Full lifecycle management APIs for RAG Agent instances
A RAG Agent serves as the runtime entity for knowledge retrieval (
First use the Management APIs to create and deploy an Agent, then obtain its
All endpoints use
Agents support two scenarios (
The
Write operations (
Holding the
knowledge/search) and knowledge-based Q&A (knowledge/chat). The Agent Management APIs enable programmatic creation, configuration, deployment, querying, and deletion of Agents—eliminating the need to manually perform these operations in the console.
Relationship with Runtime APIs
First use the Management APIs to create and deploy an Agent, then obtain its agent_id and use it with Runtime APIs to initiate retrieval or Q&A requests.
Lifecycle
The
agent_config can only be modified in the beta draft version. For already-deployed versions, only the agent_version_desc field may be updated. To modify configuration, first use the update API to revise the draft, then use the deploy API to publish a new version. Deletion is soft deletion and idempotent: repeated deletion calls will not raise errors.API List
All endpoints use POST with JSON request bodies and share the base path /api/v1/indices/rag/app/.
| Operation | Endpoint | Description |
|---|---|---|
| Create Agent | POST /app/create | Creates a new Agent in initial draft state |
| Update Agent | POST /app/update | Updates name, description, or draft configuration |
| Deploy Agent | POST /app/deploy | Deploys the beta draft as a new version |
| Delete Agent | POST /app/delete | Performs soft deletion; idempotent |
| List Agents | POST /app/list | Paginated list of Agents under the current tenant |
| Get Agent Details | POST /app/get | Retrieves full Agent information, optionally specifying a version |
| Copy Agent | POST /app/copy | Copies an existing Agent to generate a new draft |
Scenarios
Agents support two scenarios (agent_scene):
| Scenario | Value | Purpose | Corresponding Runtime API |
|---|---|---|---|
| Knowledge Q&A | chat | Configure Q&A model, citation behavior, refusal logic, etc. | knowledge/chat |
| Knowledge Retrieval | search | Configure multi-knowledge-base routing, hybrid ranking, retrieval parameters, etc. | knowledge/search |
agent_config structure differs between the two scenarios; refer to individual API documentation for details.
Externally, use
chat (internally mapped to general); search remains consistent both internally and externally.Permission Requirements
Write operations (create, update, deploy, delete, copy) require corresponding knowledge base permissions, determined by roles configured in Business Space 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 |
Knowledge Base – FullAccess permission grants authority to perform all the above operations. A 403 response indicates insufficient permissions; contact your Business Space administrator to adjust your role. Read operations (list, get) require only an API Key.