定义您的 Agent

Agent 是一种可复用的、带版本控制的配置，用于定义角色和能力。它将模型、系统提示、工具、MCP 服务器和技能打包在一起，以塑造 Claude 在会话期间的行为方式。

将 Agent 创建一次作为可复用资源，并在每次开始会话时通过 ID 引用它。Agent 带有版本控制，更易于跨多个会话进行管理。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 请求头。SDK 会自动设置该 beta 请求头。

Agent 配置字段

字段	描述
`name`	必填。Agent 的可读名称。
`model`	必填。驱动 Agent 的 Claude 模型。支持所有 Claude 4.5 及更高版本的模型。
`system`	定义 Agent 行为和角色的系统提示。系统提示与用户消息不同，用户消息应描述需要完成的工作。
`tools`	Agent 可用的工具。结合了预构建 Agent 工具、MCP 工具和自定义工具。
`mcp_servers`	提供标准化第三方能力的 MCP 服务器。
`skills`	通过渐进式披露提供特定领域上下文的技能。
`callable_agents`	该 Agent 可以调用的其他 Agent，用于多 Agent 编排。这是一项研究预览功能；申请访问权限以试用。
`description`	对 Agent 功能的描述。
`metadata`	用于您自己追踪的任意键值对。

创建 Agent

以下示例定义了一个使用 Claude Sonnet 4.6 并可访问预构建 Agent 工具集的编程 Agent。该工具集允许 Agent 编写代码、读取文件、搜索网络等。请参阅 Agent 工具参考以获取支持工具的完整列表。

要将 Claude Opus 4.6 与快速模式一起使用，请将 model 作为对象传递：{"id": "claude-opus-4-6", "speed": "fast"}。

响应会回显您的配置，并添加 id、version、created_at、updated_at 和 archived_at 字段。version 从 1 开始，每次更新 Agent 时递增。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

更新 Agent

更新 Agent 会生成新版本。传递当前的 version 以确保您是从已知状态进行更新。

更新语义

省略的字段将被保留。 您只需包含要更改的字段。
标量字段（model、system、name 等）将被替换为新值。system 和 description 可以通过传递 null 来清除。model 和 name 是必填项，不能被清除。
数组字段（tools、mcp_servers、skills、callable_agents）将被新数组完全替换。要完全清除数组字段，请传递 null 或空数组。

Agent 生命周期

操作	行为
更新	生成新的 Agent 版本。
列出版本	获取完整的版本历史记录以跟踪随时间的变化。
归档	Agent 变为只读。新会话无法引用它，但现有会话继续运行。

列出版本

获取完整的版本历史记录，以跟踪 Agent 随时间的变化情况。

归档 Agent

归档使 Agent 变为只读。现有会话继续运行，但新会话无法引用该 Agent。响应会将 archived_at 设置为归档时间戳。

后续步骤

配置工具以自定义 Agent 可以使用的能力。
附加技能以获取特定领域的专业知识。
开始会话并引用您的 Agent。

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"