归档 Agent

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

POST /v1/agents/{agent_id}/archive

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

​

请求头

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

​

路径参数

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

​

请求体

无需请求体。

​

示例请求

curl -X POST "https://api.qoder.com/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": {},
  "version": 2,
  "archived": true,
  "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 对象	自定义元数据
version	integer	当前版本号
archived	boolean	是否已归档
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 /v1/agents 的默认列表中
• 在 GET /v1/agents 传 include_archived=true 可让列表包含已归档 Agent
• 仍可通过 GET /v1/agents/{agent_id} 直接访问已归档的 Agent
• 归档操作是幂等的，重复归档不会报错
• 归档不会递增 Agent 的 version，也不会新增版本快照

​

相关

定义 Agent

创建可复用、可版本化的 Agent 配置。