定义你的代理

代理是一个可重用的、版本化的配置，定义了角色和功能。它捆绑了模型、系统提示、工具、MCP 服务器和技能，这些决定了 Claude 在会话期间的行为方式。

创建一次代理作为可重用资源，每次启动会话时通过 ID 引用它。代理是版本化的，更容易在许多会话中管理。

代理配置字段

创建代理

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

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

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

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

更新代理

更新代理会生成新版本。传递当前 version 以确保你从已知状态进行更新。

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

更新语义

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

• 标量字段（model、system、name 等）被替换为新值。system 和 description 可以通过传递 null 来清除。model 和 name 是必需的，不能被清除。

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

• 元数据在键级别合并。你提供的键被添加或更新。你省略的键被保留。要删除特定键，将其值设置为空字符串。

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

代理生命周期

列出版本

获取完整版本历史以跟踪代理如何随时间变化。

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

存档代理

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

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

后续步骤

• 配置工具以自定义代理可以使用的功能。
• 附加技能以获得特定领域的专业知识。
• 启动会话以引用你的代理。