定义您的智能体

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

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



智能体配置字段

您还可以为单个会话覆盖 model、system、tools、mcp_servers 和 skills，而无需更改智能体本身。请参阅为会话覆盖智能体配置。



创建智能体

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

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

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

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

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

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "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
}

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



更新智能体

当配置发生更改时，更新智能体会生成一个新版本。version 字段是必填的，且必须与智能体的当前版本匹配，因此您始终是从已知状态进行更新。版本不匹配会返回 409 错误，对已归档智能体的更新会被拒绝。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



更新语义

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

• 标量字段（model、system、name、description）会被新值替换。system 和 description 可以通过传递 null 来清除。model 和 name 是必填的，无法清除。

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

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

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

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

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



智能体生命周期



列出版本

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

ant beta:agents:versions list --agent-id "$AGENT_ID"



归档智能体

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

ant beta:agents archive --agent-id "$AGENT_ID"



后续步骤