Skip to main content

Agent Management Overview

Full lifecycle management APIs for RAG Agent instances

RAG Agents are the runtime entities behind Knowledge Search (knowledge/search) and Knowledge Q&A (knowledge/chat). The Agent Management APIs support creating, configure, publish, query, and delete Agents programmatically — without needing to visit the console.

Relationship to runtime APIs

First use Management APIs to create and deploy an Agent, obtain agent_id, then use runtime APIs to perform search or Q&A.

Lifecycle

agent_config can only be modified on the beta draft version. Published versions only support modifying the agent_version_desc field; to update the configuration, first update the draft via the update endpoint, then publish a new version via the deploy endpoint. Deletion is a soft delete and the interface is idempotent: repeated deletion calls will not error.

API list

All endpoints use POST + JSON body, path prefix /api/v1/indices/rag/app/.
OperationEndpointDescription
Create AgentPOST /app/createCreate a new Agent; initial status draft
Update AgentPOST /app/updateUpdate name, description, or draft config
Deploy AgentPOST /app/deployPublish beta draft as a new version
Delete AgentPOST /app/deleteSoft delete; repeated deletions don't error
List AgentsPOST /app/listPaginated list of Agents in the current tenant
Get AgentPOST /app/getFull Agent details; supports specifying a version
Copy AgentPOST /app/copyCopy an existing Agent into a new draft

Scenes

Agents have two scenes (agent_scene):
SceneValuePurposeRuntime API
Knowledge Q&AchatConfigure Q&A model, citations, refusal, etc.knowledge/chat
Knowledge SearchsearchConfigure multi-index routing, fusion, retrieval paramsknowledge/search
The agent_config structure differs between scenes — see each endpoint's documentation.
Externally chat is used (internally mapped to general); search is consistent inside and out.

Permissions

Write operations (create / update / deploy / delete / copy) require the corresponding Knowledge Base permissions, determined by the user's role in Workspace Member Management:
OperationRequired permission
createKnowledge Base - Create
updateKnowledge Base - Modify
deployKnowledge Base - Modify
deleteKnowledge Base - Delete
copyKnowledge Base - Create
Users with the "Knowledge Base - FullAccess" permission can perform all of the above. If a call returns 403, the current user lacks the required permission — contact the workspace admin to adjust the role. Read operations (list / get) require only an API Key.
General
Knowledge Base
Documents
Chunks
Sync Jobs
Data Import
Knowledge Search & Chat
Agent Management