Agent Management Overview

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

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

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:

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.

​Relationship to runtime APIs

​Lifecycle

​API list

​Scenes

​Permissions

Relationship to runtime APIs

Lifecycle

API list

Scenes

Permissions