# Add a Knowledge Base (/docs/add-a-knowledge-base)
# Add a Knowledge Base [#add-a-knowledge-base]
Transform a standard chat assistant into a **Knowledge Assistant**. By indexing your documents (PDFs, Markdown, etc.), your agent retrieves relevant passages at query time to provide grounded, accurate answers. This technique is known as **RAG (Retrieval-Augmented Generation)**.
## How RAG Works [#how-rag-works]
**Ingest**
— Documents are parsed and split into atomic chunks.
**Embed**
— Each chunk is turned into a mathematical vector by an embedding provider.
**Retrieve**
— At query time, the user's question is embedded and matched against the most similar chunks.
**Generate**
— The retrieved chunks are injected into the LLM's context for a grounded response.
## Steps to Enable RAG [#steps-to-enable-rag]
### Create an Embedding Provider [#create-an-embedding-provider]
Go to **Providers → Add Provider**.
* **Category**: `Embedding`
* **Type**: e.g., `OpenAI`, `Ollama`, `Jina`, `Cohere`
* **Sub Type**: `text-embedding-3-small` (Recommended for OpenAI)
Click **Save**. This provider handles the "translation" of your text into mathematical vectors.
### Configure your Store [#configure-your-store]
Edit your existing Store and link the embedding provider:
* **Embedding Provider**: Select the provider you just created.
* **Knowledge Count**: Set to `3` initially (adjust later based on accuracy).
### Upload and Index Documents [#upload-and-index-documents]
Go to **Files → Upload**.
1. Select your files (PDF, Docx, MD, etc.).
2. Assign them to your Store.
3. Click **Upload**.
Monitor the **Status** column. Once it says **Finished**, the content is indexed and ready for retrieval.
### Verify in Chat [#verify-in-chat]
Open the Chat UI for your Store. Ask a question specifically about the uploaded content.
*"Based on the uploaded manual, what is the procedure for X?"*
## Tuning for Accuracy [#tuning-for-accuracy]
If the agent is missing information or giving vague answers, try these adjustments:
* **Increase Knowledge Count**: Try raising it to `5` or `7` to give the model more context.
* **Adjust Split Strategy**: If your files are highly structured (like FAQs), switch the Store's **Split Provider** to `QA` and re-upload.
* **Refine System Prompt**: Tell the agent explicitly: *"Always prioritize information from the knowledge base. If the answer is not in the documents, say you don't know."*
## Next Steps [#next-steps]
# Tools & Automation (/docs/add-tools-and-automation)
# Tools & Automation [#tools--automation]
A standard LLM is limited to text generation. By adding **Tools**, you give your agent the ability to interact with the world: search the internet, browse live websites, execute code, or call external APIs.
OpenAgent supports three primary ways to extend an agent's capabilities.
## Built-in Tools [#built-in-tools]
Built-in tool implementations are pre-packaged with OpenAgent. Create Tool records for the capabilities you want, configure any credentials on those records, then attach the records to a Store.
Go to
**Tools → Add Tool**
.
Select a built-in tool type such as
`web_search`
,
`web_browser`
, or
`shell`
.
Edit your Store and add the Tool record to
**Tools**
.
Save and test in Chat.
*Example: "Search the latest news about OpenAgent and summarize it."*
**Security Note:** Tools like `Shell` or `Browser` can perform actions on your host machine. Only enable them in trusted, sandboxed environments.
## MCP (Model Context Protocol) [#mcp-model-context-protocol]
OpenAgent supports [MCP](/docs/connectors/tools/mcp), an open standard for connecting AI models to external data and tools. This is the recommended way to connect your own databases or APIs.
Go to
**Servers → Add Server**
and enter your MCP server's URL (and optional Bearer token).
Click
**Sync**
to discover available tools, then allow/deny as needed.
Edit the
**Store**
and set
**MCP Server**
to this server.
## Skills and Marketplace [#skills-and-marketplace]
Skills are reusable instruction packages that teach an agent how to perform a specific task or operate a tool. OpenAgent loads skills from the local skills folder during startup and can install skills from the Skill Marketplace. After a skill is available, attach it to a Store through the Store's **Skills** field.
Enabled Skills are exposed to the agent as a catalog plus a `load_skill` tool. This lets the agent load full Skill instructions only when a task needs them, instead of injecting every Skill into every prompt.
Stores can also enable **Experience Review** to learn from completed tool-heavy tasks. When a task produces a reusable workflow, OpenAgent can create a new Skill or update an existing one for future runs.
Built-in Skills are synchronized at startup from OpenAgent's bundled or local skills folder. A built-in Skill with the same name is replaced by the bundled version on restart, so customize workflows by creating separate custom Skills instead of editing bundled built-ins in place.
## Which one should I choose? [#which-one-should-i-choose]
| Method | Best for | Setup Effort |
| ------------------ | --------------------------------------------------- | ------------ |
| **Built-in Tools** | General web search, simple browsing, or shell tasks | Low |
| **MCP** | Connecting your own proprietary APIs or databases | Medium |
| **Skills** | Reusable task instructions and workflows | Low |
## Next Steps [#next-steps]
# MCP Servers (/docs/agent-providers)
# MCP Servers [#mcp-servers]
OpenAgent connects to external tool backends using the **MCP (Model Context Protocol)** standard. MCP servers are configured as **Server** records (under the **Servers** menu) and attached to a Store via the **MCP Server** field.
MCP configuration has moved from the Providers area to a dedicated **Servers** section. If you previously used "Agent Provider" in older versions, create a Server record instead.
## Setting up an MCP server [#setting-up-an-mcp-server]
1. Go to **Servers → Add Server**
2. Fill in:
* **Name**: unique identifier (e.g., `my-tools`)
* **URL**: the MCP server's StreamableHTTP endpoint (e.g., `https://tools.example.com/mcp`)
* **Token**: optional Bearer token for authenticated servers
3. Save, then click **Sync** to fetch the server's tool list
4. Review the discovered tools — toggle **IsAllowed** off for any tools you want to block
5. Edit the Store and set **MCP Server** to this server record
## Transport [#transport]
OpenAgent uses **StreamableHTTP** transport to connect to MCP servers. The server must expose an HTTP endpoint implementing the MCP protocol. The token, if set, is sent as `Authorization: Bearer `.
## Tool allow-listing [#tool-allow-listing]
After syncing, each tool discovered from the server appears with an **IsAllowed** flag. Disabling a tool removes it from the model's tool list for all chats using this server. Use this to expose only the tools relevant to a Store's purpose.
## One MCP server per Store [#one-mcp-server-per-store]
A Store can have exactly one MCP Server at a time.
If you need tools from multiple MCP servers, either:
1. **Combine tools into one server** — aggregate tools from multiple upstreams into a single MCP endpoint
2. **Proxy through a single MCP server** — use a routing server that delegates calls to multiple backends
## MCP vs. built-in tools [#mcp-vs-built-in-tools]
An MCP Server and Tool records for built-in tools can coexist. The model sees all tools from both sources in one unified list. OpenAgent routes each tool call to the appropriate backend transparently.
## Testing the connection [#testing-the-connection]
After attaching an MCP server, open a chat with the Store and ask the agent to perform a task the tools handle. Tool calls appear inline in the chat — you'll see the tool name, arguments, and result.
If tools aren't being called:
1. Verify the MCP server URL is reachable from OpenAgent's server (not just your local machine)
2. Check tool descriptions — vague descriptions cause the model to skip tools it should use
3. Add an explicit instruction in the system prompt: "When the user asks about X, always use the `tool_name` tool"
## Related pages [#related-pages]
* [MCP Servers (full reference)](/docs/connectors/mcp-servers) — detailed setup guide with tool description best practices
* [Built-in Tools](/docs/connectors/tools/builtin-tools) — tools that ship with OpenAgent and need no external server
# Build a Chat Assistant (/docs/build-a-chat-assistant)
# Build a Chat Assistant [#build-a-chat-assistant]
This guide walks you through creating a simple assistant that can hold multi-turn conversations — the foundation for all other OpenAgent capabilities.
**Outcome:** A functional chat UI where you can send messages and receive AI responses.
## Prerequisites [#prerequisites]
* OpenAgent is running and you have access to the Admin UI.
* An API key for a model provider (OpenAI, Anthropic, DeepSeek, etc.).
## Step 1: Connect a Model Provider [#step-1-connect-a-model-provider]
First, give OpenAgent access to an LLM "brain".
Navigate to **Providers → Add Provider**.
Configure the provider:
* **Category**: Select `Model`.
* **Type**: Choose your provider (e.g., `OpenAI`, `DeepSeek`, `Anthropic`).
* **Provider URL**: (Optional) For local models or proxies.
* **API Key**: Enter your secret key.
* **Sub Type**: Enter a model ID supported by the provider (e.g., `gpt-4.1`, `deepseek-v4-flash`).
Click **Save**.
## Step 2: Initialize your Agent (Store) [#step-2-initialize-your-agent-store]
In OpenAgent, an agent's identity and configuration are stored in a **Store**.
Navigate to **Stores → Add Store**.
Configure the core settings:
* **Name**: A unique internal ID (e.g., `my-assistant`).
* **Display Name**: The name users will see in the chat header.
* **Model Provider**: Select the provider you created in Step 1.
* **System Prompt**: Define how your agent should behave.
Example:
```
You are a helpful assistant. Keep your answers concise and professional.
```
Click **Save**.
## Step 3: Start Chatting [#step-3-start-chatting]
Click the **Chat** icon in the sidebar or the chat button next to your Store.
Select your agent from the dropdown and send a test message.
**Milestone Reached:** You now have a functional chat assistant backed by your chosen LLM.
## Next Steps [#next-steps]
# Install (/docs/install)
# Quick Start [#quick-start]
The goal of this guide is to reach the **"First Message"** milestone as quickly as possible. OpenAgent runs on port `14000` by default.
## Prerequisites [#prerequisites]
Before you begin, make sure you have:
* **OpenAgent installed** — choose a deployment method below: one-line installer, Docker, or development setup.
* **An API key** — get one from a model provider like DeepSeek, OpenAI, Anthropic, or any supported provider.
## Deploy the Infrastructure [#deploy-the-infrastructure]
**Zero installation required.** OpenAgent ships as a single self-contained binary. Download it, double-click (or run from the terminal), and it's live — no package managers, no runtimes, no Docker.
In single-binary mode, OpenAgent can run with the embedded SQLite database by default. Use an external MySQL database only when your deployment requires it.
### Choose Your Deployment Method [#choose-your-deployment-method]
**macOS / Linux / WSL**
```bash
curl -fsSL https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.sh | bash
```
**Windows (PowerShell)**
```powershell
irm https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.ps1 | iex
```
Download the latest binary from the [GitHub Releases page](https://github.com/the-open-agent/openagent/releases).
Release binaries embed the default web assets, provider logos, store avatars, and virtual figure assets, so a fresh offline binary can render the built-in UI without fetching those static files from the source tree.
**Windows** — download `openagent_windows_x86.exe` and double-click it, or run from PowerShell:
```powershell
.\openagent_windows_x86.exe
```
No WSL, no Docker, no additional dependencies. Runs natively on Windows 10/11.
**Linux** — download the binary for your platform and run:
```bash
chmod +x openagent_linux_x86
./openagent_linux_x86
```
**macOS** — download the binary for your platform (`openagent_darwin_x86` for Intel, `openagent_darwin_arm64` for Apple Silicon) and run:
```bash
chmod +x openagent_darwin_arm64
./openagent_darwin_arm64
```
```bash
docker run -d -p 14000:14000 --name openagent casbin/openagent
```
Requires Go 1.25+, Node.js 20+, Yarn 1.x, and MySQL 8.0+.
```bash
git clone https://github.com/the-open-agent/openagent.git
cd openagent
go run main.go
# Separate terminal
cd web && yarn install && yarn start
```
Once the server is running, navigate to **`http://localhost:14000`**.
### Configure a Provider [#configure-a-provider]
Navigate to **Providers → Add Provider**.
* **Category**: `Model`
* **Type**: `DeepSeek` (Recommended for cost) or `OpenAI`
* **API Key**: Enter your credentials.
* **Model (Sub Type)**: Select `deepseek-v4-flash` or a model ID supported by your provider.
### Initialize an Agent (Store) [#initialize-an-agent-store]
Navigate to **Stores → Add Store**.
* **Name**: `primary-assistant`
* **Model Provider**: Select the provider from the previous step.
* **System Prompt**: *"You are a professional research assistant."*
### Validate with Chat [#validate-with-chat]
Open the **Chat** interface from the sidebar. Select your agent and send:
> "Hello OpenAgent, identify yourself."
**Milestone Reached:** You now have a functional, self-hosted orchestration engine.
## Activate Knowledge Retrieval (RAG) [#activate-knowledge-retrieval-rag]
Transition from a standard LLM to a **Knowledge Agent** by indexing your own documents.
### Add an Embedding Provider [#add-an-embedding-provider]
Go to **Providers → Add Provider**.
* **Category**: `Embedding`
* **Type**: e.g., `OpenAI`
* **Sub Type**: `text-embedding-3-small` (Recommended)
This provider handles the "translation" of your text into mathematical vectors.
### Link Knowledge to Agent [#link-knowledge-to-agent]
Edit your Store and assign the **Embedding Provider**. Set **Knowledge Count** to `5` (Recommended for 2026 models) to define retrieval density.
### Ingest Documents [#ingest-documents]
Go to **Files → Upload**, drop your PDFs/Markdown files, and assign them to the Store. Once the status reaches **Finished**, the agent is grounded in your data.
## What to do next [#what-to-do-next]
# Introduction (/docs/introduction)
# Introduction [#introduction]
> *"Build once, deploy everywhere."*
OpenAgent is a single-binary AI agent platform — download, run, and your first agent is live in minutes.
Orchestration, RAG, MCP, and tool-calling — all self-hosted, backed by your own data.
## What is OpenAgent? [#what-is-openagent]
OpenAgent is a **self-hosted AI agent platform** that connects your data, tools, and models into a production-ready system. Unlike simple chat interfaces, OpenAgent provides:
* **Managed RAG**: Turn PDFs and wikis into grounded context with automatic parsing and semantic search.
* **Model Orchestration**: Switch between 28+ providers with standardized abstractions for models, embeddings, and storage.
* **Tool Integration**: Extend agents with MCP servers and built-in automation.
* **Privacy & Access Control**: Role-based access control (RBAC), SSO integration, and comprehensive audit logs.
**Who is it for?** Developers and teams who want a private, self-hosted AI assistant that can reason over their own data — without relying on hosted APIs.
**What makes it different?**
* **Single Binary**: Ships as one executable — download and double-click to run. No installation wizard, no dependencies to manage.
* **Self-hosted**: Runs on your own infrastructure. Full control, no vendor lock-in.
* **Provider Agnostic**: Standardized abstraction for models, embeddings, and storage.
* **Scalable Workflows**: Connect agents to external tools, data, and automation through a consistent provider model.
* **Audit Ready**: Track every token, record every tool call, and monitor agent performance at scale.
## Quick start [#quick-start]
The simplest way to run OpenAgent is to **download the binary** from the [Releases page](https://github.com/the-open-agent/openagent/releases) and double-click it. No installation required — it works natively on Windows, macOS, and Linux.
**Windows** — download `openagent_windows_x86.exe` and run it directly. No WSL, no Docker needed.
**Linux** — download the binary and make it executable:
```bash
chmod +x openagent_linux_x86 && ./openagent_linux_x86
```
**macOS** — download the binary for your chip (`openagent_darwin_arm64` for Apple Silicon, `openagent_darwin_x86` for Intel) and run:
```bash
chmod +x openagent_darwin_arm64 && ./openagent_darwin_arm64
```
Once running, navigate to **`http://localhost:14000`**.
Navigate to **Providers → Add Provider**.
* **Category**: `Model`
* **Type**: `DeepSeek` (Recommended for cost) or `OpenAI`
* **API Key**: Enter your credentials.
* **Model (Sub Type)**: Select a supported model ID.
Navigate to **Stores → Add Store**.
* **Name**: `primary-assistant`
* **Model Provider**: Select the provider from Step 2.
* **System Prompt**: *"You are a professional research assistant."*
Open the **Chat** interface from the sidebar. Select your agent and send a test message.
**Milestone Reached:** You now have a functional, self-hosted AI orchestration engine.
Need a deeper walkthrough? See [Build a Chat Assistant](/docs/build-a-chat-assistant).
## Start here [#start-here]
**Note on Migration:** This documentation covers the new Agent-first architecture. Legacy cloud and multimedia modules from previous versions are now deprecated.
# Install (/docs/quick-start)
# Quick Start [#quick-start]
The goal of this guide is to reach the **"First Message"** milestone as quickly as possible. OpenAgent runs on port `14000` by default.
## Prerequisites [#prerequisites]
Before you begin, make sure you have:
Choose a deployment method below: one-line installer, Docker, or development setup.
Get an API key from a model provider like DeepSeek, OpenAI, Anthropic, or any supported provider.
## Deploy the Infrastructure [#deploy-the-infrastructure]
### Choose Your Deployment Method [#choose-your-deployment-method]
**macOS / Linux / WSL**
```bash
curl -fsSL \
https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.sh | bash
```
**Windows (PowerShell)**
```powershell
irm https://raw.githubusercontent.com/the-open-agent/openagent/master/scripts/install.ps1 | iex
```
```bash
docker run -d -p 14000:14000 --name openagent casbin/openagent
```
Requires Go 1.25+, Node.js 20+, Yarn 1.x, and MySQL 8.0+.
```bash
git clone https://github.com/the-open-agent/openagent.git
cd openagent
go run main.go
# Separate terminal
cd web && yarn install && yarn start
```
Once the server is running, navigate to **`http://localhost:14000`**.
### Configure a Provider [#configure-a-provider]
Navigate to **Providers → Add Provider**.
* **Category**: `Model`
* **Type**: `DeepSeek` (Recommended for cost) or `OpenAI`
* **API Key**: Enter your credentials.
* **Model (Sub Type)**: Select `deepseek-v4-flash` or a model ID supported by your provider.
### Initialize an Agent (Store) [#initialize-an-agent-store]
Navigate to **Stores → Add Store**.
* **Name**: `primary-assistant`
* **Model Provider**: Select the provider from the previous step.
* **System Prompt**: *"You are a professional research assistant."*
### Validate with Chat [#validate-with-chat]
Open the **Chat** interface from the sidebar. Select your agent and send:
> "Hello OpenAgent, identify yourself."
**Milestone Reached:** You now have a functional, self-hosted orchestration engine.
## Activate Knowledge Retrieval (RAG) [#activate-knowledge-retrieval-rag]
Transition from a standard LLM to a **Knowledge Agent** by indexing your own documents.
### Add an Embedding Provider [#add-an-embedding-provider]
Go to **Providers → Add Provider**.
* **Category**: `Embedding`
* **Type**: e.g., `OpenAI`
* **Sub Type**: `text-embedding-3-small` (Recommended)
This provider handles the "translation" of your text into mathematical vectors.
### Link Knowledge to Agent [#link-knowledge-to-agent]
Edit your Store and assign the **Embedding Provider**. Set **Knowledge Count** to `5` (Recommended for 2026 models) to define retrieval density.
### Ingest Documents [#ingest-documents]
Go to **Files → Upload**, drop your PDFs/Markdown files, and assign them to the Store. Once the status reaches **Finished**, the agent is grounded in your data.
## What to do next [#what-to-do-next]
# Tools & Automation (/docs/tools-and-automation)
# Tools & Automation [#tools--automation]
A standard LLM is limited to text generation. By adding **Tools**, you give your agent the ability to interact with the world: search the internet, browse live websites, execute code, or call external APIs.
OpenAgent supports three primary ways to extend an agent's capabilities.
## Built-in Tools [#built-in-tools]
Built-in tool implementations are pre-packaged with OpenAgent. Create Tool records for the capabilities you want, configure any credentials on those records, then attach the records to a Store.
Go to
**Tools → Add Tool**
.
Select a built-in tool type such as
`web_search`
,
`web_browser`
, or
`shell`
.
Edit your Store and add the Tool record to
**Tools**
.
Save and test in Chat.
*Example: "Search the latest news about OpenAgent and summarize it."*
**Security Note:** Tools like `Shell` or `Browser` can perform actions on your host machine. Only enable them in trusted, sandboxed environments.
## MCP (Model Context Protocol) [#mcp-model-context-protocol]
OpenAgent supports [MCP](/docs/connectors/tools/mcp), an open standard for connecting AI models to external data and tools. This is the recommended way to connect your own databases or APIs.
Go to
**Servers → Add Server**
and enter your MCP server's URL (and optional Bearer token).
Click
**Sync**
to discover available tools, then allow/deny as needed.
Edit the
**Store**
and set
**MCP Server**
to this server.
## Skills and Marketplace [#skills-and-marketplace]
Skills are reusable instruction packages that teach an agent how to perform a specific task or operate a tool. OpenAgent loads skills from the local skills folder during startup and can install skills from the Skill Marketplace. After a skill is available, attach it to a Store through the Store's **Skills** field.
Enabled Skills are exposed to the agent as a catalog plus a `load_skill` tool. This lets the agent load full Skill instructions only when a task needs them, instead of injecting every Skill into every prompt.
Stores can also enable **Experience Review** to learn from completed tool-heavy tasks. When a task produces a reusable workflow, OpenAgent can create a new Skill or update an existing one for future runs.
Built-in Skills are synchronized at startup from OpenAgent's bundled or local skills folder. A built-in Skill with the same name is replaced by the bundled version on restart, so customize workflows by creating separate custom Skills instead of editing bundled built-ins in place.
## Which one should I choose? [#which-one-should-i-choose]
| Method | Best for | Setup Effort |
| ------------------ | --------------------------------------------------- | ------------ |
| **Built-in Tools** | General web search, simple browsing, or shell tasks | Low |
| **MCP** | Connecting your own proprietary APIs or databases | Medium |
| **Skills** | Reusable task instructions and workflows | Low |
## Next Steps [#next-steps]
# Introduction (/docs/what-is-openagent)
# Visitors (/docs/admin/activities)
# Visitors [#visitors]
**Visitors** is the high-level activity view in the product UI.
Use it when you want a quick sense of what has been happening across the system before drilling down into detailed logs.
For authoritative auditing data, use [Logs](/docs/auditing-logs/logs). Visitors is the lighter operational overview; Logs is the detailed record.
# AI Usage (/docs/admin/ai-usage)
# AI Usage [#ai-usage]
**AI Usage** gives you the operational view of token consumption and cost over time.
This is where teams answer questions like:
* Which Store is consuming the most tokens?
* How much did this deployment cost this week?
* Is usage spiking unexpectedly?
The detailed explanation for usage and cost tracking already lives in [Logs](/docs/auditing-logs/logs). This page exists to match the product navigation and point you there.
# Enterprise SSO (/docs/admin/enterprise-sso)
# Enterprise SSO & User Management [#enterprise-sso--user-management]
User accounts and authentication are managed through [Casdoor](https://casdoor.org), the SSO service bundled in OpenAgent's stack. The OpenAgent admin panel exposes the controls you need day-to-day — roles, account status, permissions, and sessions — without requiring you to navigate Casdoor directly for most operations.
## User roles [#user-roles]
OpenAgent has three roles:
### Admin [#admin]
Full access to the admin panel and all resources. Admins can:
* Create, edit, and delete Stores, Providers, and Files
* View all Chats and Messages across all users
* Browse Records and Usage data
* Manage user accounts and permissions
The built-in `admin` account is created during setup and cannot be deleted. You can create additional admin accounts for daily use.
### Regular User [#regular-user]
Access to the chat interface only. Regular users can:
* Chat with any Store that has been shared with them (or that allows public access)
* View their own conversation history
* Provide feedback on messages (like/dislike)
Regular users cannot access the admin panel, view other users' conversations, or modify any configuration.
### Chat Admin [#chat-admin]
An intermediate role that grants access to conversation management without full admin access. Chat admins can:
* View all Chats across all users
* Read any conversation thread
* Useful for support, moderation, or QA roles
Chat admins cannot modify Stores, Providers, or user accounts.
## Managing users [#managing-users]
Go to **Users** in the admin panel to see all accounts in the organization. From the user list you can:
**Enable or disable accounts** — disable login for an account without deleting it. The user's conversations, Chats, and Messages are preserved. Re-enabling restores access.
**Reset passwords** — generates a new password or sends a reset link, depending on the authentication configuration.
**Grant or revoke admin status** — promote a user to Admin or remove admin privileges. Takes effect quickly; the user may need to refresh.
**Set role** — change a user between Regular User and Chat Admin.
For SSO-connected deployments (LDAP, OIDC, SAML), user accounts are created automatically on first login. You can still manage roles and permissions in OpenAgent after the account is created.
## Permissions [#permissions]
Fine-grained permission rules are configured in the **Permissions** section. A permission rule specifies:
* **Who** — a specific user, a role, or a group
* **What** — which resource type (Store, Provider, File, etc.)
* **Action** — read, write, or admin
Permissions layer on top of roles — they add restrictions or grants on top of what the role provides. An Admin always has full access regardless of permission rules. For regular users, permissions can restrict or expand what they see.
**Example use cases:**
* Give a specific user read access to a particular Store without making them a Chat Admin
* Restrict access to a sensitive Store to a named list of users
* Allow a team to manage their own Providers without accessing other teams' resources
For most deployments, the three-role model (Admin / Regular User / Chat Admin) is sufficient. Explicit permission rules are most useful when you're running a multi-team deployment where different groups own different Stores.
## Organizations [#organizations]
Every resource in OpenAgent — Stores, Providers, Files, Vectors — has an `owner` field that stores the organization name. The default organization is `built-in`.
Resources are scoped to their organization: a user in organization A cannot see or access resources owned by organization B. This enables multi-tenant deployments where multiple independent groups share the same OpenAgent instance without visibility into each other's data.
To create or manage organizations, go to Casdoor directly (accessible at the Casdoor admin URL configured in your deployment). Once an organization exists, you can assign it as the owner when creating resources in OpenAgent.
All resources created through the admin panel are assigned to the organization of the currently logged-in admin. If you're setting up a multi-tenant environment, make sure you're logged in as the correct organization's admin when creating resources.
## Authentication configuration [#authentication-configuration]
OpenAgent supports multiple authentication methods through Casdoor:
* **Local username/password** — default; accounts are stored in Casdoor's database
* **OAuth 2.0 / OIDC** — connect to Google, GitHub, Microsoft, or any OIDC provider
* **LDAP / Active Directory** — enterprise directory integration
* **SAML 2.0** — enterprise SSO
Configure authentication providers in Casdoor at the identity provider level. OpenAgent consumes Casdoor's auth layer without needing per-method configuration.
## Sessions [#sessions]
Active sessions are listed under **Sessions** in the admin panel. Each session shows the user, creation time, and last active time.
Admins can revoke any session. Revocation takes effect immediately — the user's next API request will be rejected with a 401 and they will be redirected to the login page.
Session expiry is configured in Casdoor. The default is typically 24 hours of inactivity.
## Default admin account [#default-admin-account]
The first admin account is configured during setup via environment variables:
```
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-password
```
Change the default password immediately after first login. The built-in `admin` account cannot be deleted, but you can change its password and create additional admin accounts for daily use.
# Resources (/docs/admin/resources)
# Resources [#resources]
**Resources** provides access to manage files and documents that are part of the knowledge base system.
This page allows you to view, organize, and manage the resources that power your AI agents' knowledge retrieval capabilities.
For detailed information about working with files and knowledge bases, see [Files](/docs/knowledge-base/files) and [Vectors](/docs/knowledge-base/vectors).
# Settings (/docs/admin/settings)
# Settings [#settings]
**Settings** (configured via **Sites** in the admin panel) controls the entire built-in site experience: branding, authentication, navigation, and runtime behavior.
## Branding & Appearance [#branding--appearance]
| Field | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Theme Color** | Primary accent color for the UI (hex code, e.g. `#4f46e5`). |
| **HTML Title** | Browser tab title for the site (e.g. `"MyCompany AI"`). |
| **Favicon URL** | URL to a `.ico` or `.png` favicon. |
| **Logo URL** | URL to the logo image shown in the navigation bar. |
| **Navbar HTML** | Custom HTML injected into the navigation bar. |
| **Footer HTML** | Custom HTML for the page footer. |
| **Static Base URL** | Base URL for serving static assets from a CDN or custom domain. |
| **Nav Items** | List of navigation items to show in the site sidebar. Controls which product areas are visible. |
| **Endpoint** | Public HTTPS base URL for this OpenAgent site. Hub cards use it when linking to Stores hosted by another OpenAgent database. If the built-in site has no public endpoint, OpenAgent can auto-fill it from the first public request host. |
| **Hub Description** | Custom subtitle shown at the top of the Hub page. Leave it empty to use the default Hub description. |
Custom **Navbar HTML** is rendered in the management shell after settings are loaded, so branding and navigation snippets can be updated from the site record without rebuilding the frontend.
## Authentication [#authentication]
| Field | Description |
| ------------------------ | ----------------------------------------------------------------- |
| **Issuer** | OIDC issuer URL of the identity provider (e.g. Casdoor endpoint). |
| **Client ID** | OAuth2 application client ID. |
| **Client Secret** | OAuth2 application client secret. |
| **Casdoor Endpoint** | Casdoor service URL (backward-compatible alias for Issuer). |
| **Casdoor Organization** | The Casdoor organization name to authenticate against. |
| **Casdoor Application** | The Casdoor application name. |
For standard Casdoor deployments, setting **Issuer**, **Client ID**, and **Client Secret** is sufficient. The Casdoor-specific fields are for backward compatibility.
## Runtime Configuration [#runtime-configuration]
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **IP Parsing Mode** | How client IPs are extracted from requests. Options: `""` (direct), `"X-Forwarded-For"`, `"X-Real-IP"`. Set appropriately when running behind a reverse proxy. |
| **Parent DB Name** | Database name for a parent OpenAgent instance. Use it when this site should read or sync shared parent-instance data in a multi-instance deployment. |
| **Hub DB Names** | Comma-separated database names whose published Stores should also appear in this site's Hub. Each remote database should have a public **Endpoint** configured on its built-in site record. |
| **Socks5 Proxy** | SOCKS5 proxy address (e.g. `127.0.0.1:1080`) for outbound requests. Used by tools that make external HTTP calls (web\_search, web\_fetch, etc.) when **Enable Proxy** is set on the Tool record. |
| **Log Config** | Logging configuration string (BeeGo log config format). |
### Hub Federation [#hub-federation]
Use **Hub DB Names** when one OpenAgent site should act as a catalog for Stores published by multiple OpenAgent databases. The field accepts database names separated by commas. OpenAgent reads Stores whose **Publish State** is **Published** from each listed database and merges them into the Hub response.
Each contributing site should have a public **Endpoint** on its built-in site record. Remote Hub cards use that endpoint to build the chat link, so users land on the OpenAgent instance that actually hosts the Store. When **Endpoint** is empty or points to a non-public host, OpenAgent can auto-fill it from the first public request host and stores it as an HTTPS URL.
Set **Hub Description** on the Hub site when the catalog needs deployment-specific copy, such as an internal marketplace description or school/course context. This text only changes the Hub page header; Store cards still use each Store's own profile fields.
## Feature Flags [#feature-flags]
| Field | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Check User Balance** | When enabled, enforces token/credit balance checks before processing messages. Useful for metered deployments. |
## Applying changes [#applying-changes]
Settings changes take effect immediately for new sessions. Users who are currently logged in may need to refresh their browser to pick up branding changes.
# Sites (/docs/admin/sites)
# Sites [#sites]
**Sites** is the admin panel section where you manage the built-in site configuration for an OpenAgent deployment. Each site record controls the full user-facing experience: branding, authentication, navigation, and runtime behavior.
The full field reference for site configuration is documented in [Settings](/docs/admin/settings).
# Swagger (/docs/admin/swagger)
# Swagger [#swagger]
OpenAgent includes a **Swagger** entry for browsing and testing API endpoints directly.
Use Swagger when you want to:
* Inspect available API routes
* Test requests manually
* Understand request and response shapes before integrating programmatically
Swagger is the fastest way to explore the API interactively without writing client code first.
The built-in Swagger route redirects to the generated API explorer path, so the sidebar entry and direct Swagger URL stay usable even when static routing changes.
# System Info (/docs/admin/system-info)
# System Info [#system-info]
**System Info** surfaces environment and runtime details about the current OpenAgent deployment.
Use it when you need to quickly inspect:
* Version and build information
* Build metadata reported by the running binary, such as commit, build time, and build mode when available
* Runtime environment details
* High-level system status
# AI Usage (/docs/admin/usages)
# AI Usage [#ai-usage]
**AI Usage** gives you the operational view of token consumption and cost over time.
This is where teams answer questions like:
* Which Store is consuming the most tokens?
* How much did this deployment cost this week?
* Is usage spiking unexpectedly?
The detailed explanation for usage and cost tracking already lives in [Logs](/docs/auditing-logs/logs). This page exists to match the product navigation and point you there.
# Users (/docs/admin/users)
# Users [#users]
User accounts and authentication are managed through [Casdoor](https://casdoor.org), the SSO service bundled in OpenAgent's stack. The OpenAgent admin panel exposes the controls you need day-to-day — roles, account status, permissions, and sessions — without requiring you to navigate Casdoor directly for most operations.
## User roles [#user-roles]
OpenAgent has three roles:
### Admin [#admin]
Full access to the admin panel and all resources. Admins can:
* Create, edit, and delete Stores, Providers, and Files
* View all Chats and Messages across all users
* Browse Records and Usage data
* Manage user accounts and permissions
The built-in `admin` account is created during setup and cannot be deleted. You can create additional admin accounts for daily use.
### Regular User [#regular-user]
Access to the chat interface only. Regular users can:
* Chat with any Store that has been shared with them (or that allows public access)
* View their own conversation history
* Provide feedback on messages (like/dislike)
Regular users cannot access the admin panel, view other users' conversations, or modify any configuration.
### Chat Admin [#chat-admin]
An intermediate role that grants access to conversation management without full admin access. Chat admins can:
* View all Chats across all users
* Read any conversation thread
* Useful for support, moderation, or QA roles
Chat admins cannot modify Stores, Providers, or user accounts.
## Managing users [#managing-users]
Go to **Users** in the admin panel to see all accounts in the organization. From the user list you can:
**Enable or disable accounts** — disable login for an account without deleting it. The user's conversations, Chats, and Messages are preserved. Re-enabling restores access.
**Reset passwords** — generates a new password or sends a reset link, depending on the authentication configuration.
**Grant or revoke admin status** — promote a user to Admin or remove admin privileges. Takes effect quickly; the user may need to refresh.
**Set role** — change a user between Regular User and Chat Admin.
For SSO-connected deployments (LDAP, OIDC, SAML), user accounts are created automatically on first login. You can still manage roles and permissions in OpenAgent after the account is created.
## Permissions [#permissions]
Fine-grained permission rules are configured in the **Permissions** section. A permission rule specifies:
* **Who** — a specific user, a role, or a group
* **What** — which resource type (Store, Provider, File, etc.)
* **Action** — read, write, or admin
Permissions layer on top of roles — they add restrictions or grants on top of what the role provides. An Admin always has full access regardless of permission rules. For regular users, permissions can restrict or expand what they see.
**Example use cases:**
* Give a specific user read access to a particular Store without making them a Chat Admin
* Restrict access to a sensitive Store to a named list of users
* Allow a team to manage their own Providers without accessing other teams' resources
For most deployments, the three-role model (Admin / Regular User / Chat Admin) is sufficient. Explicit permission rules are most useful when you're running a multi-team deployment where different groups own different Stores.
## Organizations [#organizations]
Every resource in OpenAgent — Stores, Providers, Files, Vectors — has an `owner` field that stores the organization name. The default organization is `built-in`.
Resources are scoped to their organization: a user in organization A cannot see or access resources owned by organization B. This enables multi-tenant deployments where multiple independent groups share the same OpenAgent instance without visibility into each other's data.
To create or manage organizations, go to Casdoor directly (accessible at the Casdoor admin URL configured in your deployment). Once an organization exists, you can assign it as the owner when creating resources in OpenAgent.
All resources created through the admin panel are assigned to the organization of the currently logged-in admin. If you're setting up a multi-tenant environment, make sure you're logged in as the correct organization's admin when creating resources.
## Authentication configuration [#authentication-configuration]
OpenAgent supports multiple authentication methods through Casdoor:
* **Local username/password** — default; accounts are stored in Casdoor's database
* **OAuth 2.0 / OIDC** — connect to Google, GitHub, Microsoft, or any OIDC provider
* **LDAP / Active Directory** — enterprise directory integration
* **SAML 2.0** — enterprise SSO
Configure authentication providers in Casdoor at the identity provider level. OpenAgent consumes Casdoor's auth layer without needing per-method configuration.
## Sessions [#sessions]
Active sessions are listed under **Sessions** in the admin panel. Each session shows the user, creation time, and last active time.
Admins can revoke any session. Revocation takes effect immediately — the user's next API request will be rejected with a 401 and they will be redirected to the login page.
Session expiry is configured in Casdoor. The default is typically 24 hours of inactivity.
## Default admin account [#default-admin-account]
The first admin account is configured during setup via environment variables:
```
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-password
```
Change the default password immediately after first login. The built-in `admin` account cannot be deleted, but you can change its password and create additional admin accounts for daily use.
# Visitors (/docs/admin/visitors)
# Visitors [#visitors]
**Visitors** is the high-level activity view in the product UI.
Use it when you want a quick sense of what has been happening across the system before drilling down into detailed logs.
For authoritative auditing data, use [Logs](/docs/auditing-logs/logs). Visitors is the lighter operational overview; Logs is the detailed record.
# Chat (/docs/agent-page/chat)
# Chat [#chat]
The **Chat** tab embeds the full chat experience directly in the [Agent page](/docs/agent-page), so users can try the agent without navigating away. It sits right after **Overview** in the tab bar and behaves exactly like the standalone chat page — streaming responses, inline tool calls, attachments, and follow-up suggestions all work the same way.
Unlike the standalone page, the embedded chat stays put: auto-selecting or starting a chat updates the conversation in place without changing the page URL or leaving the Chat tab. The tab itself is still deep-linkable at `/agents/{owner}/{storeName}/chat`.
For the full request lifecycle and chat features, see the [Chat reference](/docs/chat).
# Files (/docs/agent-page/files)
# Files [#files]
The **Files** tab shows the agent's knowledge base as a file tree — the same tree surfaced at the top of the [Overview](/docs/agent-page/overview) tab. Use it to inspect which documents back the agent before starting a conversation.
For how files are uploaded, embedded, and retrieved, see the [Knowledge Base → Files](/docs/knowledge-base/files) reference.
# Agent Page (/docs/agent-page)
# Agent Page [#agent-page]
Every published Store has a public **Agent page** at `/agents/{owner}/{storeName}`. Users reach it by selecting a card on the [Hub](/docs/basic/stores#hub-publishing). It is a read-only landing page for inspecting an agent — its profile, files, activity, and community — before starting a conversation.
## Header actions [#header-actions]
The page header shows the agent's avatar, display name, and author. A forked agent also shows a **Forked from** tag linking back to the original. The header exposes four actions:
* **Star** marks the agent as a favorite and increments its public star count. Starred agents appear under the Hub's **Starred** view.
* **Watch** follows the agent and increments its public watch count. Watched agents appear under the Hub's **Watching** view.
* **Fork** creates your own copy of the agent's Store configuration. Forking duplicates only the Store configuration; the file tree is not copied and usage counters (chats, messages, vectors) start from zero. You cannot fork your own agent, and you can fork any given agent only once.
* **Start Chat** opens the agent's chat page.
## Tabs [#tabs]
The page is organized into tabs, each documented on its own page:
* [Overview](/docs/agent-page/overview) — files, description, and comments at a glance.
* [Chat](/docs/agent-page/chat) — start a conversation without leaving the page.
* [Files](/docs/agent-page/files) — browse the agent's knowledge base files.
* [Issues](/docs/agent-page/issues) — a GitHub-style discussion board.
* [Security](/docs/agent-page/security) — a configuration and activity security audit.
* [Insights](/docs/agent-page/insights) — usage analytics.
* [Settings](/docs/agent-page/settings) — full configuration, visible to the agent's owner only.
## Deep-linking [#deep-linking]
Each tab has its own URL — for example `/agents/{owner}/{storeName}/issues` — and the [Insights](/docs/agent-page/insights) sub-tabs are addressable too, such as `/agents/{owner}/{storeName}/insights/traffic`. Any tab or Insights view can therefore be bookmarked or shared as a direct link.
Some tabs depend on the agent being published. Comments and other community features are unavailable for external (remote-Hub) agents and for agents whose publish state is not **Published**.
# Insights (/docs/agent-page/insights)
# Insights [#insights]
The **Insights** tab is an analytics area for understanding how an agent is used. Most views support **24h**, **7d**, and **30d** windows plus a manual refresh, and each sub-tab has its own URL (for example `/agents/{owner}/{storeName}/insights/traffic`) so a specific view can be linked to directly.
## Sub-tabs [#sub-tabs]
* **Pulse** summarizes active users, chats, messages, files added, vectors added, and top active users.
* **Contributors** shows message activity by user over time.
* **Traffic** tracks Agent page views, unique visitors, referrers, and top paths.
* **Word Cloud** aggregates common terms from the agent's messages. It respects the selected **24h**, **7d**, or **30d** window (and falls back to all messages when no window is set), and includes a minimum-frequency filter.
* **Cost** charts token usage and estimated cost, including average cost per message and peak usage.
* **Stargazers** shows a total count plus a grid of the users who starred the agent, each with their display name, avatar, and the time they starred.
* **Watchers** shows the users who watch the agent, in the same count-plus-user-grid layout.
* **Forks** lists the agents forked from this one and links through to each fork.
# Issues (/docs/agent-page/issues)
# Issues [#issues]
The **Issues** tab is a lightweight, GitHub-style discussion board scoped to a single agent. Use it to report problems, request changes, or ask questions about the agent.
## Opening an issue [#opening-an-issue]
Any signed-in user can open an issue with a **title** (required, up to 200 characters) and an optional **description** (up to 2,000 characters). New issues start in the **Open** state.
## Browsing and filtering [#browsing-and-filtering]
Issues can be filtered by **Open**, **Closed**, or **All**, with a count shown for each. Each issue in the list displays its status, title, author, and reply count.
## Replies [#replies]
Opening an issue shows its full description and a threaded reply list. Each issue has its own URL path (`/agents/{owner}/{storeName}/issues/{issueName}`), so it can be linked to directly, and reloading or using the browser's back and forward buttons preserves the open issue instead of dropping back to the list. Replies reuse the same rich comment editor as agent [comments](/docs/agent-page/overview#comments), including emoji and inline images.
## Moderation [#moderation]
The agent's owner can **edit**, **close**, **reopen**, or **delete** any issue on the agent. Closing an issue keeps it — and its replies — visible under the **Closed** filter.
# Overview (/docs/agent-page/overview)
# Overview [#overview]
The **Overview** tab is the default view of the [Agent page](/docs/agent-page). It combines the agent's content and community in a single scroll:
* **Files** — the agent's knowledge base file tree. See [Files](/docs/agent-page/files).
* **Description** — the agent's rendered README / long description.
* **About** — a sidebar with the agent's profile fields (author, affiliation, subject, grade, topic) and stats.
* **Comments** — a rich-text comment thread (below).
## Comments [#comments]
Signed-in users can leave rich-text comments on an agent. The comment editor supports:
* **Emoji** from a picker.
* **Inline images** — uploaded from the toolbar, pasted from the clipboard, or dragged into the editor, as PNG, JPEG, GIF, or WebP.
* A live **character count** with an enforced limit.
Submitted HTML is sanitized and links are rewritten to open safely in a new tab. Comments are unavailable for external agents and for agents that are not published.
Each comment shows the author's real display name and avatar with a [profile hover card](/docs/chat#user-identities).
## Moderation [#moderation]
Administrators can moderate all comments from the **Comments** page under **Admin**. It lists every comment with its target, author, content, and created time, and lets admins edit or delete individual comments.
# Security (/docs/agent-page/security)
# Security [#security]
The **Security** tab runs an automated security audit of the agent and grades the result, helping owners spot risky configuration and abusive activity. A period selector (**24h**, **7d**, **30d**), a manual **Refresh** action, and a **Data as of** timestamp control the activity portion of the report.
## Score and grade [#score-and-grade]
The report summarizes an overall **security score** and letter **grade**, with counts of checks that **Passed**, raised a **Warning**, or **Failed**. Address failed and warned checks to improve the score.
## Configuration checks [#configuration-checks]
* **Secrets in agent definition** — scans the prompt and description for hard-coded credentials (private keys, API keys, AWS/Slack/GitHub tokens, JWTs, and credential assignments).
* **API key exposure** — flags when the Store's external API key appears in a client-readable text field.
* **Content moderation list** — checks whether forbidden words are configured for input filtering.
* **File upload policy** — flags public agents that allow file uploads.
* **Public exposure** — notes whether the agent is published and reachable in the public Hub.
* **Tool & capability surface** — reports the number of enabled tools, skills, and MCP servers that expand the attack surface.
* **Co-owner access control** — reports how many owners have write access to the agent.
## Activity checks [#activity-checks]
For the selected period, the report scans recent messages and visits, surfacing **forbidden-word violations**, **error replies**, and **visit** counts (guest vs. signed-in). Flagged messages are listed so owners can act on the users involved.
# Settings (/docs/agent-page/settings)
# Settings [#settings]
The **Settings** tab is visible only to the agent's owner. It embeds the full Store edit form inline, so the owner can configure every aspect of the agent — model, knowledge base, tools, prompt, voice, and publishing — without leaving the Agent page. Editing happens in place rather than redirecting to the standalone Store edit page, and the tab is deep-linkable at `/agents/{owner}/{storeName}/settings`.
For the complete field reference, see [Stores](/docs/basic/stores).
# Logs (/docs/auditing-logs/logs)
# Logs [#logs]
OpenAgent keeps two kinds of operational data: **Records** for tracking administrative actions, and **Usage** for tracking token consumption and cost. Both are read-only views — they accumulate automatically as the system runs.
## Records [#records]
A **Record** is created for every write operation performed through the API. Each record captures:
| Field | Description |
| -------------- | ------------------------------------------------------------------ |
| `user` | Which account triggered the action |
| `method` | HTTP method — typically `POST` for writes |
| `requestUri` | The API endpoint called (e.g. `/api/store`, `/api/file`) |
| `action` | Human-readable description (e.g. "update Store: customer-support") |
| `clientIp` | IP address of the requester |
| `organization` | Organization context of the request |
| `createdTime` | When the action occurred |
Browse Records at **Records** in the admin panel. Filter by user, action keyword, or time range to narrow down specific events.
### What Records capture [#what-records-capture]
Records are your audit trail for configuration changes:
* Who created or edited a Store, and when
* Who added or removed a Provider
* Who uploaded or deleted a File
* Who changed a user's role or permissions
* Who triggered a file re-index
Records do **not** capture conversation activity (chat messages, tool calls) — that data is in the Chat and Message records.
## Snapshots [#snapshots]
**Snapshots** track file changes made by local file tools so admins can inspect and roll back tool-driven filesystem edits. They appear under the operational logs area alongside Records and Sessions.
The Snapshots page is controlled by the site's configured navigation items. Include `/snapshots` in the nav item list when admins should see it in the sidebar.
Each Snapshot records:
| Field | Description |
| ---------------------------- | ----------------------------------------------------------------- |
| `tool` | Tool that produced the filesystem change, currently `local_file`. |
| `action` | Operation type, such as write, move, or delete. |
| `path` / `source` / `target` | Affected path, or source and target for move operations. |
| `fileCount` | Number of files captured in the snapshot. |
| `state` | `Active` or `RolledBack`. |
| `errorText` | Rollback error, if one occurred. |
Open a Snapshot to review its file list and diff summary. Rolling back a Snapshot restores the captured before-state when the current files still match either the before or after state; if the files have changed independently, OpenAgent reports a conflict instead of overwriting unexpected changes.
### logPostOnly [#logpostonly]
By default, Records focus on **changes** (writes) rather than read traffic. This keeps the audit trail useful instead of noisy.
If you need to audit read access for compliance, OpenAgent can be configured to log all requests.
Records are append-only. They cannot be edited or deleted through the admin panel.
## Conversation history [#conversation-history]
For understanding what the agent said, what tools it called, and what it retrieved, go to **Chat** in the admin panel.
Admins can open any conversation across all users and see the full message thread. Each Message in the thread shows:
* The user's input and the agent's response
* Tool calls: the tool name, arguments sent, and result returned
* Retrieved Vectors: which knowledge base chunks were used, and their similarity scores
* Web search results, if `web_search` was used
* Token counts (input tokens, output tokens)
* The model's reasoning steps, if thinking mode was enabled
This is separate from Records. Records track administrative actions ("who changed a Store"). The Chat view tracks what happened inside conversations ("what did the agent say and do in response to this user").
### Finding a specific conversation [#finding-a-specific-conversation]
Use the Chat filter to narrow by:
* **Store** — see only conversations from a specific agent
* **User** — see all conversations from a specific account
* **Date range** — narrow to a time window
Click into any Chat to see its full message history. Click into any Message to see the full detail view (retrieval results, tool calls, web search results, token/cost accounting).
API chat sessions created through a Store's OpenAI-compatible external API key are marked as API chats. Their Chat and Message records are visible for audit and cost tracking, but are read-only in the admin UI so external-client history cannot be edited after the fact.
## Usage [#usage]
**Usage** aggregates token consumption over time. Each row represents one day's activity for one Store or provider:
| Field | Description |
| -------------- | -------------------------------------------------------- |
| `date` | Calendar date (UTC) |
| `userCount` | Distinct users who sent at least one message |
| `chatCount` | Number of Chat sessions started |
| `messageCount` | Total messages sent and received |
| `tokenCount` | Total tokens consumed (input + output) |
| `price` | Estimated cost, if pricing is configured on the provider |
Browse Usage at **Usage** in the admin panel. Filter by Store or date range.
### Cost tracking [#cost-tracking]
Cost tracking is opt-in. To enable it:
1. Edit the Model Provider
2. Set **Input Price per Thousand Tokens** and **Output Price per Thousand Tokens**
3. Set **Currency** (e.g. `USD`, `CNY`)
4. Save
After this, every Message records an estimated cost alongside its token counts. The Usage table accumulates these into daily totals.
Each provider tracks cost independently with its own currency and pricing. If you use multiple providers, their costs are tracked separately — no automatic currency conversion is performed.
Prices are estimates based on reported token counts. Actual billed amounts from the provider may differ due to minimum charges, rounding, or additional fees not reflected in token counts alone.
### Reading Usage data [#reading-usage-data]
Usage data answers questions like:
* Which Store is consuming the most tokens this month?
* Has usage spiked unexpectedly in the last 48 hours?
* How much did this deployment cost last week?
* How many unique users interacted with the system today?
If a Store shows unexpectedly high token usage, check the Store's **Memory Limit** setting — a high limit means more conversation history is included in every prompt, multiplying token usage for long conversations.
If `messageCount` is high but `userCount` is low, a small number of users are generating most of the traffic — possibly automated clients or testers.
### Token count accuracy [#token-count-accuracy]
Token counts in Usage are the values reported by the model provider API. They reflect actual tokens processed, including the system prompt, retrieved Vector text, tool results, and conversation history injected by Memory Limit — not just the visible user message and response.
For accurate per-message token details, open the Message detail view inside a Chat thread.
# Sessions (/docs/auditing-logs/sessions)
# Sessions [#sessions]
**Sessions** show which users are currently authenticated and active in the system.
Admins use Sessions to:
* Review active logins
* Revoke access when needed
* Investigate whether a user is still authenticated
Session handling is part of the broader account and access model described in [Users](/docs/admin/users).
# Chats (/docs/basic/chats)
# Chats [#chats]
A **Chat** is a conversation session backed by a single **Store**. When users talk to OpenAgent, they are always talking through a Chat.
Chats are where you:
* Start a conversation with an assistant
* Continue multi-turn history
* Review what happened in a session
For the full request lifecycle, streaming behavior, and how retrieval and tool calls work, see [Chat](/docs/chat).
## What matters in practice [#what-matters-in-practice]
* Use [Stores](/docs/basic/stores) to define the assistant
* Use Chats to hold the conversation history
* Use [Messages](/docs/basic/messages) to inspect each turn in detail
# Messages (/docs/basic/messages)
# Messages [#messages]
A **Message** is a single turn inside a Chat. It captures the user input or assistant reply, along with technical detail that helps you understand how the answer was produced.
In day-to-day use, Messages are the best place to inspect:
* What the user asked
* What the assistant replied
* Which tools were called
* Which knowledge chunks were retrieved
For a deeper explanation of message lifecycle and metadata, see [Chat](/docs/chat).
# Notifications (/docs/basic/notifications)
# Notifications [#notifications]
The **notification inbox** keeps users informed about activity on the Stores they follow, without having to poll each agent page. Notifications are generated automatically when something happens on a **published** Store that a user is **watching**.
## Opening the inbox [#opening-the-inbox]
A bell/inbox icon sits in the top navigation bar. It shows a **badge with the number of unread notifications**, and the count refreshes automatically about every 30 seconds. Clicking the icon opens your personal inbox at `/user-notifications`.
In the inbox you can:
* **Filter** between **All** and **Unread** notifications.
* **Mark one** notification as read (a notification is also marked read when you open its linked item).
* **Mark all as read** in a single action.
* **Page** through your notification history.
Each entry shows an event icon, the title, a short preview of the content, the actor who triggered it, and the related Store. Selecting a notification takes you to the item it refers to (for example, the issue or comment).
## What triggers a notification [#what-triggers-a-notification]
Notifications are created for watchers of a **published** Store when one of these events occurs:
| Event | When it fires |
| :-------------- | :----------------------------------------------- |
| `store-updated` | The Store's configuration or content is updated. |
| `issue-created` | A new issue is opened on the Store. |
| `issue-updated` | An existing issue is updated. |
| `comment-added` | A comment is added to an issue on the Store. |
To start receiving notifications for a Store, set it to **Watching** from the [Store hub](/docs/basic/stores) or [Issues](/docs/agent-page/issues) view. You are never notified about your own actions — the user who triggers an event is excluded from that event's recipients.
Only **Published** Stores generate notifications. Drafts and unpublished Stores do not notify their watchers.
## Delivery and lifecycle [#delivery-and-lifecycle]
Every notification is stored so it appears in the inbox, and it is also handed to OpenAgent's outbound notification channel for external delivery (such as the notification providers configured for your deployment). Each record moves through a simple lifecycle:
* **Pending** → **Sending** → **Sent**, or **Failed** if delivery does not succeed.
* Failed sends are retried automatically, up to a fixed retry limit.
* A background worker scans for pending and stale items on a short interval, and old notifications are cleaned up after a retention window (90 days by default).
## Administrator view [#administrator-view]
Global administrators have an additional **Notifications** page (at `/notifications`) that lists notification records across all users and Stores, which is useful for auditing delivery and troubleshooting failures. Regular users only see their own inbox at `/user-notifications`.
# Stores (/docs/basic/stores)
# Stores [#stores]
A **Store** is the primary object in OpenAgent. It defines a complete, independent AI agent: its model, its knowledge base (Files), and its capabilities (Tools).
Every conversation in OpenAgent is scoped to a Store. By configuring different Stores, you can create multiple specialized assistants — like a "Legal Advisor" and a "Coding Helper" — on the same platform.
***
## Ownership & Visibility [#ownership--visibility]
Stores are scoped to their owner. In the management list, each user sees only the Stores they own — Stores owned by the `admin` account are **not** mixed into other users' Store lists. To make a Store available to everyone, publish it to the Hub by setting its **Publish State** to **Published** (see [Hub Publishing](#hub-publishing)).
***
## Basic Information [#basic-information]
| Field | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | Unique internal ID (e.g., `support-bot`). No spaces. |
| **Display Name** | The name users see in the Chat UI. |
| **Avatar** | URL to the agent's icon. |
| **Title** | A short tagline shown under the agent's name. |
| **Is Default** | If true, new chats will use this Store by default. |
| **Publish State** | Controls whether the Store is private, pending review, published, or rejected for the Hub. Published Stores appear on the Hub and can be opened from there. |
| **External API Key** | Store-scoped key for the OpenAI-compatible chat completions API. Keys are generated automatically for new Stores and masked after saving. |
## Agent Profile [#agent-profile]
The **Agent Profile** fields enrich Store listings, especially in the Hub:
| Field | Description |
| --------------- | ---------------------------------------------------------------------------------- |
| **Author** | Name shown on the Hub card. If blank, OpenAgent falls back to the Store owner. |
| **Affiliation** | Organization, school, team, or institution shown under the author on the Hub card. |
| **Tutor** | Optional mentor or tutor attribution for the agent. |
| **Subject** | Academic subject, picked from a dropdown selector. |
| **Grade** | Target grade level, picked from a dropdown selector. |
| **Topic** | Focus topic shown as a Hub tag. |
| **Brief** | One-sentence introduction shown on the Hub card. |
| **Description** | Longer introduction for the agent. |
## Hub Publishing [#hub-publishing]
Store owners can submit a Store for review from the Store edit page. The **Publish State** can be **Private**, **Pending Review**, **Published**, or **Rejected**, and who may set which state is enforced:
* The **super admin** (the global admin whose username is `admin`) can set any state directly, including **Published**.
* Other **admins** can set any state except **Published** — they move a Store to **Pending Review** instead of publishing it outright.
* A Store's **owner** can only set the state to **Private** or **Pending Review**.
Everyone except the super admin must also clear the hub review eligibility bar to move a Store into **Pending Review**. A Store qualifies only when it has a custom display name (the default `New Store` name is rejected), a custom avatar (the default avatar is rejected), at least **200 messages**, and at least **100 vectors**. If any requirement is unmet, submission is blocked and every failed check is reported at once.
The Hub lists only Stores whose publish state is **Published**, using profile fields such as **Author**, **Subject**, **Grade**, **Topic**, and **Brief** on the card. Each card also shows the agent's **star**, **watcher**, and **fork** counts on one side and its **chat** and **message** counts on the other.
On the Hub page, users can search published Stores by name, author, owner, or affiliation; filter by **Subject**, **Grade**, and **Topic**; and sort by star, watcher, or fork count, or by display name, author, affiliation, subject, grade, or topic. The default sort is **most starred**. The filter bar always shows an agent count — the total number of published agents, or the matched-over-total count (for example `12 / 40`) once any filter is applied. Clicking a card opens that agent's [Agent page](/docs/agent-page) — a local agent navigates in place, while an external agent opens in a new browser tab. Each card also has a **View Details** link that opens a details drawer with the Store profile, description, full chat link, copy-link action, and **Start Chat** button. Signed-in users can also switch the listing between **All agents**, **Starred**, and **Watching** with the view selector, so favorited and followed agents are easy to find again.
For a single OpenAgent deployment, no extra Hub configuration is required: published Stores from the current database appear in **Hub**, and clicking a card opens that Store's Agent page.
Published Store cards also link to a public **[Agent page](/docs/agent-page)** — a read-only landing page for inspecting an agent before starting a conversation. It offers Star, Watch, and Fork actions and is organized into tabs for the agent's [Overview](/docs/agent-page/overview), [Chat](/docs/agent-page/chat), [Files](/docs/agent-page/files), [Issues](/docs/agent-page/issues), [Security](/docs/agent-page/security), [Insights](/docs/agent-page/insights), and owner-only [Settings](/docs/agent-page/settings). See the [Agent Page](/docs/agent-page) reference for the full breakdown.
For a multi-instance Hub, configure the source sites first:
1. On each OpenAgent site that should contribute Stores, set the site **Endpoint** to its public HTTPS base URL, such as `https://agents.example.com`.
2. On the Hub site, set **Hub DB Names** to a comma-separated list of additional OpenAgent database names to include.
3. Publish the Stores that should appear by setting their **Publish State** to **Published**.
The Hub combines local published Stores with published Stores from the listed databases. Local cards open chat pages on the current site; remote cards are labeled as external and use the source site's **Endpoint** for both the visible chat link and the **Start Chat** action, so users are sent to the correct OpenAgent instance. Opening an external agent's [Agent page](/docs/agent-page) also targets the source site's endpoint and opens in a new browser tab, while local agents navigate in place.
If a child OpenAgent database leaves **Hub DB Names** empty, it inherits the parent database's Hub list when the site is configured with a parent database name. This lets a hub topology share the same source list without repeating it in every child site.
***
## Intelligence & Reasoning [#intelligence--reasoning]
**Model Provider**\
The primary LLM that powers the agent's reasoning. You must select a provider configured under **Providers → Model**.
**Child Model Providers**\
A list of fallback models. If the primary model fails (e.g., rate limits or downtime), OpenAgent will automatically try these models in order.
**System Prompt**\
The most critical field. It defines the agent's persona, instructions, and constraints.\
*Example: "You are a customer support agent. Answer questions only based on the provided documents."*
***
## Knowledge Base (RAG) [#knowledge-base-rag]
These settings control how the agent retrieves information from your documents.
**Embedding Provider**\
The model used to turn text into searchable vectors. All files in this Store must be embedded using the same provider.
**Knowledge Count**\
The number of document "chunks" retrieved per user query. A higher number provides more context but can exceed the model's window. Recommended: `5`.
**Split Provider**\
Professional chunking strategies to optimize retrieval accuracy:
* **Default**: Paragraph-based, ideal for general documentation.
* **Markdown**: Heading-aware, preserves the structural context of technical docs.
* **QA**: **(Professional Choice)** Specifically optimized for FAQ-style files, ensuring questions and answers stay together in a single vector.
**Search Provider**
* **Default**: Standard vector similarity search.
* **Hierarchy**: Advanced recursive retrieval; performs a high-level scan of document sections before drilling down into specific chunks. Best for massive libraries.
**Image Provider**
Storage provider used for image assets generated or handled by this Store. OpenAgent resolves a local Provider record first and falls back to Casdoor storage when available.
***
## Tools & Automation [#tools--automation]
**MCP Server**\
Connect an external MCP (Model Context Protocol) server to this Store. The agent will have access to all allowed tools from that server. Configure servers under **Servers → Add Server**.
**Tools**\
Tool records attached to this Store. Built-in tools are configured from the **Tools** area first, then selected here alongside any other tool records the agent should be allowed to call. See [Built-in Tools](/docs/connectors/tools/builtin-tools) for the full reference.
Select `All` to expose every Tool record owned by the Store's organization. Use this only for trusted internal agents; for public or high-risk agents, select the exact tools the agent needs.
**Skills**\
Reusable skill instructions attached to this Store. Skills can be loaded from the local skills folder or installed from the Skill Marketplace, then selected on the Store so the agent can use those task-specific instructions.
Select `All` to include every available Skill for the Store's organization. This is useful for broad internal assistants, but targeted agents should usually use a smaller skill set.
OpenAgent exposes enabled Skills through a `load_skill` tool. The agent sees a catalog first and loads the full Skill content only when the user request or Skill name makes it relevant.
**Enable Experience Review**
When enabled, OpenAgent can review completed tool-heavy tasks in the background and create or update reusable Skills from durable procedures. The review runs after tasks that use `browser_use` or at least three tool calls, and it is designed to save stable workflows rather than private reasoning, secrets, personal data, or one-off task narratives.
***
## Voice & Multimodal [#voice--multimodal]
**Text-to-Speech Provider**\
When set, the assistant's replies are read aloud using this provider. Enable **TTS Streaming** to stream audio as it is generated rather than waiting for the full reply.
**Speech-to-Text Provider**\
When set, a microphone button appears in the chat input so users can dictate messages. Set it to `Browser Built-In` to transcribe in the browser at no cost, or to a cloud STT Provider to stream audio to the server for higher accuracy. See [Voice Input](/docs/chat/voice-input) for the two modes and silence auto-stop behavior.
***
## Virtual Figure [#virtual-figure]
Stores can show an AI virtual figure in the chat UI. Users can resize, move, collapse, or disable the figure from its chat menu; the figure status follows the chat state, such as typing, thinking, replying, error, or done.
| Field | Description |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Enable virtual figure** | Turns the virtual figure on for this Store's chat UI. |
| **Virtual figure URL** | Image URL for the figure. If left blank, the built-in default figure asset is used. |
| **Default mode** | Whether the figure starts **Expanded** or **Collapsed** when the chat opens. |
***
## Insights & Security [#insights--security]
A published agent's usage analytics and its automated security audit live on the [Agent page](/docs/agent-page), under the [Insights](/docs/agent-page/insights) and [Security](/docs/agent-page/security) tabs.
***
## Memory & Context [#memory--context]
**Memory Limit**\
Maximum number of previous messages kept in the prompt context window. Setting this prevents context overflow on long conversations.
**Hide Thinking**\
When enabled, chain-of-thought reasoning (from models like DeepSeek-R1 or Claude 3.7 in extended thinking mode) is hidden from users — only the final answer is shown.
***
## Chat UI [#chat-ui]
The selected Store is persisted in the browser, so refreshing the page or returning to Chat keeps the last Store selection instead of resetting to the default Store.
The **Analysis** page summarizes Stores that already have message history and shows word clouds built from user messages. It is useful for spotting common topics and prompt patterns across Store conversations.
**Welcome Title / Welcome Text**\
Greeting shown on the empty-state chat screen before the user's first message.
**Example Questions**\
Suggested prompts shown in the chat UI. Each entry has a **Title** (short label) and **Text** (the full question sent when clicked). Useful for onboarding users to the agent's capabilities.
**Suggestion Count**\
Number of follow-up question suggestions to generate after each assistant reply.
**Show Auto Read**\
Exposes an auto-read toggle in the chat UI so users can enable hands-free TTS playback.
**Disable File Upload**\
Hides the file upload button in the chat UI, preventing users from attaching files mid-conversation.
***
## API Access [#api-access]
OpenAgent exposes OpenAI-compatible chat completion endpoints at `POST /api/chat/completions` and `POST /api/v1/chat/completions`. Both the Store edit page and the [Model Provider](/docs/connectors/providers/model-providers) edit page show a copyable OpenAI-compatible API panel with **Base URL** and **Chat completions endpoint** values for external clients — the Store page pairs it with the Store's External API Key, the Provider page with that provider's key.
Use `Authorization: Bearer ` with either:
* a Store **External API Key**, which routes the request through that Store's model provider, attached MCP server, and built-in tools, then records the API conversation as Chat and Message records with user `api`
* a Model Provider key, which calls that provider directly without creating Store chat history
Store-key requests include the OpenAI-style message history and system prompt. If the request includes a system message, it overrides the Store prompt for that API call.
***
## Storage [#storage]
**Storage Provider**\
Which storage backend is used for file uploads to this Store. Defaults to the system-level storage provider. Override here if this Store needs a specific bucket or path.
***
## Content Safety & Compliance [#content-safety--compliance]
OpenAgent includes built-in safeguards to ensure agent responses remain within corporate or community guidelines.
**Forbidden Words**\
A configurable list of blocked terms. If a user's query or the model's potential response contains these words, OpenAgent will intercept the request and return a standardized refusal.
***
## Knowledge Modularity (Composition) [#knowledge-modularity-composition]
One of OpenAgent's most powerful architectural features is its support for **Knowledge Composition**.
**Child Stores**\
Instead of creating one massive, unmanageable Store, you can link multiple specialized Stores together. When a user queries a "Master Store," OpenAgent performs a unified search across its own knowledge base and all associated **Child Stores**.
*Example: A "Company Handbook" Store can link to a "Legal Store," an "HR Store," and a "Technical Specs Store" to provide a unified corporate brain while keeping data management decentralized.*
***
**Pro Tip:** If you change the **Embedding Provider** for an existing Store, you must re-upload its files. Existing vectors are not compatible with different embedding models.
# Agent Configuration (/docs/chat/agent-configuration)
# Agent Configuration [#agent-configuration]
All chat behavior is controlled through the Store. There is no separate chat settings screen — every field that shapes a conversation lives on the Store that backs it. Changes take effect immediately for the next message sent to that Store.
## System prompt [#system-prompt]
**Prompt** is the single most important lever for agent behavior. It is sent as the system message at the start of every conversation, before any user input or retrieved context.
Write it as direct instructions. Some effective patterns:
**Define scope and persona:**
```
You are a technical support assistant for Acme Corp.
Answer questions about our software products.
For anything unrelated, politely redirect the user.
```
**Instruct on knowledge base use:**
```
Always search the provided context before answering.
If the context contains a relevant answer, use it and reference the source.
If not, say you don't have that information — do not guess.
```
**Control response format:**
```
Keep responses under 3 paragraphs. Use bullet points for steps.
For code, always use fenced code blocks with the language specified.
```
The prompt is the first thing in the context, so it has the strongest influence on model behavior. Ambiguous prompts produce inconsistent results — be explicit.
## Memory [#memory]
**Memory Limit** controls how many past turns to include in each context window. Each "turn" is one user message plus one AI response.
Setting this too high uses more tokens per request (which costs more and can hit context window limits). Setting it too low means the agent loses earlier parts of the conversation.
Typical values:
* `10` — enough for most single-topic conversations
* `20–30` — for longer, multi-topic sessions
* `0` — no history is included (each message is treated as independent)
When the limit is reached, the oldest turns are dropped. The system prompt and retrieved knowledge chunks are always included regardless of the limit.
## Knowledge retrieval [#knowledge-retrieval]
**Knowledge Count** sets how many Vector chunks are retrieved from the knowledge base per query. The default is 3.
Raise this when:
* Questions require synthesizing information from multiple sections of a document
* Documents are dense and a single chunk often lacks full context
* The agent frequently says "I don't have enough information" despite the content existing
Lower this when:
* Retrieved chunks are large and you need to stay within token budget
* Questions are typically answered by a single, specific passage
**Search Provider** determines the retrieval algorithm:
* `Default` — standard cosine similarity search over all Vectors in the Store
* `Hierarchy` — a hierarchical search that first identifies high-level document sections, then refines within them. Better for large knowledge bases with many documents where flat similarity search returns noisy results.
## Rate limiting [#rate-limiting]
**Frequency** and **Limit Minutes** together control how many messages a user can send within a time window.
* **Frequency** — maximum number of messages allowed per window
* **Limit Minutes** — the length of the window in minutes
For example: Frequency = `20`, Limit Minutes = `60` means each user can send 20 messages per hour to this Store. Once the limit is hit, further messages are rejected with a rate limit error until the window resets.
Setting Frequency to `0` disables rate limiting entirely.
Rate limits are per-user, per-Store. Users who hit the limit on one Store can still use other Stores freely.
## Suggestions [#suggestions]
**Suggestion Count** — the number of follow-up question suggestions generated after each AI response. These appear as clickable prompts in the chat UI, inviting the user to continue the conversation.
Setting this to `0` disables suggestions. Setting it to `3` generates three suggestions per response. The suggestions are produced by a separate model call using the conversation context, so they incur additional token usage.
Use suggestions when you want to guide users toward topics the agent handles well, or when users tend to be unsure what to ask next.
## Welcome message [#welcome-message]
Three optional fields are shown when a user opens a fresh Chat session:
* **Welcome Title** — bold heading at the top of the empty chat
* **Welcome Text** — a paragraph below the heading, describing what the agent can do
* **Welcome** — a brief greeting line
Leave these empty and the chat opens directly to the input field with no preamble.
## Example questions [#example-questions]
**Example Questions** — a list of suggested prompts shown as buttons in the chat UI. Each entry has:
* **Title** — the button label
* **Text** — the actual prompt sent when the button is clicked
* **Image** (optional) — an icon or thumbnail shown alongside the button
Use example questions to surface the most useful things users can ask. They also serve as an implicit FAQ — clicking a button immediately sends the question and gets an answer.
## Content filtering [#content-filtering]
**Forbidden Words** — a blocklist applied to incoming user messages before they reach the model. Any message containing a word from this list is rejected with an error response. The rejection happens before any LLM call, so no tokens are consumed.
This is a simple exact-match filter, not a semantic classifier. Use it for obvious off-topic keywords or brand-safety terms, not as a comprehensive moderation system.
## Display options [#display-options]
**Hide Thinking** — some models (certain Claude, DeepSeek, and Volcano Engine variants) return reasoning content alongside the final answer. When this is enabled, the reasoning is stripped before the response reaches the user. Admins can still see it in the Message detail view.
**Disable File Upload** — hides the file upload button in the chat UI, preventing users from attaching files to messages.
**Show Auto Read** — adds a text-to-speech playback button to AI responses. Only meaningful if a Text-to-Speech provider is configured on the Store.
**Enable Extra Options** — exposes additional configuration toggles in the chat UI for end users (such as enabling or disabling web search per-message). Off by default; only enable if you want users to have runtime control over these options.
## Multi-provider fallback [#multi-provider-fallback]
**Child Model Providers** — an ordered list of fallback providers. If the primary **Model Provider** fails, OpenAgent tries each in sequence and uses the first one that succeeds.
This is transparent to the user. The Message record captures which provider actually handled the request in its `modelProvider` field.
# Chat (/docs/chat)
# Chat [#chat]
Every conversation in OpenAgent is a **Chat** session backed by a **Store**. The Store's configuration determines everything: which model responds, whether the knowledge base is searched, which tools are available, and what instructions the model operates under.
## Request lifecycle [#request-lifecycle]
When a user sends a message, OpenAgent runs this sequence:
**1. Load history.** The conversation history is retrieved from the database, bounded by the Store's **Memory Limit**. Turns beyond the limit are dropped, oldest first. The system prompt is always included regardless of the limit.
**2. Search the knowledge base.** If the Store has an Embedding Provider and indexed Files, the user's message is embedded and compared against the Store's Vectors. The top N chunks by cosine similarity are retrieved (N = **Knowledge Count**).
**3. Assemble context.** The prompt is constructed: system prompt first, then the retrieved chunks (labeled as context), then the conversation history, then the user's message.
**4. Call the model.** The assembled context is sent to the LLM. If the model calls a tool, OpenAgent executes the tool, appends the result to the context, and calls the model again. This loop repeats until the model produces a text response.
If a tool call fails, OpenAgent marks the tool result as an error and gives the model a recovery turn. The model can retry with corrected arguments, choose a different approach, or explain why the task is blocked.
**5. Stream and save.** Tokens stream to the client in real time. When the response is complete, a Message record is saved containing the text, tool calls, retrieval metadata (if any), token counts, and estimated cost.
## Chat records [#chat-records]
Each Chat belongs to a Store and a user. It records:
* **Display Name** — the chat title shown in the sidebar. OpenAgent prefers the generated title from the model and falls back to a short version of the first user message when no title is returned.
* **Message Count** — total turns in the conversation
* **Token Count** — cumulative tokens across all messages
* **Price** — cumulative estimated cost (if pricing is configured on the model provider)
* **Is Generating / Is Unread** — status flags used by the chat list. OpenAgent marks a chat as generating while a response is running, polls active chats for status updates, and clears the unread state when a completed chat is opened.
* **Is Hidden / Is Deleted** — soft-delete flags; admins can hide or delete chats without permanent removal
Admins can browse all Chats across all users from **Chat** in the admin panel. Opening a Chat shows the full conversation history with Message detail.
## Message records [#message-records]
Every turn is saved as a Message. The admin UI can show the full technical detail for debugging (retrieval results, tool calls, which provider handled the request, and token/cost accounting).
## Feedback and regeneration [#feedback-and-regeneration]
Users can leave feedback on AI responses:
**Like / Dislike** — thumbs up or down on a message. Useful for collecting quality signals from users without any additional tooling.
**Regenerate** — users can regenerate an AI response. Both the original and regenerated responses are retained.
## Follow-up suggestions [#follow-up-suggestions]
If **Suggestion Count** is set on the Store (to a number greater than 0), OpenAgent generates follow-up question suggestions after each AI response. These appear as clickable prompts in the chat UI. The count controls how many suggestions are generated — typically 2–4 works well.
Setting Suggestion Count to 0 disables the feature entirely.
## Attachments [#attachments]
Users can attach files from the chat input. Files can also be pasted directly from the clipboard or dragged into the input area, which adds them to the pending attachments before the message is sent. Pasting and dropping accept the same file types as the attach button — images plus common document formats such as `.txt`, `.md`, `.yaml`, `.csv`, `.pdf`, `.docx`, `.xlsx`, and `.pptx` — and duplicate files pulled from the clipboard are de-duplicated automatically.
## Streaming [#streaming]
Responses stream token by token. The frontend renders each token as it arrives. Tool calls appear inline as they happen — the user can see what tool was called, with what arguments, and what it returned, before the final response is generated.
Failed tool calls are shown as error tool results in the stream, which makes retries and blocked actions easier to diagnose from the chat transcript.
If a provider doesn't support streaming, OpenAgent falls back to waiting for the full response. Streaming is the default for all providers that support it.
During long-running tool calls, OpenAgent sends SSE keepalive comments so browsers and proxies are less likely to close an otherwise quiet stream.
While a response is running, OpenAgent can stream generation status events into the chat UI. The message shows a compact progress strip for stages such as preparing context, retrieving knowledge, calling tools, or waiting for the model, so users can see that work is still moving even before new answer text appears.
Message generation is tracked independently from a single browser connection. If the tab refreshes or the SSE connection drops, reconnecting to the same message can replay the generated stream while the job is still retained. Closing the stream alone does not cancel the model call; use the chat cancel action to explicitly stop a running answer.
If generation finishes while the browser was interrupted, the chat UI refreshes the latest messages when it detects the chat is no longer generating. Tool call arguments can also stream incrementally, so users can inspect long tool inputs before the tool result is complete.
When a tool creates a downloadable file, OpenAgent can show generated Resource cards directly under the assistant message.
## User identities [#user-identities]
Wherever a user appears in the UI — chat message authors, comments, issue replies, task lists, Insights contributor breakdowns, and the owner columns of the admin management list pages (Chats, Messages, Files, Sessions, Stores, and more) — OpenAgent shows their real display name and avatar instead of a bare username. Hovering the name or avatar pops a small profile card, and it links through to the full user profile, so it is easy to see who wrote a message or left a comment.
## Multi-provider fallback [#multi-provider-fallback]
A Store can have **Child Model Providers** as fallbacks. If the primary provider fails (network error, rate limit, API key issue), OpenAgent tries each fallback in order. No conversation is interrupted by a single provider outage.
The **Message** detail view in the admin panel shows the full technical record for each turn. It’s the best place to debug why an agent responded a certain way.
## Advanced: what’s in a Message record? [#advanced-whats-in-a-message-record]
If you’re integrating with the API or debugging deeply, Message records include structured fields for:
* Retrieval metadata (which chunks were retrieved and their similarity scores)
* Tool calls (tool name, arguments, and results)
* Provider attribution (which model/embedding provider was used)
* Token and cost accounting
## Related [#related]
* [Agent Configuration](/docs/chat/agent-configuration) — prompt, memory, rate limiting, content filtering
* [Stores](/docs/basic/stores) — complete Store field reference
* [Vectors](/docs/knowledge-base/vectors) — understanding vector retrieval and scores
# Voice Input (/docs/chat/voice-input)
# Voice Input [#voice-input]
When a Store has a **Speech-to-Text Provider** configured, a microphone button appears next to the chat input. Users tap it to dictate a message instead of typing. The transcript is inserted into the input box — it is **not** sent automatically, so the user can review or edit it before pressing send.
Voice input is the inbound counterpart to [text-to-speech playback](/docs/chat/agent-configuration): speech-to-text turns the user's voice into text, text-to-speech reads the assistant's replies aloud. The two are configured independently on the Store.
## Choosing a mode [#choosing-a-mode]
The **Speech-to-Text Provider** field on the Store selects one of two transcription paths:
| Provider setting | Mode | Where audio is processed |
| ---------------------------------------------- | ------------------- | -------------------------------- |
| Empty or `Browser Built-In` | Browser recognition | Entirely in the user's browser |
| A configured STT Provider (e.g. Alibaba Cloud) | Cloud streaming | Streamed to the OpenAgent server |
### Browser built-in recognition [#browser-built-in-recognition]
The default mode uses the browser's built-in Web Speech API. It runs entirely client-side, so there is no provider cost and no audio leaves the user's device. Recognition is continuous and shows interim results as the user speaks, so several sentences can be strung together in one session.
Browser recognition depends on the Web Speech API, which is available in Chrome, Edge, and Safari but not all browsers. If the browser doesn't support it, the user sees a "Speech recognition not supported in this browser" message and should switch to a cloud Speech-to-Text Provider.
### Cloud streaming recognition [#cloud-streaming-recognition]
When a cloud Speech-to-Text Provider is set, OpenAgent opens a WebSocket to the server and streams microphone audio end to end. The browser captures the mic with echo cancellation, noise suppression, and auto gain control, downsamples it to 16 kHz mono PCM, and ships it to the server, which returns interim and final transcripts live as the user talks. This gives higher accuracy than browser recognition and works consistently across browsers, at the cost of running through the configured provider.
Streaming requires a browser with `AudioWorklet` and microphone access; if those aren't available the user sees a "Streaming speech recognition is not supported in this browser" message.
Alibaba Cloud Speech-to-Text providers include realtime options such as `fun-asr-realtime`, `fun-asr-flash-8k-realtime`, and `paraformer-realtime-v2`. Provider edit pages include a microphone test widget for Speech-to-Text providers, so admins can record a short sample and verify transcription before attaching the provider to a Store.
## Silence auto-stop [#silence-auto-stop]
In both modes the recording session ends on its own after a short period of silence, so the microphone button always resets instead of staying stuck in the "recording" state. A session also ends automatically when the browser stops recognition for its own reasons — a network drop, switching tabs, or the roughly 60-second cap that mobile Safari imposes. Users can always stop a session manually by tapping the microphone button again.
When a session ends — whether by silence, manual stop, or a server-side completion — the mic button returns to its idle state and the cursor is placed at the end of the transcribed text, ready for the user to keep editing or send. New transcript text is appended to the existing input instead of replacing it, and OpenAgent does not auto-send the transcript when recording stops.
## Requirements [#requirements]
* The Store must have a **Speech-to-Text Provider** set (`Browser Built-In` or a cloud STT Provider). See [Stores → Voice & Multimodal](/docs/basic/stores).
* The browser must grant microphone permission on first use.
* Cloud streaming requires a browser with `AudioWorklet`; browser built-in recognition requires Web Speech API support.
## Related [#related]
* [Stores](/docs/basic/stores) — the **Speech-to-Text Provider** and **Text-to-Speech Provider** fields
* [Agent Configuration](/docs/chat/agent-configuration) — the **Show Auto Read** toggle for text-to-speech playback
* [Chat](/docs/chat) — the overall request lifecycle
# MCP Servers (/docs/connectors/mcp-servers)
# MCP Servers [#mcp-servers]
MCP is an open standard for exposing tools to language models. An MCP server defines a set of tools — each with a name, description, and parameter schema — that the model can call during a conversation. OpenAgent connects as an MCP client: it queries the server's tool list when a conversation starts and routes tool calls to the server during the conversation.
Any MCP-compatible server works with OpenAgent. No custom integration code is needed on the OpenAgent side.
## How tool use works [#how-tool-use-works]
When a conversation starts, OpenAgent queries the MCP server for its tool list. Each tool's name and description are included in the context sent to the model. During the conversation:
1. The model decides a tool is needed based on the user's request and the tool's description
2. The model emits a structured tool call: `{ "tool": "get_weather", "args": { "city": "Tokyo" } }`
3. OpenAgent sends the call to the MCP server and waits for the result
4. The result is appended to the context: `{ "result": "Partly cloudy, 22°C" }`
5. The model reasons again with the result in view and either calls another tool or produces a final response
Tool calls and results are shown inline in the chat UI and saved in the Message's `toolCalls` field.
## Connecting an MCP server [#connecting-an-mcp-server]
### Create a Server record [#create-a-server-record]
Go to **Servers → Add Server**.
* **Name**: a unique identifier for the server (e.g., `my-tools`)
* **Display Name**: human-readable label shown in the UI
* **URL**: the MCP server's StreamableHTTP endpoint (e.g., `https://tools.example.com/mcp`)
* **Token**: optional Bearer token sent as `Authorization: Bearer ` for authenticated servers
OpenAgent uses the **StreamableHTTP** transport to connect to MCP servers. The server must expose an HTTP endpoint that implements the MCP protocol.
After a token is saved, API responses return it as `***`. Submit `***` unchanged when editing other fields to keep the existing token; enter a new value only when rotating the credential.
Save the server record.
### Sync tools [#sync-tools]
After saving, click **Sync** on the server record. OpenAgent connects to the URL and fetches the server's tool list. Each discovered tool appears in the tool list with an **IsAllowed** toggle.
By default all tools are allowed. Disable individual tools to prevent the model from calling them.
### Attach to a Store [#attach-to-a-store]
Edit the Store where you want the MCP tools available. Set **MCP Server** to the server you created. Save.
### Test it [#test-it]
Open a chat with the Store. Ask the agent to do something the tool handles. Watch the tool call appear inline — you'll see the tool name, the arguments passed, and the result returned.
If the tool isn't called when you expect it to be, check the tool description (see below) and consider adding explicit instructions in the system prompt.
## Writing good tool descriptions [#writing-good-tool-descriptions]
The model has no way to try a tool and see what happens. It relies entirely on the description to decide whether the tool is appropriate. Vague or generic descriptions lead to the wrong tool being called, the right tool not being called, or incorrect arguments being passed.
Good descriptions answer three questions:
1. What does this tool do?
2. When should the model use it (and when shouldn't it)?
3. What do the parameters mean?
**Well-described tool:**
```json
{
"name": "lookup_order",
"description": "Look up the current status and details of a customer order by its order ID. Use this when the user asks about shipping, delivery, or order status. Do not use for billing or refund questions.",
"parameters": {
"order_id": {
"type": "string",
"description": "The order identifier. Format: ORD-XXXXXX (e.g. ORD-123456)"
}
}
}
```
**Poorly described tool:**
```json
{
"name": "get_order",
"description": "Gets order info.",
"parameters": {
"id": { "type": "string" }
}
}
```
The system prompt can also guide tool selection directly: "If the user asks about order status, always use `lookup_order` before responding."
OpenAgent queries the MCP server's tool list at conversation start. Changes to the server's exposed tools are reflected immediately in new conversations without restarting OpenAgent. Use **Sync** after modifying the server's tool list to refresh OpenAgent's cached tool allowlist.
## Tool allow-listing [#tool-allow-listing]
After syncing, the server record shows each discovered tool with an **IsAllowed** toggle. Disabling a tool removes it from the model's tool list for all chats using this server — the model never sees it and cannot call it.
Use this to restrict a server to only the tools relevant to a particular Store's purpose, or to disable dangerous tools that the server exposes but you don't want available in your deployment.
## Combining MCP with built-in tools [#combining-mcp-with-built-in-tools]
An MCP Server and Tool records for built-in tools can coexist on the same Store. The model sees all tools in one unified list and decides which to call. OpenAgent routes each call to the appropriate backend — MCP server or built-in implementation — transparently.
A Store can only have one MCP Server at a time. If you need tools from multiple MCP servers, either:
* Combine the tools into a single MCP server
* Use an MCP server that proxies multiple upstreams
## MCP ecosystem [#mcp-ecosystem]
The [MCP documentation](https://modelcontextprotocol.io) maintains a directory of open-source servers and SDKs. Commonly used servers include:
| Server | What it does |
| ----------------------------------------- | --------------------------------------- |
| `@modelcontextprotocol/server-filesystem` | Read and write local files |
| `@modelcontextprotocol/server-github` | Search repos, read files, create issues |
| `@modelcontextprotocol/server-postgres` | Query PostgreSQL with natural language |
| `@modelcontextprotocol/server-slack` | Send messages, read channel history |
| `@modelcontextprotocol/server-fetch` | Fetch and extract content from URLs |
SDKs are available for TypeScript, Python, and other languages for building custom servers.
# Servers (/docs/connectors/servers)
# Servers [#servers]
**Servers** is the admin panel section for managing MCP Server records. Each Server record stores the connection details for one external MCP server and controls which of its tools your agents are allowed to use.
## Server record fields [#server-record-fields]
| Field | Description |
| -------------- | ----------------------------------------------------------------------------------------------- |
| **Name** | Unique identifier for this server (e.g. `my-tools`). Used to reference the server from a Store. |
| **URL** | The MCP server's StreamableHTTP endpoint (e.g. `https://tools.example.com/mcp`). |
| **Token** | Optional Bearer token sent in the `Authorization` header for authenticated servers. |
| **Tools** | The list of tools discovered via Sync, each with an **IsAllowed** toggle. |
| **Is Default** | If enabled, this server is pre-selected when creating new Stores. |
## Adding a server [#adding-a-server]
### Create the record [#create-the-record]
Go to **Servers → Add Server**.
Fill in **Name**, **URL**, and optionally **Token**. Save.
### Sync tools [#sync-tools]
Click **Sync** on the server record. OpenAgent connects to the MCP server and fetches its tool list. Each discovered tool appears with an **IsAllowed** toggle.
Disable any tools you don't want the model to have access to. Only allowed tools are included in the model's context.
### Attach to a Store [#attach-to-a-store]
Edit the Store where you want these tools available. Set **MCP Server** to this server. Save.
### Test it [#test-it]
Open a chat with the Store and ask the agent to do something the tool handles. The tool call, arguments, and result appear inline in the chat UI.
## Tool allow-listing [#tool-allow-listing]
After syncing, each tool has an **IsAllowed** toggle. This lets you expose only a subset of the server's tools to the model — useful when a server provides many tools but you only want the agent to use specific ones.
Sync again whenever the MCP server adds or removes tools. New tools discovered during sync default to **IsAllowed = true**. Toggle off any tools you want to block before attaching the server to a Store.
## One server per Store [#one-server-per-store]
A Store can only have one MCP Server attached at a time. If you need tools from multiple servers, either:
* Combine the tools into a single MCP server
* Use an MCP server that proxies multiple upstreams
Built-in tools and the MCP Server can coexist on the same Store — the model sees all tools in one unified list.
## Related [#related]
* [Understanding MCP](/docs/connectors/tools/mcp) — how the MCP protocol works and how to write good tool descriptions
* [Built-in Tools](/docs/connectors/tools/builtin-tools) — tools bundled with OpenAgent that need no external server
# Files (/docs/knowledge-base/files)
# Files [#files]
A **File** is a document uploaded to a Store. Once uploaded, it goes through an asynchronous processing pipeline: text extraction, chunking, embedding, and Vector storage. After processing completes, the File's content is searchable by any Chat backed by that Store.
## Uploading [#uploading]
Go to **Files → Upload**. Select one or more files and assign them to a Store. A File belongs to exactly one Store — retrieval is scoped to that Store's own Files plus any Child Stores.
You can upload multiple files at once. Each file is processed independently, so one failed file doesn't affect others.
The Files list also supports direct uploads from the table toolbar. Uploaded files are stored through the selected Store's Storage Provider when a Store filter is active, or through the default Storage Provider and default Store otherwise. Filenames are stored under a generated object path so two uploads with the same filename do not overwrite each other.
The table shows the file owner, Store, Storage Provider, created time, size, token count, and Vector count. You can filter the list by Store, click the Vector count or vector action to inspect generated Vectors, and use the refresh action to regenerate Vectors for a File. Image files show a small preview in the list; for other files, use the file URL or the related Vectors view to inspect processed content.
## Supported formats [#supported-formats]
| Format | Extension | Notes |
| ---------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| PDF | `.pdf` | Text extraction from both digital and (where configured) scanned pages |
| Word | `.docx` | Structure-aware: headings, paragraphs, and tables are preserved |
| Excel | `.xlsx` | Each sheet is ingested row by row |
| CSV / TSV | `.csv`, `.tsv` | Structured tabular data |
| Plain text | `.txt` | Direct ingestion, no parsing |
| Markdown | `.md`, `.mdx` | Best paired with the `Markdown` Split Provider |
| PowerPoint | `.pptx` | Slide text and speaker notes |
| Images | `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp` | Captioned by the Store's vision-capable model provider, then embedded for retrieval |
Legacy Office formats such as `.doc`, `.xls`, and `.ppt` are rejected. Convert them to `.docx`, `.xlsx`, or `.pptx` before uploading.
Scanned PDFs may need OCR before their text can be read. For agent-side reading of scanned local PDFs, enable the `local_file` Tool and use `local_pdf_ocr_read`; see [Built-in Tools](/docs/connectors/tools/builtin-tools#local_file) for the OCR endpoint configuration.
Image files require the Store's Model Provider to be vision-capable so OpenAgent can generate a caption before embedding. OpenAgent stores the generated caption as vector text and keeps the original image URL on the Vector, so retrieved image knowledge can be shown back to the model and rendered in chat responses.
## Processing pipeline [#processing-pipeline]
After upload, each file moves through:
**Pending** — the file has been received and is queued. No processing has started yet.
**Processing** — text is being extracted, split into chunks, and embedded. Each chunk becomes a Vector record. Duration depends on document size and embedding provider latency — a 20-page PDF typically takes 20–60 seconds.
**Finished** — all chunks are embedded and indexed. The File is now searchable.
**Error** — processing failed. The error message is shown in the file list.
If a File shows `Error`, the most common causes are:
* **Embedding Provider not configured** on the Store — set one before uploading
* **Invalid API key** on the Embedding Provider — test the provider from its edit page
* **Password-protected file** — remove the password before uploading
* **Unsupported encoding** — convert to UTF-8 before uploading plain text files
## Chunking and the Split Provider [#chunking-and-the-split-provider]
The Store's **Split Provider** controls how the extracted text is divided before embedding. Choosing the right strategy affects retrieval quality:
**Default** — paragraph-aware chunking, max \~210 tokens per chunk. Handles code blocks specially (keeps them intact). Splits on paragraph boundaries (4+ consecutive blank lines). Good for most document types.
**Basic** — simpler line-based chunking, max \~210 tokens. Use for short, uniform content where paragraph detection isn't needed.
For the Default and Basic split providers, oversized single lines are split by words before embedding. This prevents one unusually long line from exceeding the embedding model's context limit.
**Markdown** — heading-aware. Splits at heading boundaries and keeps content under each heading together. Use this when uploading Markdown documentation — retrieval will correctly associate content with its section heading.
**QA** — splits on `Q:` / `A:` lines. Use for FAQ-format documents. Each question-answer pair becomes its own chunk, so retrieval stays at the QA granularity.
Change the Split Provider on the Store before uploading. Files uploaded with one strategy and then re-uploaded after changing the strategy are re-processed with the new strategy.
## Viewing file content [#viewing-file-content]
Navigate to **Files** and open the related Vectors for a finished File to browse its indexed chunks. You can see the exact text of each chunk alongside its position in the document. This is useful for verifying that chunking produced sensible results — if chunks are cut in awkward places, try a different Split Provider.
## Updating a file [#updating-a-file]
There is no in-place update. To replace a document:
1. Delete the old File from the **Files** list — this immediately deletes all its Vectors
2. Upload the new version
## Deleting files [#deleting-files]
Deleting a File removes it and all its Vector records from the database permanently. The raw file data is also deleted from the storage backend. This cannot be undone.
## File fields [#file-fields]
| Field | Description |
| ----------------- | ------------------------------------------------------------------------- |
| `name` | Unique identifier (usually the original filename) |
| `filename` | Display filename shown in the UI |
| `size` | File size in bytes |
| `store` | Which Store this File belongs to |
| `storageProvider` | Which Storage Provider holds the raw file data |
| `url` | URL to access or download the raw file |
| `tokenCount` | Total tokens across all Vectors generated from this File |
| `vectorCount` | Number of Vector records generated for this File, shown in the Files list |
| `status` | `Pending`, `Processing`, `Finished`, or `Error` |
| `errorText` | Error message if status is `Error` |
# Resources (/docs/knowledge-base/resources)
# Resources [#resources]
In the product UI, **Resources** sits alongside Files and Vectors as part of the knowledge-base area.
For most teams, the main workflow still starts with:
* [Files](/docs/knowledge-base/files) for document ingestion
* [Vectors](/docs/knowledge-base/vectors) for retrieval
Use Resources as the broader bucket for knowledge-related supporting objects shown in the admin UI.
## Generated resources [#generated-resources]
When an agent creates a file with `word_write`, `excel_write`, `pptx_write`, or `local_file_write`, OpenAgent archives the generated output as a Resource. The chat response shows a download card for the generated file, and the same object appears in **Resources** for later access.
Resources are user-scoped for non-admin users: regular users see and delete their own generated files, while admins can browse resources across users. This keeps generated deliverables such as decks, spreadsheets, documents, and written local files available after the chat turn finishes.
If you're just getting started with RAG, you usually do not need to begin here. Start with [Add a Knowledge Base](/docs/add-a-knowledge-base), then come back as needed.
# Vectors (/docs/knowledge-base/vectors)
# Vectors [#vectors]
A **Vector** is a single embedded chunk of text from a File. When OpenAgent processes an uploaded document, it splits the text into smaller pieces (using the Store's Split Provider), converts each piece into a numerical vector (using the Embedding Provider), and stores the result as a Vector record. These Vector records are what power semantic search.
## How retrieval works [#how-retrieval-works]
At query time:
1. The user's message is embedded using the same Embedding Provider as the Store's Vectors
2. OpenAgent computes cosine similarity between the query vector and every Vector in the Store (plus any Child Stores)
3. The top N most similar Vectors are returned (N = Store's **Knowledge Count**)
4. Their text content is injected into the prompt context before the model call
The similarity score is computed on the fly and appears in the Message's `vectorScores` field — you can see which chunks were retrieved and how similar they were.
## What a Vector contains [#what-a-vector-contains]
| Field | Description |
| ------------ | -------------------------------------------------------------------- |
| `store` | Which Store this Vector belongs to |
| `file` | The source File |
| `index` | Position within the File, used to reconstruct document order |
| `text` | The raw chunk text |
| `imageUrl` | Original image URL for Vectors generated from image files |
| `provider` | Which Embedding Provider generated this Vector |
| `tokenCount` | Token count for this chunk |
| `data` | The embedding coordinates — a float array, dimension varies by model |
| `dimension` | Number of dimensions in the embedding |
## Browsing Vectors [#browsing-vectors]
Go to **Vectors** in the admin panel. Filter by Store or File. The list shows the chunk text, source file, position, and token count. For image files, the chunk text is the generated caption and `imageUrl` points back to the original image.
Reading chunk text directly is often the fastest way to debug retrieval issues. If the agent is pulling irrelevant chunks, look at what text those Vectors actually contain — the problem is usually in how the document was split, not in the retrieval algorithm itself.
**Common issues visible in the Vector list:**
* Chunks that are too large (many tokens) and dilute relevance when retrieved
* Chunks that split mid-sentence or mid-table, losing important context
* Chunks from different sections merged together because of inconsistent formatting in the source document
If you see these problems, try a different Split Provider and re-index.
## Checking retrieval quality [#checking-retrieval-quality]
The Message detail view shows `vectorScores` — the list of Vectors that were retrieved for a specific message, along with their similarity scores. Scores range from 0 to 1; a score below 0.6 usually means the retrieved chunk isn't very relevant to the query.
If relevant content exists in the knowledge base but isn't being retrieved:
* Raise **Knowledge Count** to retrieve more candidates
* Check if the chunk containing the answer is too large (the query might match a different chunk more closely)
* Consider switching to the `Hierarchy` Search Provider for large knowledge bases
## Re-indexing [#re-indexing]
Vectors are generated once per File. Changing the Store's **Embedding Provider** invalidates all existing Vectors — they were embedded in a different vector space and are no longer comparable to new queries.
To re-index after changing the Embedding Provider:
1. Go to **Files** and delete all Files belonging to the Store
2. Re-upload the Files
3. Processing runs automatically with the new provider
Deleting Files also deletes their Vectors immediately. There is no recovery — make sure you have the source documents before deleting.
## External vector stores [#external-vector-stores]
If you have an external vector database (such as Pinecone, Weaviate, or Qdrant), you can link it to a Store via the **Vector Store ID** field. Retrieval will query the external store instead of OpenAgent's built-in Vector table. The external store must be pre-populated separately — OpenAgent does not write to external vector stores automatically.
# Discord (/docs/connectors/pipes/discord)
# Discord [#discord]
The **Discord** Pipe answers Discord interactions (such as slash-command or mention events) with an OpenAgent agent.
## Configuration [#configuration]
| Field | Value |
| :------------- | :----------------------------------------------------------------------------- |
| **Type** | `Discord` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your bot token from the Discord Developer Portal. |
| **Public Key** | The application's **Public Key**, used to verify Discord's request signatures. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
In the Discord Developer Portal, set the application's **Interactions Endpoint URL** to:
```
https:///api/chat-webhook/discord/
```
OpenAgent verifies each request's Ed25519 signature against the **Public Key** before processing it, and answers Discord's endpoint validation handshake automatically.
## Streaming [#streaming]
Discord supports [streaming replies](/docs/connectors/pipes#streaming-replies). OpenAgent acknowledges the interaction, then edits the original deferred response as the model streams tokens.
# Facebook Messenger (/docs/connectors/pipes/facebook-messenger)
# Facebook Messenger [#facebook-messenger]
The **Facebook Messenger** Pipe connects a Facebook Page's Messenger inbox to a Store through Meta's Messenger Platform.
## Configuration [#configuration]
| Field | Value |
| :------------- | :---------------------------------- |
| **Type** | `Facebook Messenger` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your Page access token. |
| **App Secret** | Your Meta app's **App Secret**. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
In the Meta Developer Console, configure the Messenger webhook with:
* **Callback URL**: `https:///api/chat-webhook/facebook-messenger/`
* **Verify token**: the Pipe's **ID** (its `name`).
Meta sends a GET challenge when you save the webhook; OpenAgent responds using the verify token to confirm the subscription. Subscribe to the messaging events for your Page so incoming messages reach the Pipe.
# Pipes (/docs/connectors/pipes)
# Pipes [#pipes]
Pipes connect external messaging channels to OpenAgent Stores. A Pipe receives messages from a channel, sends them through the selected agent, and returns the agent's reply to the same channel.
## Available Channels [#available-channels]
## How a Pipe is configured [#how-a-pipe-is-configured]
Every Pipe shares a common set of fields on its edit page:
| Field | Purpose |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ID / Display name** | The Pipe's identifier and human-readable name. The **ID** doubles as the webhook verify token on several platforms (see each channel's page). |
| **Type** | The channel this Pipe connects to. |
| **Store** | The [Store](/docs/basic/stores) whose agent answers incoming messages. |
| **Token** | The channel's bot/access token. (Not used by [Weixin Claw](/docs/connectors/pipes/weixin-claw), which logs in by QR code.) |
| **Secret** | A per-channel secret used to verify requests — its label changes by channel (App Secret, Signing Secret, Public Key, Consumer Secret, Phone Number ID). Only administrators can edit this field. |
| **Domain** | Your public base URL. Setting it lets OpenAgent show the full webhook URL to paste into the channel's console. |
| **Is default** | Marks this Pipe as the default for its channel. |
| **State** | `Active` or `Inactive` — inactive Pipes stop receiving and answering messages. |
### Webhook URL convention [#webhook-url-convention]
Most channels deliver messages to OpenAgent through a webhook. OpenAgent exposes one URL per Pipe following this pattern:
```
https:///api/chat-webhook//
```
For example, a Slack Pipe named `support` is reachable at `https:///api/chat-webhook/slack/support`. Set the **Domain** field so the edit page can render the exact URL for you. Telegram registers its webhook automatically, and Weixin Claw uses QR login instead of a webhook.
## Streaming Replies [#streaming-replies]
Discord, Slack, and Telegram Pipes support streaming replies. When the selected model streams tokens, OpenAgent can update the channel response as text is generated instead of waiting for the full answer to finish.
For Discord interactions, OpenAgent edits the original deferred interaction response during streaming. For gateway messages, Slack messages, and Telegram chats, OpenAgent creates or updates the channel message through the channel API.
If a channel or provider does not support streaming for a specific request, OpenAgent falls back to sending the completed response.
## Store Selection [#store-selection]
Each Pipe routes incoming messages to a Store. Review the Store's model, tools, skills, file upload settings, and access controls before connecting it to a public messaging channel.
Pipes expose an agent outside the OpenAgent web UI. Treat channel credentials and webhook URLs as secrets, and only connect Stores that are intended for that audience.
# Slack (/docs/connectors/pipes/slack)
# Slack [#slack]
The **Slack** Pipe connects a Slack app to a Store so the agent can reply to events (such as messages and mentions) in your workspace.
## Configuration [#configuration]
| Field | Value |
| :----------------- | :----------------------------------------------------------------------------- |
| **Type** | `Slack` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your Slack **Bot User OAuth Token** (`xoxb-...`). |
| **Signing Secret** | Your app's **Signing Secret**, used to validate that requests come from Slack. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
Slack does not accept a programmatically registered webhook, so set it manually. In the Slack API portal, open your app's **Event Subscriptions** and set the Request URL to:
```
https:///api/chat-webhook/slack/
```
OpenAgent answers Slack's URL verification challenge automatically when you save the subscription.
## Streaming [#streaming]
Slack supports [streaming replies](/docs/connectors/pipes#streaming-replies): OpenAgent posts a message and updates it through the Slack API as the model produces tokens.
# Snapchat (/docs/connectors/pipes/snapchat)
# Snapchat [#snapchat]
The **Snapchat** Pipe connects a Snapchat bot to a Store through the Snap webhook.
## Configuration [#configuration]
| Field | Value |
| :------------- | :------------------------------------------------------------------- |
| **Type** | `Snapchat` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your Snapchat OAuth access token. |
| **App Secret** | Your app's **App Secret**, used to verify incoming webhook requests. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
The Snapchat webhook URL cannot be registered programmatically, so set it manually. In the Snap Developer Portal, open your bot's **Webhook** settings and set the URL to:
```
https:///api/chat-webhook/snapchat/
```
OpenAgent verifies incoming requests against the **App Secret** before answering, and replies through the Snap API.
# Telegram (/docs/connectors/pipes/telegram)
# Telegram [#telegram]
The **Telegram** Pipe connects a Telegram bot to a Store. Messages sent to the bot are answered by the agent in the same chat.
## Configuration [#configuration]
| Field | Value |
| :--------- | :-------------------------------------------------------- |
| **Type** | `Telegram` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your bot token from [@BotFather](https://t.me/BotFather). |
| **Domain** | Your public base URL (used to register the webhook). |
Telegram does not use a separate secret field.
## Webhook [#webhook]
Unlike the other channels, you do **not** register the webhook manually. When you save an active Telegram Pipe, OpenAgent calls Telegram's `setWebhook` for you, pointing it at `https:///api/chat-webhook/telegram/`. Make sure the **Domain** is set to a URL Telegram can reach.
## Streaming [#streaming]
Telegram supports [streaming replies](/docs/connectors/pipes#streaming-replies): OpenAgent edits the bot's message as the model produces tokens.
# Threads (/docs/connectors/pipes/threads)
# Threads [#threads]
The **Threads** Pipe answers replies and mentions on Meta Threads with an OpenAgent agent.
## Configuration [#configuration]
| Field | Value |
| :------------- | :---------------------------------- |
| **Type** | `Threads` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your Threads access token. |
| **App Secret** | Your Meta app's **App Secret**. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
In the Meta Developer Console, configure the Threads webhook with:
* **Callback URL**: `https:///api/chat-webhook/threads/`
* **Verify token**: the Pipe's **ID** (its `name`).
Meta sends the `hub.challenge` verification handshake when you save the webhook; OpenAgent completes it automatically. Each incoming reply or mention is routed to the Store's agent, and the response is posted back to the same thread.
# WeChat (/docs/connectors/pipes/wechat)
# WeChat [#wechat]
The **WeChat** Pipe connects a WeChat **Official Account** to a Store through the WeChat message callback. Messages that followers send to the Official Account are answered by the agent.
This Pipe is for **Official Accounts**. To drive a **personal** WeChat account instead, use [Weixin Claw](/docs/connectors/pipes/weixin-claw).
## Configuration [#configuration]
| Field | Value |
| :------------- | :------------------------------------ |
| **Type** | `WeChat` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your Official Account token. |
| **App Secret** | Your Official Account **App Secret**. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
In the WeChat Official Account platform, set the server (message callback) configuration:
* **URL**: `https:///api/chat-webhook/wechat/`
* **Token**: the Pipe's **ID** (its `name`), used for the signature verification handshake.
WeChat sends a GET challenge to validate the server URL; OpenAgent answers it automatically. Incoming messages arrive as XML, and OpenAgent replies to the platform so the follower receives the agent's answer.
# Weixin Claw (/docs/connectors/pipes/weixin-claw)
# Weixin Claw [#weixin-claw]
The **Weixin Claw** Pipe connects a **personal WeChat account** to a Store, so messages sent to that account are answered by the agent. Unlike the other channel Pipes (which use official platform APIs and webhooks), Weixin Claw authorizes a personal account by **scanning a QR code**, then listens for incoming messages in the background.
For a WeChat **Official Account**, use the [WeChat](/docs/connectors/pipes/wechat) Pipe instead.
## Configuration [#configuration]
| Field | Value |
| :-------- | :---------------------------------- |
| **Type** | `Weixin Claw` |
| **Store** | The Store whose agent should reply. |
Weixin Claw does not use the **Token**, secret, or webhook fields — the account is bound through QR login instead.
## Connecting an account [#connecting-an-account]
1. Create a Pipe of type **Weixin Claw** and select the Store that should answer messages.
2. On the Pipe edit page, choose **Login with Weixin QR**. OpenAgent starts a login session and displays a QR code.
3. **Scan the QR code with WeChat** and confirm on your phone. The status updates live as you scan and confirm (waiting → scanned → confirmed).
4. Once confirmed, the account is bound to the Pipe and OpenAgent begins monitoring it for new messages.
If the QR code expires before you confirm, start the login again to get a fresh code. Login state (the bound account token) is stored per-Pipe, so you normally only need to scan once.
## How it works [#how-it-works]
After login, a background monitor polls for new incoming messages, sends each one through the selected Store's agent, and replies in the same WeChat conversation. If the connection drops, the monitor retries automatically. Deleting the Pipe clears its stored login state.
Weixin Claw drives a **personal** WeChat account rather than an official account. Use it only where that is acceptable, and only connect Stores that are appropriate for the people who can message that account.
# WhatsApp (/docs/connectors/pipes/whatsapp)
# WhatsApp [#whatsapp]
The **WhatsApp** Pipe connects a WhatsApp Cloud API number to a Store through Meta's webhook platform.
## Configuration [#configuration]
| Field | Value |
| :------------------ | :--------------------------------------------------------------------- |
| **Type** | `WhatsApp` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your WhatsApp Cloud API access token. |
| **Phone Number ID** | The Cloud API **Phone Number ID** that outgoing replies are sent from. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
In the Meta Developer Console, configure the WhatsApp webhook with:
* **Callback URL**: `https:///api/chat-webhook/whatsapp/`
* **Verify token**: the Pipe's **ID** (its `name`).
Meta sends a GET challenge when you save the webhook; OpenAgent responds to it using the verify token so the subscription is confirmed.
# X Direct Messages (/docs/connectors/pipes/x-direct-messages)
# X Direct Messages [#x-direct-messages]
The **X Direct Messages** Pipe answers X (Twitter) DMs with an OpenAgent agent through the X Account Activity API.
## Configuration [#configuration]
| Field | Value |
| :------------------ | :-------------------------------------------------------------------------------- |
| **Type** | `X Direct Messages` |
| **Store** | The Store whose agent should reply. |
| **Token** | Your X access token. |
| **Consumer Secret** | Your app's **Consumer Secret** (API Secret Key), used for CRC webhook validation. |
| **Domain** | Your public base URL. |
## Webhook [#webhook]
The X Account Activity API webhook cannot be registered programmatically, so set it manually in your X developer app. Use:
```
https:///api/chat-webhook/x-dm/
```
When X issues its **CRC (Challenge-Response Check)**, OpenAgent answers it using the **Consumer Secret** so the webhook can be registered and stays subscribed. Incoming DMs are routed to the Store's agent and the reply is sent back in the same conversation.
# Embedding Providers (/docs/connectors/providers/embedding-providers)
# Embedding Providers [#embedding-providers]
An embedding provider converts text into numerical vectors. OpenAgent uses it at two moments: when a File is uploaded (each chunk is embedded and stored as a Vector), and when a user sends a message (the query is embedded so OpenAgent can find the most similar chunks). The same provider must be used for both — mixing providers produces meaningless similarity scores.
## Recommended defaults [#recommended-defaults]
If you're not sure what to pick:
* **Most teams**: `text-embedding-3-small` (OpenAI) as a fast, affordable default
* **Multilingual or highest accuracy**: `text-embedding-3-large` (OpenAI) or Cohere multilingual embeddings
* **Offline / local**: `nomic-embed-text` via Ollama
## Supported providers [#supported-providers]
| Provider | Notable models |
| --------------------------- | ---------------------------------------------------------------------------- |
| **OpenAI** | `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002` |
| **Gemini** (Google) | `text-embedding-004`, `embedding-001` |
| **Cohere** | `embed-english-v3.0`, `embed-multilingual-v3.0` |
| **Ollama** | `nomic-embed-text`, `mxbai-embed-large`, `all-minilm`, and others |
| **Azure OpenAI** | OpenAI embedding models deployed to your Azure subscription |
| **Alibaba Cloud** (Qwen) | `text-embedding-v1`, `text-embedding-v2`, `text-embedding-v3` |
| **Baidu Cloud** (Ernie) | ERNIE embedding models |
| **MiniMax** | MiniMax embedding models |
| **Tencent Cloud** (Hunyuan) | Hunyuan embedding models |
| **Jina** | `jina-embeddings-v3`, `jina-embeddings-v2-base-en` |
| **Hugging Face** | Embedding models via the Inference API |
| **Word2Vec** | Classic word vector models for legacy or offline use |
| **Local** | Any OpenAI-compatible local embedding endpoint (LM Studio, Infinity, TEI) |
## Adding a provider [#adding-a-provider]
1. **Providers → Add Provider**, category **Embedding**
2. Choose a **Type** from the table above
3. Enter **API Key** (and **Provider URL** for Azure, Jina, or local servers)
4. Set **Sub Type** to the model name (e.g. `text-embedding-3-small`)
5. Save — the provider appears immediately in the **Embedding Provider** dropdown on Stores
## Provider-specific configuration [#provider-specific-configuration]
The simplest setup. OpenAI offers three generations of embedding models:
* **Type**: OpenAI
* **API Key**: your OpenAI API key
* **Sub Type**: model name
| Model | Dimensions | Best for |
| ------------------------ | ---------- | -------------------------------------- |
| `text-embedding-3-small` | 1536 | General use, low cost |
| `text-embedding-3-large` | 3072 | Higher accuracy, multilingual |
| `text-embedding-ada-002` | 1536 | Legacy — prefer 3-small for new stores |
`text-embedding-3-small` is the recommended default. It is fast, affordable, and outperforms `ada-002` on most benchmarks.
Both `3-small` and `3-large` support **dimension reduction** — you can specify a lower dimension count to reduce storage requirements while retaining most accuracy. OpenAgent uses the model's default dimension unless you configure otherwise.
Use when you need OpenAI embeddings through your Azure subscription (compliance, VNet access, cost management):
* **Type**: Azure
* **API Key**: your Azure OpenAI key
* **Provider URL**: `https://your-resource.openai.azure.com`
* **Sub Type**: your deployment name (the name you gave the model in Azure — not the model family name)
The API version is handled automatically. Make sure the model deployed in Azure is an embedding model, not a chat completion model.
Ollama lets you run embedding models locally with no external API calls:
* **Type**: Ollama
* **Provider URL**: `http://localhost:11434` (or wherever Ollama is running)
* **Sub Type**: model name as it appears in `ollama list`
* **API Key**: not required
Pull the model before creating the provider:
```bash
ollama pull nomic-embed-text
```
Commonly used embedding models with Ollama:
| Model | Dimensions | Notes |
| ------------------- | ---------- | --------------------------------------- |
| `nomic-embed-text` | 768 | Fast, good quality, recommended default |
| `mxbai-embed-large` | 1024 | Higher quality, slower |
| `all-minilm` | 384 | Lightweight, lower accuracy |
Ollama embedding models work on CPU; GPU is not required for most sizes.
Jina provides high-quality embedding models with strong multilingual support:
* **Type**: Jina
* **API Key**: your Jina API key
* **Sub Type**: model name (e.g. `jina-embeddings-v3`)
`jina-embeddings-v3` supports 89 languages and late-interaction features useful for long documents. If your knowledge base contains documents in multiple languages and you're not using Cohere's multilingual model, Jina is a strong alternative.
Any server that implements the OpenAI embeddings API format works:
* **Type**: Local
* **Provider URL**: base URL of your server (e.g. `http://localhost:8080`)
* **Sub Type**: model identifier your server expects
* **Compatible Provider**: optional model ID to send when **Sub Type** is `custom-embedding`
* **API Key**: leave empty or set to `none`
Compatible servers: [Infinity](https://github.com/michaelfeil/infinity), [TEI (Text Embeddings Inference)](https://github.com/huggingface/text-embeddings-inference), LM Studio (embedding mode).
This is the fully offline option that doesn't depend on Ollama — useful if you already have an embedding inference stack. For custom OpenAI-compatible embedding servers, set **Compatible Provider** to the actual embedding model name expected by the server and configure custom pricing if the model is not one of OpenAgent's built-in embedding price entries.
## Choosing an embedding model [#choosing-an-embedding-model]
**For most English-language knowledge bases:** `text-embedding-3-small` (OpenAI). Low cost, reliable, integrates in minutes.
**For multilingual content:** Cohere `embed-multilingual-v3.0` or Jina `jina-embeddings-v3`. Both handle non-English documents and cross-language queries (English query matching a Chinese document, for example).
**For fully offline or on-premise deployments:** Ollama with `nomic-embed-text` or `mxbai-embed-large`. No data leaves your server. Works on CPU.
**For high-accuracy retrieval on large knowledge bases:** `text-embedding-3-large` or Cohere `embed-english-v3.0`. Higher dimensionality improves discrimination between similar chunks, at higher cost and slightly higher latency.
**For legacy or research workflows:** Word2Vec is available for compatibility with pre-existing vector pipelines, but modern neural embedding models outperform it significantly on retrieval tasks.
## The consistency rule [#the-consistency-rule]
All Vectors in a Store must be embedded by the same model. If you change the Store's Embedding Provider after Files have been uploaded, existing Vectors are no longer comparable to new query embeddings — retrieval will silently return wrong results.
After changing the Embedding Provider, delete all Files in the Store and re-upload them. Processing runs automatically with the new provider.
The reason: embedding models produce vectors in their own coordinate space. A vector from `text-embedding-3-small` and a vector from `nomic-embed-text` exist in completely different spaces — cosine similarity between them has no meaning.
## Embedding provider vs. chat model [#embedding-provider-vs-chat-model]
The embedding provider is entirely independent of the chat model. You can freely mix:
* OpenAI embeddings + Ollama chat model (send no data to OpenAI during conversations, only during indexing)
* Ollama embeddings + Claude chat model (fully offline indexing, cloud-based reasoning)
* Jina embeddings + a strong chat model (e.g. OpenAI `gpt-4.1`) for multilingual retrieval with high-quality generation
The Store has separate fields for **Model Provider** (chat) and **Embedding Provider** — configure each independently.
## Pricing and token counts [#pricing-and-token-counts]
Most embedding providers charge per token, but at rates far lower than chat models. For cost estimation:
* `text-embedding-3-small` (OpenAI): about $0.02 / 1M tokens (about $0.01 / 1M via Batch API)
* `text-embedding-3-large` (OpenAI): about $0.13 / 1M tokens (about $0.065 / 1M via Batch API)
* Ollama and local: free (compute cost only)
Embedding costs are incurred at upload time (once per chunk) and at query time (once per user message). Query-time costs are typically small compared to upload-time costs for large knowledge bases.
Prices change over time. The numbers above are a rough reference as of April 2026 — check your provider’s current pricing page for production budgeting (for OpenAI: [https://platform.openai.com/pricing](https://platform.openai.com/pricing)).
The embedding provider does not need to be from the same vendor as your chat model. Mixing providers is normal — choose each independently based on your requirements for retrieval quality, language coverage, and cost.
# Model Providers (/docs/connectors/providers/model-providers)
# Model Providers [#model-providers]
In OpenAgent, **Model Providers** represent the compute backbone of your agents. The platform abstracts the complexities of individual LLM APIs, providing a unified interface to manage intelligence, failover, and cost across your organization.
## Supported Providers [#supported-providers]
OpenAgent is designed for maximum flexibility, supporting a wide range of cloud-based and local intelligence engines. All providers are normalized into a unified interface for system prompts and tool calling.
| Provider | Notable Models / Notes |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **OpenAI** | GPT-5.5 / 5.2 / 5.1, GPT-4.1, GPT-4o, o4, o3, o1 series. |
| **Claude** | Claude Opus 4.7 / 4.5 / 4.1, Claude 3.x (Sonnet / Haiku). |
| **Gemini** | Gemini 3.1 Pro/Flash, Gemini 2.5 Pro/Flash. |
| **DeepSeek** | DeepSeek V4 (Pro/Flash), DeepSeek-R1. `deepseek-v4-flash` is handled as a thinking-capable model. |
| **Mistral** | Mistral Large, Mixtral, Codestral. |
| **Grok** | Grok-3, Grok-3-mini, Grok-2. |
| **Alibaba Cloud** | Qwen-Max, Qwen-Plus, Qwen-Turbo, Qwen3.6, and Qwen-VL/QVQ multimodal models. |
| **Baidu Cloud** | ERNIE 4.0, ERNIE 3.5. |
| **Tencent Cloud** | Hunyuan-Pro, Hunyuan-Standard. |
| **Volcano Engine** | Doubao-Pro, Doubao-Lite, and Doubao Seedance video models. Supports streamed thinking content when the provider has thinking enabled. |
| **Moonshot** | Moonshot-v1 (Kimi), including `kimi-for-coding`. |
| **iFlytek** | Spark-4.0 Ultra, Spark-3.5 Max. |
| **Baichuan** | Baichuan2-Turbo. |
| **StepFun** | Step-1, Step-2. |
| **Yi (01.AI)** | Yi-Large, Yi-34B. |
| **ChatGLM** | GLM-4, GLM-4V. |
| **MiniMax** | MiniMax-M3, M2.7, M2.5, M2.1, M2 (with `-highspeed` variants). |
| **OpenRouter** | Access to 200+ models via a single API key. |
| **Silicon Flow** | High-performance inference for open-weight models. |
| **GitHub Models** | Models via GitHub's serverless inference. |
| **Hugging Face** | Models via the HF Inference API. |
| **Azure OpenAI** | OpenAI models deployed on Azure infrastructure. |
| **Amazon Bedrock** | Claude, Llama, and Titan models via AWS. |
| **Ollama** | Local LLM execution (Llama, Mistral, Gemma, etc.). |
| **Local** | Any OpenAI-compatible API (vLLM, llama.cpp, LM Studio) with `compatibleProvider` field. |
| **OpenCode** | Delegate coding work to a local OpenCode agent server. |
| **OpenAI Compatible** | Any OpenAI-compatible API with a custom endpoint URL (no `compatibleProvider` needed). |
| **Writer** | Writer AI platform models. |
| **Cohere** | Command R+, Command R. |
***
## Quick Setup [#quick-setup]
New deployments can configure their first model provider from the **Quick Setup** onboarding page instead of the full provider form. It presents the common providers as one-click cards; picking one pre-fills sensible defaults (a default model / **Sub Type**) so you only need to supply the credential.
Quick Setup covers most supported providers, including OpenAI, Claude, Gemini, DeepSeek, Grok, Mistral, MiniMax, OpenRouter, Alibaba Cloud, Moonshot, Silicon Flow, Volcano Engine, Baidu Cloud, Tencent Cloud, iFlytek, ChatGLM, Baichuan, StepFun, Yi, Cohere, Writer, Hugging Face, GitHub Models, Amazon Bedrock, Azure, Ollama, Local, OpenCode, and OpenAI Compatible.
Each card indicates what it needs — most only require an **API Key**, while local or self-hosted options (Ollama, Local, OpenAI Compatible, OpenCode) ask for a **Provider URL** instead, and enterprise types (Azure, Amazon Bedrock, Tencent Cloud) request their extra endpoint or region fields. For anything not listed, or to fine-tune advanced settings, use the full provider form described below.
***
## Configuration [#configuration]
OpenAgent provides a unified form to connect these services. While most providers only require an **API Key**, some enterprise and local types have additional field mappings.
### Provider-Specific Settings [#provider-specific-settings]
Most providers (OpenAI, Claude, DeepSeek, OpenRouter) follow this pattern:
* **Type**: Select the provider name.
* **Sub Type**: The specific model ID (e.g., `gpt-4o`, `deepseek-chat`).
* **API Key**: Your secret token.
* **Fetch models**: For supported providers, use the sync button beside **Sub Type** to load the current model list from the provider API.
Azure requires specific endpoint and deployment details:
* **Type**: `Azure`
* **API Key**: Your Azure OpenAI API key.
* **Provider URL**: Your resource endpoint (e.g., `https://your-name.openai.azure.com`).
* **Client ID**: Enter your **Deployment Name**.
* **API Version**: (Optional) e.g., `2024-02-15-preview`.
OpenAgent uses the AWS SDK to connect to Bedrock:
* **Type**: `Amazon Bedrock`
* **Sub Type**: The Bedrock Model ID (e.g., `anthropic.claude-3-opus-20240229-v1:0`).
* **API Key**: Your AWS Secret Access Key (ensure AWS credentials are also available in your environment).
For local inference engines:
**Ollama:**
* **Type**: `Ollama`
* **Provider URL**: The address of your Ollama server (e.g., `http://localhost:11434`).
* **Sub Type**: The model name as it appears in `ollama list` (e.g., `llama3.2`).
* OpenAgent sends chat requests through Ollama's OpenAI-compatible `/v1` chat completions endpoint, so the base server URL is enough.
**Local (with compatible provider):**
* **Type**: `Local`
* **Provider URL**: Base URL of your local inference server.
* **Sub Type**: The model ID.
* **Compatible Provider**: Specify which API format it mimics (e.g., `gpt-3.5-turbo`) — used for correct message formatting.
OpenCode lets OpenAgent hand coding tasks to an OpenCode agent process:
* **Type**: `OpenCode`
* **Provider URL**: Your OpenCode server URL, usually `http://localhost:4096`.
* **API Key**: Optional.
OpenCode executes its own coding workflow and tool use internally. OpenAgent sends the conversation to OpenCode and streams the final response back; OpenAgent-side Store tools are not mapped into OpenCode tool calls.
For any server that implements the OpenAI Chat Completions API format at a custom URL:
* **Type**: `OpenAI Compatible`
* **Provider URL**: The base URL of your server (e.g., `https://api.your-service.com`).
* **Sub Type**: The model ID to send in requests.
* **API Key**: Your API key if the server requires authentication.
Use this for hosted OpenAI-compatible services (Together AI, Fireworks AI, Groq, etc.) where you don't need the `compatibleProvider` adapter logic. OpenAI Compatible providers use the Chat Completions style request path and can track configured custom input/output pricing; if no custom price is configured, usage cost falls back to `0` instead of failing.
***
## Key Platform Features [#key-platform-features]
OpenAgent provides several infrastructure-level capabilities that go beyond simple API wrapping.
### 1. Automated Failover (Child Models) [#1-automated-failover-child-models]
To ensure high availability, OpenAgent allows you to configure **Child Model Providers** at the Store level.
* If the primary provider returns a rate limit or a 5xx error, OpenAgent automatically routes the request to the next available child provider in your list.
* **Example**: Use `DeepSeek V4` for cost-efficiency, with `GPT-4.1` as a high-reliability fallback.
### 2. Context Logic Abstraction [#2-context-logic-abstraction]
OpenAgent handles the "dirty work" of different model families:
* **Thinking Mode**: Native support for reasoning models (o1, DeepSeek-R1, DeepSeek V4 Flash).
* **Prompt Unification**: Automatically formats system, user, and tool-call roles based on the provider's specific requirements.
Volcano Engine providers can stream reasoning content when **Enable Thinking** is turned on for the Provider. This reasoning is stored with the message detail and follows the Store's **Hide Thinking** display setting.
Alibaba Cloud Qwen-VL and QVQ models are treated as multimodal models, so image inputs and text tool outputs can be combined in vision-capable conversations.
Volcano Engine `doubao-seedance` models are treated as video generation models. OpenAgent creates a generation task, polls for completion, records token usage and cost, and returns the generated video URL when the task succeeds.
When a prompt or conversation history contains a supported document URL, OpenAgent can parse and cache the document text before calling the model. For OpenAI and Azure models this replacement is limited to local or private URLs; other providers can receive parsed content for supported document URLs.
### 3. Cost & Usage Tracking [#3-cost--usage-tracking]
By filling in the pricing fields in the Provider configuration, OpenAgent tracks expenditures at the organization level:
* **Input/Output Price**: Tracks cost per 1k tokens.
* **Message Auditing**: Every message stores the actual provider used and the calculated cost in the database for billing or reporting.
Unknown OpenAI-compatible model names no longer block message completion because of missing built-in pricing; OpenAgent records `0` cost unless custom input/output pricing is configured on the Provider.
### 4. OpenAI-Compatible API Access [#4-openai-compatible-api-access]
Each Model Provider edit page shows an OpenAI-compatible API panel with copyable **Base URL** and **Chat completions endpoint** values. External clients can call these endpoints with `Authorization: Bearer ` to reach that provider directly, without creating Store chat history. See [API Access](/docs/basic/stores#api-access) for the full request semantics and the Store-key alternative.
***
## Sampling Parameters [#sampling-parameters]
While OpenAgent exposes standard parameters (Temperature, Top-P, Min-P), the platform is designed to use **Provider Defaults** to ensure stable reasoning. Adjust these only if your specific agentic workflow requires high determinism or extreme creativity.
**Recommendation:** For agentic tool-use, always set Temperature to `0` to ensure strict adherence to JSON schemas.
# Storage Providers (/docs/connectors/providers/storage-providers)
# Storage Providers [#storage-providers]
A storage provider controls where the raw bytes of uploaded files are kept. It only affects the physical location of file data — not retrieval quality or agent behavior.
## Recommended default [#recommended-default]
Use **Local File System** unless you have a specific reason to offload file storage to an external backend.
## Supported types [#supported-types]
### Local File System [#local-file-system]
Files are stored on the server's local disk. This is the default and requires no additional configuration.
* **Best for**: single-server deployments, development environments, on-premise installations where you manage your own disk
* **No API key required**
* **No extra cost** beyond disk space
Files are written to the configured upload directory on the server running OpenAgent. If you're running behind a load balancer or across multiple nodes, all nodes must share the same filesystem (e.g. a network mount) or you will get inconsistent file access.
### Alibaba Cloud OSS [#alibaba-cloud-oss]
Files are uploaded to Alibaba Cloud Object Storage Service (OSS).
* **Best for**: deployments on Alibaba Cloud infrastructure, or when you need scalable cloud object storage
* **API Key required**: your Alibaba Cloud Access Key ID and Access Key Secret
* **Region and bucket**: configure the OSS region, bucket name, and endpoint
* **CDN domain**: optional custom domain used when OpenAgent builds public file URLs. If the value does not include a protocol, OpenAgent serves it as `https://`.
The original file bytes are stored in OSS. Processing (text extraction, chunking, embedding) still happens within OpenAgent — the storage provider only determines where the file bytes land.
### Casdoor (default fallback) [#casdoor-default-fallback]
When no storage provider is explicitly configured on a Store, OpenAgent falls back to using Casdoor's built-in storage. This requires Casdoor to be configured and available. For production deployments, explicitly configure Local File System or Alibaba Cloud OSS.
## Adding a provider [#adding-a-provider]
1. **Providers → Add Provider**, category **Storage**
2. Choose **Local File System** or **Alibaba Cloud OSS**
3. For Alibaba Cloud OSS, enter your **Access Key ID** (Client ID), **Access Key Secret** (Client Secret), **Region**, **Bucket**, endpoint, and optional **CDN domain**
4. Save
Then edit the Store and set **Storage Provider** to the provider you created.
## Setting a default [#setting-a-default]
If you have only one storage provider configured, all new Stores will default to it. If you have multiple providers, mark one active Storage Provider as **Is Default**. OpenAgent looks for that default provider first and falls back to an active Storage Provider only when no explicit default is set.
Global uploads from the Files list use the default Storage Provider. A user must also have a default Store because the uploaded File record is still attached to a Store for later vector processing.
If a deployment uses a separate provider database, OpenAgent checks that provider database as part of the default lookup. This keeps Store file uploads working consistently across standard and split-provider deployments.
## Changing the storage provider on an existing Store [#changing-the-storage-provider-on-an-existing-store]
Changing the Storage Provider on a Store does **not** migrate existing files. Files already uploaded remain in their original storage location. Only new uploads after the change will go to the new provider.
If you need all files in the same storage backend, delete the existing Files and re-upload them after switching the provider.
## What the storage provider does not affect [#what-the-storage-provider-does-not-affect]
* **File metadata** — name, size, status (`Pending`, `Processing`, `Finished`, `Error`), and Store association are always in OpenAgent's database
* **Vectors** — embeddings are always stored in OpenAgent's Vector table, regardless of storage provider
* **File processing** — text extraction and chunking happen within OpenAgent after the file is stored, independently of where the bytes live
* **Retrieval** — vector similarity search does not access the raw file bytes; it only uses Vectors
In practice, most deployments use **Local File System** throughout. Switch to **Alibaba Cloud OSS** only if you need scalable cloud object storage or are running on Alibaba Cloud infrastructure.
The storage provider is a low-visibility setting. It doesn't affect retrieval quality, agent behavior, or conversation performance. Set it once when configuring a new Store and leave it alone.
# Built-in Tools (/docs/connectors/tools/builtin-tools)
# Tools [#tools]
OpenAgent includes built-in tool implementations that can be exposed through Tool records without running an external MCP server. Create or edit Tool records in the **Tools** area, then attach the selected records to a Store's **Tools** field. The model sees each enabled tool's name and description alongside any MCP tools, and decides when to call them.
## Available tools [#available-tools]
### web\_search [#web_search]
Searches the web and returns a list of results. The model receives result titles, URLs, and snippets and can decide which to fetch for more detail.
Useful for: current events, topics not in the knowledge base, information that changes frequently.
Supported search engines: **DuckDuckGo** (default, no key required), **Bing**, **Google** (requires API key and Search Engine ID), **Baidu** (requires API key). Configure the engine in the Tool record's **Sub Type** field.
A `web_search` Tool record exposes both `web_search` and `image_search`. `image_search` returns image URLs, source pages, dimensions, and thumbnails for vision-capable models; if the selected model cannot accept images, the tool returns an error telling the model to continue with text-based tools.
When `web_search` is used, the search results are saved in the Message's `searchResults` field. The `webSearchEnabled` flag on the Message is set to `true`.
### web\_fetch [#web_fetch]
Fetches the full text content of a given URL. Returns the page's text after stripping HTML. Use after `web_search` when you want the model to read the full content of a specific page, not just the snippet.
If a site blocks the plain HTTP request with a 403 response, OpenAgent can retry through the browser-backed fetch path and return the rendered text. JavaScript-rendered pages, login flows, or pages that need interaction should still use `web_browser`.
### web\_browser [#web_browser]
Opens a real headless Chrome browser session (via chromedp). Enabling this tool type exposes **four** sub-tools to the model:
| Sub-tool | What it does |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `web_browser` | Navigate to a URL, wait for the page to render, return visible text content. Handles JavaScript SPAs and dynamic pages. |
| `browser_screenshot` | Navigate to a URL and capture a full-page screenshot, returned as base64-encoded PNG. |
| `browser_evaluate` | Navigate to a URL, evaluate a JavaScript expression in the page context, return the result. |
| `browser_click` | Navigate to a URL, click an element identified by a CSS selector, return the updated page content. |
Use `web_browser` when `web_fetch` returns incomplete or empty content for a page (JavaScript-rendered apps, login redirects, etc.).
### browser\_use [#browser_use]
Higher-level browser automation backed by the Claude-in-Chrome extension. Beyond reading page content, `browser_use` can interact with pages: click buttons, fill forms, navigate through multi-step flows, and extract structured data.
Use cases: logging into services, submitting forms, extracting data from paginated tables, interacting with web applications.
`browser_use` requires the Claude-in-Chrome browser extension to be installed and connected. It gives the agent direct control of a browser session.
### shell [#shell]
Executes shell commands on the server running OpenAgent and returns the output. Supports both one-shot foreground commands and long-running background sessions.
**Foreground mode**: runs a command and returns when it finishes. Configurable timeout (default 30s, max 300s).
**Background session mode** (set `background: true` or use `action` parameter): starts a persistent shell session and returns a `session_id`. Subsequent calls with `action: poll` read output, `action: write` or `action: submit` send input, `action: send_keys` sends key sequences (Enter, Ctrl+C, etc.), `action: resize` resizes the PTY, and `action: stop` terminates the session.
**PTY mode** (`pty: true`): allocates a pseudo-terminal for interactive CLI programs (vim, python REPL, npm interactive prompts, etc.).
When a foreground or PTY command times out, OpenAgent terminates the command's process group so child processes do not keep running after the parent shell exits. Stopping a background session follows the same cleanup path after sending the requested interrupt or stop signal.
`shell` gives the agent arbitrary command execution on the server. Only enable it in deployments where you control who can access the Store and you trust the model's judgment. Do not expose a Store with `shell` enabled to untrusted users.
### time [#time]
Returns the current date and time in UTC and the server's local timezone. Use this when the model needs to know the current time to answer questions or construct time-based queries.
Example: "What happened in the news today?" — the model can call `time` first to establish today's date, then call `web_search` with a date-qualified query.
### office [#office]
Reads and processes office document formats (DOCX, XLSX, PPTX). Useful when a user attaches a document to the chat and asks the agent to analyze it, without going through the Files/Vectors pipeline.
Available office sub-tools include Word read/write, Excel read/write, `pptx_read`, `pptx_write`, `pptx_template_analyze`, and `pptx_template_fill`. The PowerPoint writer creates editable `.pptx` files from an inline PptxGenJS script passed in the tool call. The script exports `build(pptx, ctx)`, adds slides through PptxGenJS, and can receive optional JSON `data` plus an `assets_dir` for images or icons.
For template-based PowerPoint generation, call `pptx_template_analyze` on a local `.pptx` file or chat attachment URL first. It returns slide, text slot, image, table, chart, SmartArt, and capacity metadata. Then call `pptx_template_fill` with a plan that selects, repeats, reorders, and fills template slides. Template filling can replace PNG/JPEG images while preserving the template picture frame, edit SmartArt node text, and resize supported SmartArt layouts. It validates missing targets, chart data, unsupported image formats, and new object collisions before writing the output file.
`pptx_write` requires Node.js on the OpenAgent host. Source deployments use the bundled worker under `tool/pptx-worker`; if dependencies are missing, OpenAgent can run `npm ci` in that worker directory before generating the deck.
### local\_file [#local_file]
Provides access to files on the local filesystem of the server running OpenAgent. Enabling this tool type exposes **six** sub-tools:
| Sub-tool | What it does |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local_special_dirs` | Returns common OS directories (Desktop, Documents, Downloads) with their absolute paths. Call this first when the user says "my Desktop" or "Downloads" without giving a full path. |
| `local_file_scan` | Scans a directory recursively and returns descendant files/directories with type, name, path, size, modified time, and optional text previews. Use `preview_chars` to control preview length or set it to `0` to skip previews. |
| `local_file_read` | Reads text from a local file by absolute path. Supported document types are parsed; other files are read as UTF-8 text. Supports offset and limit for large files. |
| `local_pdf_ocr_read` | Reads text from scanned local PDFs through OCR. It posts the PDF to the Tool record's **Provider URL**, or uses OpenAgent's managed local OCR service when the Provider URL is empty. |
| `local_file_write` | Writes text content to a local file. Requires an absolute path. Safe by default — will not overwrite unless `overwrite: true`. |
| `local_file_move` | Moves a file from one absolute path to another. Requires `confirmed: true` — the model must get explicit user confirmation before moving. |
`local_file` gives the agent read and write access to the server's filesystem. Only enable in deployments where you trust the model's access scope.
For PDF OCR, leave **Provider URL** empty to use the managed local service at `http://127.0.0.1:8001/ocr/pdf`, or set it to a compatible OCR HTTP endpoint that accepts multipart field `file` and returns `{"text":"recognized text"}`. The managed service requires Python 3.10+ on the OpenAgent host and installs its Python dependencies on first startup.
Older deployments may refer to `local_documents_scan`, `local_document_read`, or `local_text_write`. Current OpenAgent exposes the generic `local_file_scan`, `local_file_read`, `local_pdf_ocr_read`, and `local_file_write` APIs instead.
### gui [#gui]
Controls Windows desktop applications using the Windows UI Automation (UIA) API. Primarily useful in automation workflows on Windows servers where the agent needs to interact with a native desktop application.
`gui` is Windows-only and gives the agent direct control of the desktop UI. Use only in controlled Windows environments.
### video\_download [#video_download]
Downloads video content from a URL (YouTube, Vimeo, and other supported platforms). Returns the downloaded file path or the video metadata.
## Enabling tools [#enabling-tools]
Create a Tool record for each built-in tool you want to expose, then edit the Store and add those records to **Tools**. Save. All Chat sessions backed by this Store will have the selected tools available from the next message.
For tools that require credentials (e.g., `web_search` with Google, `web_browser` with a proxy), configure the credentials on the Tool record before attaching it to a Store.
## Combining with MCP [#combining-with-mcp]
Built-in tools and an MCP Server can coexist on the same Store. The model sees them all in a single unified tool list. OpenAgent routes each call to the right backend — built-in implementation or MCP server — transparently.
## Controlling tool use from the system prompt [#controlling-tool-use-from-the-system-prompt]
The model decides when to call a tool based on the tool description and the conversation context. You can influence this from the system prompt:
```
You have access to web_search and web_fetch.
Before answering any question about current events, call web_search first.
Only call web_fetch on URLs returned by web_search — do not fetch arbitrary URLs.
```
If you find the model over-using or under-using a particular tool, adjusting the system prompt is usually more effective than removing the tool entirely.
# MCP (Model Context Protocol) (/docs/connectors/tools/mcp)
# MCP (Model Context Protocol) [#mcp-model-context-protocol]
MCP is an open standard for exposing tools to language models. An MCP server defines a set of tools — each with a name, description, and parameter schema — that the model can call during a conversation. OpenAgent acts as an MCP client: it queries the server's tool list at conversation start and routes tool calls to the server during the conversation.
Any MCP-compatible server works with OpenAgent. No custom integration code is required.
For setup steps (adding a Server record, syncing tools, attaching to a Store), see [Servers](/docs/connectors/servers).
## How tool calls work [#how-tool-calls-work]
When a conversation starts, OpenAgent fetches the MCP server's tool list. Each tool's name and description are injected into the context sent to the model. During the conversation:
1. The model decides a tool is needed based on the user's request and the tool description
2. The model emits a structured tool call: `{ "tool": "get_weather", "args": { "city": "Tokyo" } }`
3. OpenAgent sends the call to the MCP server and waits for the result
4. The result is appended to the context: `{ "result": "Partly cloudy, 22°C" }`
5. The model reasons with the result and either calls another tool or produces a final response
Tool calls and results are shown inline in the chat UI and saved in the Message's `toolCalls` field.
OpenAgent queries the MCP server's tool list at conversation start. Changes to the server's exposed tools are reflected immediately in new conversations. Use **Sync** on the Server record after modifying the server's tool list to update the cached allowlist.
## Writing good tool descriptions [#writing-good-tool-descriptions]
The model relies entirely on descriptions to decide whether and how to use a tool. Vague descriptions produce wrong tool selection, missed calls, and incorrect arguments.
Good descriptions answer three questions:
1. What does this tool do?
2. When should the model use it — and when shouldn't it?
3. What do the parameters mean?
**Well-described tool:**
```json
{
"name": "lookup_order",
"description": "Look up the current status and details of a customer order by its order ID. Use this when the user asks about shipping, delivery, or order status. Do not use for billing or refund questions.",
"parameters": {
"order_id": {
"type": "string",
"description": "The order identifier. Format: ORD-XXXXXX (e.g. ORD-123456)"
}
}
}
```
**Poorly described tool:**
```json
{
"name": "get_order",
"description": "Gets order info.",
"parameters": {
"id": { "type": "string" }
}
}
```
The system prompt can also guide tool selection: `"If the user asks about order status, always use lookup_order before responding."`
## MCP ecosystem [#mcp-ecosystem]
The [MCP documentation](https://modelcontextprotocol.io) maintains a directory of open-source servers and SDKs. Commonly used servers:
| Server | What it does |
| ----------------------------------------- | --------------------------------------- |
| `@modelcontextprotocol/server-filesystem` | Read and write local files |
| `@modelcontextprotocol/server-github` | Search repos, read files, create issues |
| `@modelcontextprotocol/server-postgres` | Query PostgreSQL with natural language |
| `@modelcontextprotocol/server-slack` | Send messages, read channel history |
| `@modelcontextprotocol/server-fetch` | Fetch and extract content from URLs |
SDKs are available for TypeScript, Python, and other languages for building custom servers.
## Transport [#transport]
OpenAgent uses **StreamableHTTP** as the MCP transport. The Server record's **URL** must point to a StreamableHTTP endpoint. The optional **Token** field is sent as a Bearer token in the `Authorization` header.
## Related [#related]
* [Servers](/docs/connectors/servers) — add Server records, sync tools, manage the allowlist
* [Built-in Tools](/docs/connectors/tools/builtin-tools) — tools bundled with OpenAgent requiring no external server