归档 Agent - Qoder CN 系列

归档指定 Agent。归档后不再出现在默认列表中，但仍可通过 ID 访问。

POST /api/v1/cloud/agents/{agent_id}/archive

归档指定的 Agent。归档后 Agent 不会出现在默认列表中，但仍可通过 ID 直接获取。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT>`

路径参数

参数	类型	必选	说明
`agent_id`	string	是	Agent 唯一标识

请求体

无需请求体。

示例请求

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents/agent_019eXXXX.../archive" \
  -H "Authorization: Bearer $QODER_PAT"

示例响应

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "用于 API 文档测试",
  "model": "ultimate",
  "system": "你是更新后的文档测试助手",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 2,
  "archived_at": "2026-05-18T15:27:22.698411Z",
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:22.698411Z"
}

响应字段

返回归档后的完整 Agent 对象。updated_at 字段会更新为归档操作的时间。

字段	类型	说明
`type`	string	固定值 `"agent"`
`id`	string	Agent 唯一标识
`name`	string	Agent 名称
`description`	string	Agent 描述
`model`	string	模型标识
`system`	string	系统提示词
`tools`	Agent tool 数组	工具配置列表
`mcp_servers`	MCP server 数组	MCP 服务器配置
`skills`	Skill binding 数组	Skill 绑定列表
`metadata`	Metadata 对象	自定义元数据
`multiagent`	Multiagent \| null	Agents 配置，未设置时为 `null`
`version`	integer	当前版本号
`archived_at`	string\|null	归档时间（ISO 8601），未归档时为 `null`
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	最后更新时间（ISO 8601），归档时刷新

错误码

HTTP	type	触发条件
401	`authentication_error`	PAT 无效或过期
403	`permission_error`	无权限归档此 Agent
404	`not_found_error`	指定 ID 的 Agent 不存在

注意事项

归档会保留 Agent 数据
归档后的 Agent 不会出现在 GET /api/v1/cloud/agents 的默认列表中
在 GET /api/v1/cloud/agents 传 include_archived=true 可让列表包含已归档 Agent
仍可通过 GET /api/v1/cloud/agents/{agent_id} 直接访问已归档的 Agent
归档操作是幂等的，重复归档不会报错
归档不会递增 Agent 的 version，也不会新增版本快照