Feature: Agent Management
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Management feature is a core component of LobeChat, providing the framework for creating, configuring, and managing AI assistants, referred to as "Agents". Each agent can be customized with a unique persona, capabilities, and settings, including its system role, AI model, plugins, and voice services. This system allows users to tailor conversational experiences for specific tasks or domains.
This feature spans the entire application stack, from the database schema that defines an agent's properties, to the backend APIs that serve agent configurations, and the frontend state management and UI components that allow users to interact with and modify agents.
Architecture Overview
The Agent Management system follows a typical full-stack architecture, with distinct layers for data persistence, backend logic, and frontend presentation.
This diagram illustrates the data flow when a user interacts with the Agent settings, from the UI component down to the database and back.
Sources: src/features/AgentSetting/index.tsx, src/store/agent/store.ts, src/server/routers/lambda/agent.ts
Data Model and Schema
The foundation of an agent is its data model, defined in the database. The primary table is agents, which stores all configuration details for an agent. It has relationships with sessions, files, and knowledge bases.
Sources: packages/database/src/schemas/agent.ts, packages/database/src/models/tests/agent.test.ts
ER Diagram
This diagram shows the entity relationships between agents and other core entities like sessions, files, and knowledge bases.
agents Table Schema
The agents table contains all the configuration for an AI assistant.
| Column | Type | Description |
|---|---|---|
id | string | Unique identifier for the agent. |
slug | string | A URL-friendly slug for the agent. |
avatar | string | Emoji or URL for the agent's avatar. |
backgroundColor | string | Background color for the avatar. |
title | string | The display name of the agent. |
description | string | A short description of the agent's purpose. |
systemRole | text | The core prompt that defines the agent's persona and instructions. |
model | string | The default language model used by the agent (e.g., gpt-4o-mini). |
provider | string | The provider of the model (e.g., openai). |
params | jsonb | Advanced model parameters like temperature, top_p. |
tts | jsonb | Text-to-Speech configuration, including service and voice. |
chatConfig | jsonb | Chat-specific settings like historyCount and enableAutoCreateTopic. |
plugins | jsonb | A list of enabled plugins for the agent. |
tags | text[] | Keywords for categorizing and searching for the agent. |
Sources: packages/database/src/schemas/agent.ts:8-63, packages/database/src/repositories/dataImporter/tests/fixtures/agentsToSessions.json:4-89
chatConfig Object
The chatConfig JSON object fine-tunes the agent's conversational behavior.
| Key | Type | Description |
|---|---|---|
displayMode | string | The style of the chat window (chat or docs). |
historyCount | number | Number of historical messages to include in each request. |
enableHistoryCount | boolean | Toggles the history count limit. |
enableAutoCreateTopic | boolean | If true, a new topic is created automatically when a conversation exceeds a threshold. |
autoCreateTopicThreshold | number | The number of messages to exceed before creating a new topic. |
enableCompressHistory | boolean | If true, older messages are summarized to save tokens. |
Sources: packages/database/src/schemas/agent.ts:40-47, packages/database/src/repositories/dataImporter/tests/fixtures/agentsToSessions.json:20-31
Backend API (tRPC)
The backend exposes several tRPC endpoints under the agent router to manage agent data. These endpoints are consumed by the frontend to fetch and update agent configurations.
Sources: src/server/routers/lambda/agent.ts
Endpoints
| Procedure | Input | Output | Description |
|---|---|---|---|
getAgentConfig | { sessionId: string } | AgentConfig | Fetches the configuration for the agent associated with a given session ID. Handles creation of the "inbox" session if it doesn't exist. |
getKnowledgeBasesAndFiles | { agentId: string } | KnowledgeItem[] | Retrieves all available knowledge bases and files, marking those that are enabled for the specified agent. |
createAgentFiles | { agentId: string, fileIds: string[] } | void | Associates one or more files with an agent. |
deleteAgentFile | { agentId: string, fileId: string } | void | Disassociates a file from an agent. |
toggleFile | { agentId: string, fileId: string, enabled: boolean } | void | Toggles the enabled status of a file for an agent. |
createAgentKnowledgeBase | { agentId: string, knowledgeBaseId: string } | void | Associates a knowledge base with an agent. |
deleteAgentKnowledgeBase | { agentId: string, knowledgeBaseId: string } | void | Disassociates a knowledge base from an agent. |
toggleKnowledgeBase | { agentId: string, knowledgeBaseId: string, enabled: boolean } | void | Toggles the enabled status of a knowledge base for an agent. |
Sources: src/server/routers/lambda/agent.ts:31-139
getAgentConfig Sequence Diagram
This diagram shows the sequence of operations when the frontend requests an agent's configuration.
Frontend State Management (Zustand)
On the client side, a Zustand store (agentStore) is responsible for managing the state of all agents. It holds the list of available agents, the currently active agent's configuration, and provides actions to modify this state.
Sources: src/store/agent/store.ts
Key State Properties
agentList: An array of all available agents.currentIdentifier: The identifier of the currently active agent.defaultAgent: The default agent configuration, used as a fallback.meta,model,params,plugins,systemRole,tts: Slices of the active agent's configuration, allowing for granular updates.
Sources: src/store/agent/store.ts:68-87
Core Actions
| Action | Description |
|---|---|
updateAgentConfig | Updates the configuration of the currently active agent. |
resetAgentConfig | Resets the active agent's settings to the default configuration. |
updateAgentMeta | Updates the metadata (name, description, avatar, etc.) of an agent. |
switchAgent | Switches the active agent to a different one using its identifier. |
addAgent | Adds a new agent to the agentList. |
removeAgent | Removes an agent from the agentList. |
cloneAgent | Creates a duplicate of an existing agent. |
Sources: src/store/agent/store.ts:101-209
UI Components
The user interface for managing agent settings is encapsulated within the AgentSetting feature component. This component renders a tabbed interface, allowing users to configure different aspects of an agent.
Sources: src/features/AgentSetting/index.tsx
The settings are organized into the following tabs:
- Assistant Info (
AgentTab.Meta): Configure the agent's name, description, avatar, background color, and tags. - Role Configuration (
AgentTab.Prompt): Define the agent'ssystemRole, which is the core instruction set for its behavior. - Model Settings (
AgentTab.Modal): Select the AI model, provider, and set advanced parameters like temperature and token limits. - Plugin Settings (
AgentTab.Plugin): Enable or disable available plugins for the agent. - Voice Service (
AgentTab.TTS): Configure text-to-speech (TTS) and speech-to-text (STT) services, including voice selection.
Sources: locales/en-US/setting.json:5-12
Conclusion
The Agent Management feature is a comprehensive system that enables deep customization of AI assistants in LobeChat. It is well-structured, with clear separation of concerns between the database, backend services, and frontend state/UI. The use of a relational database with JSONB columns provides a flexible yet structured way to store complex agent configurations, while the tRPC API and Zustand store facilitate efficient data flow and state management. This robust architecture allows for a rich user experience in creating and interacting with specialized AI agents.