定义您的智能体

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

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

智能体配置字段

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

创建智能体

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

示例使用 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": "medium" },
    "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 配置中，该智能体的固定值以及 subagents 或 workflows 的 predefined_agents 列表中列出的每个智能体的固定值，必须全部设置为相同的值或全部不设置；请参阅多智能体编排。若要稍后更改或清除固定值，请更新智能体的 model 对象；提供不含 inference_geo 的 model 会将其清除，如更新语义中所述。

更新智能体

当配置发生变化时，更新智能体会生成一个新版本。version 字段是可选的：提供它可实现 "optimistic concurrency"（乐观并发）控制（不匹配时返回 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：

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

更新语义

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

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

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

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

• multiagent 在更新保持 multiagent_20261001 类型时，会逐层合并到存储的块中。您省略的设置会保留其存储值，而您发送的 predefined_agents 列表会替换存储的列表。任何其他发送 multiagent 的更新都会整体替换存储的块，其省略的设置将采用默认值。传递 multiagent=None 可清除整个块。在块内部，null 会将设置重置为其默认值，因此将 workflows 设置为 null 会开启动态工作流。请参阅开启动态工作流。

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

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

• 其他智能体的 predefined_agents 列表不会被更新。 在 subagents 或 workflows 的 predefined_agents 列表中列出此智能体的其他智能体，会保留在它们创建时或上次更新发送该列表时所固定的版本，即使引用中省略了 version 也是如此。若要委派给新版本，请更新列出它的智能体，使列表引用新版本。

以下更新会清除描述，从 metadata 中删除 team 键，并将 workflows 设置为 null，从而开启动态工作流：

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

智能体生命周期

列出版本

获取完整的版本历史，以跟踪智能体随时间的变化。结果是分页的，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()}")

后续步骤