Agent Management Overview
Full lifecycle management APIs for RAG Agent instances.
RAG Agents are the runtime entities behind Knowledge Retrieval (knowledge/search) and Knowledge Q&A (knowledge/chat) services, with retrieval strategies carried by agent_config. The Agent Management APIs support creating, configuring, publishing, querying, and deleting Agents programmatically, without needing to visit the console.
Relationship to runtime APIs
Management APIs (this group) Runtime APIs
┌───────────────────────────┐
│ create / update / deploy │── produces agent_id ─▶ knowledge/search
│ list / get │── produces agent_id ─▶ knowledge/chat
│ copy / delete │
└───────────────────────────┘
First use the Management APIs to create and deploy an Agent and obtain its agent_id, then use the runtime APIs to perform retrieval or Q&A.
Lifecycle
create
└─▶ draft / beta
├─▶ update (edit draft config)
├─▶ deploy ─▶ deployed (version auto-increments)
│ ├─ change description only ─▶ update (version description only)
│ ├─ change config ─▶ update (edit draft config) ─▶ deploy a new version
│ ├─ copy ─▶ new Agent (draft / beta)
│ └─ delete ─▶ deleted
└─▶ delete ─▶ deleted
Noteagent_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 API is idempotent: repeated deletions do not return an error.
API list
All endpoints use POST + JSON body, with the path prefix /api/v1/indices/rag/app/.
| Operation | Endpoint | Description |
|---|---|---|
| Create Agent | POST /app/create | Create a new Agent; initial status draft |
| Update Agent | POST /app/update | Update name, description, or draft config |
| Deploy Agent | POST /app/deploy | Publish the beta draft as a new version |
| Delete Agent | POST /app/delete | Soft delete; the API is idempotent |
| List Agents | POST /app/list | Paginated query of Agents under the current tenant |
| Get Agent | POST /app/get | Get full Agent details, with support for specifying a version |
| Copy Agent | POST /app/copy | Copy an existing Agent into a new draft |
Scenes
Agents have two scenes (agent_scene):
| Scene | Value | Purpose | Runtime API |
|---|---|---|---|
| Knowledge Q&A | chat | Configure the Q&A model, citations, refusal, etc. | knowledge/chat |
| Knowledge Retrieval | search | Configure multi-index routing, fusion rerank, retrieval parameters, etc. | knowledge/search |
The agent_config structure differs between scenes. See each endpoint's documentation.
NoteExternally 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:
| Operation | Required permission |
|---|---|
| create | Knowledge Base - Create |
| update | Knowledge Base - Modify |
| deploy | Knowledge Base - Modify |
| delete | Knowledge Base - Delete |
| copy | Knowledge Base - Create |
Users with the "Knowledge Base - FullAccess" permission can perform all of the above operations. If a call returns 403, the current user lacks the required permission; contact the workspace administrator to adjust the role. Read operations (list / get) require only an API Key.