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

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).

---

Basic Information

Agent Profile

The Agent Profile fields enrich Store listings, especially in the Hub:

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 — 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 — 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, Chat, Files, Issues, Security, Insights, and owner-only Settings. See the 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 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

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)

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

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 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

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 for the two modes and silence auto-stop behavior.

---

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.

---

Insights & Security

A published agent's usage analytics and its automated security audit live on the Agent page, under the Insights and Security tabs.

---

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

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

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 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 <key> 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 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

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)

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.

---