定义您的智能体

"Agent"（智能体）是一种可复用、带版本的配置，用于定义角色设定和能力。它将模型、系统提示、工具、MCP 服务器和技能打包在一起，共同决定 Claude 在会话期间的行为方式。

只需将智能体作为可复用资源创建一次，之后每次启动会话时通过 ID 引用它即可。智能体带有版本，便于在大量会话中进行管理。

智能体配置字段

您还可以针对单个会话覆盖 model、system、tools、mcp_servers 和 skills，而无需更改智能体本身。model 覆盖会完整替换智能体的 model 对象，因此智能体自身的 effort 不会被沿用。若要以特定的 effort 级别运行会话，请在覆盖的 model 对象中设置 effort。请参阅为会话覆盖智能体配置。

创建智能体

以下示例定义了一个编码智能体，它使用 Claude Opus 5 并可访问预构建的智能体工具集。该工具集允许智能体编写代码、读取文件、搜索网络等。有关支持的工具的完整列表，请参阅智能体工具参考。

这些示例使用 curl、ant CLI 或某个 SDK。如果您尚未完成设置，快速入门涵盖了安装和客户端设置。

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

响应会回显您的配置，并添加 id、type、version、created_at、updated_at 和 archived_at 字段，同时用默认值填充您省略的 model 字段（例如 effort）。version 从 1 开始，每当更新改变了智能体时递增。

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "high" },
    "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": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

工具集上的 default_config 显示其默认权限策略 always_allow，除非您另行配置，否则将应用该策略。

固定推理地理区域

与 speed 和 effort 一样，inference_geo（推理地理区域）通过 model 的对象形式设置：以对象形式传递 model，并在 id 旁设置 inference_geo。该字段接受 "us" 或 "global"。未设置时，每个模型请求在被处理时遵循工作区的默认推理地理区域。有关工作区级别的地理区域控制和定价，请参阅数据驻留。

以下示例将智能体固定到美国推理，并打印智能体 model 对象中的 inference_geo 值：

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

inference_geo 固定值会在保存智能体时、从其创建会话时以及会话处理的每一轮中，对照工作区的 allowed_inference_geos 进行验证。如果工作区允许列表收窄导致某个固定值不再被允许，则无法从该智能体创建新会话，且正在运行的会话会拒绝后续轮次；固定值永远不会被豁免，因为工作区依赖它们来满足合规和数据驻留要求。

在不支持地理推理固定的模型上设置 inference_geo 会返回 400 错误；有关支持的模型，请参阅模型可用性。在 multiagent 配置中，协调者的固定值与每个名册成员的固定值必须全部设置为相同的值，或全部不设置；请参阅多智能体编排。若要稍后更改或清除固定值，请更新智能体的 model 对象；提供不含 inference_geo 的 model 会将其清除，如更新语义中所述。

更新智能体

当配置发生变化时，更新智能体会生成一个新版本。version 字段是可选的：提供它可实现乐观并发控制（不匹配时返回 409），省略它则无条件应用更新（最后写入者获胜）。对已归档智能体的更新会被拒绝。

使用 CLI 时，编辑智能体的文件并再次运行 ant apply；apply 会为您提供 version。

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

上述示例提供了来自创建响应的 version，因此只有在您读取智能体之后没有其他操作更改过它时，更新才会生效。若要无条件应用更新，请在请求中省略 version：

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 '{
    "description": "Writes and reviews code."
  }')

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

更新语义

• version 是可选的，提供时必须至少为 1。提供时，如果它与智能体的当前版本不匹配，请求将返回 409，即使您发送的字段已与存储的值一致也是如此；请重新读取智能体并重试。省略时，更新将无条件应用，最近一次更新会静默替换任何并发更新，且不会向任一调用方返回错误。对于交互式调用方，建议默认提供 version；而省略它则适合声明式应用循环，例如同步已签入的智能体定义的 CI 作业，此时由该循环拥有智能体。

• 省略的字段会被保留。 您只需包含想要更改的字段。

• 标量字段（model、system、name、description）会被新值替换。system 和 description 可通过传递 null 清除。model 和 name 是必填项，无法清除。在您提供的 model 对象中，effort 是唯一的例外：如果模型 id 未更改，省略 effort 会保持存储的 effort 级别不变。如果您更改了模型 id，省略的 effort 会重置为新模型的默认值。其他 model 字段会随对象一起被替换：提供不含 inference_geo 的 model 会清除智能体的推理地理区域固定值。

• 数组字段（tools、mcp_servers、skills）会被新数组完全替换。若要完全清除某个数组字段，请传递 null 或空数组。

• multiagent 会被整体替换，包括其 agents 名册。传递 null 可将其清除。

• Metadata 在键级别进行合并。您提供的键会被添加或更新。您省略的键会被保留。若要删除特定键，请将其值设置为 null。

• 无操作检测。 如果更新相对于当前版本没有产生任何变化，则不会创建新版本，并返回现有版本。

• 协调者名册不会被更新。 在其 multiagent.agents 名册中引用此智能体的协调者会保留在协调者创建或上次更新时固定的版本，即使该引用省略了 version。若要委派给新版本，请更新协调者，使其名册引用新版本。

智能体生命周期

列出版本

获取完整的版本历史，以跟踪智能体随时间的变化。结果是分页的，SDK 示例会自动获取每一页。

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

归档智能体

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

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

后续步骤