claudecode的agent定义

{Agent Name}

{一句话描述，给 coordinator / 用户看，决定何时调用此 Agent}

---

Configuration

字段	值
name	"{Agent Name}"
model	"claude-sonnet-4-6"
description	"{一句话描述}"
tools	(见下方 Tools)
mcp_servers	(见下方 MCP Servers)
skills	(见下方 Skills)
callable_agents	(见下方 Callable Agents)
metadata	team: {team}，version: 1.0

---

System Prompt

你是 {角色名称}。{一句话角色定位}。

人格

• {性格特点 1}
• {性格特点 2}
• {对异常 / 不确定信息的处理态度}

职责

1. {职责 1}
2. {职责 2}
3. {职责 3}

约束

• 不能 {约束 1}
• 不能 {约束 2}
• 不捏造或推测未从工具返回的数据

工具使用策略

优先级	工具	何时调用
首选	{tool_name}({param})	{触发条件}
按需	{tool_name}({param})	{触发条件}

回答格式

{场景名称} （调用 {tool}）：

【{维度 1}】{模板}
【{维度 2}】{模板}
【{维度 3}】{模板}

如有异常，附加：

【⚠️ 告警】{描述}

---

Tools

[
  {
    "type": "agent_toolset_20260401",
    "default_config": {
      "permission_policy": { "type": "always_allow" },
      "configs": [
        { "name": "web_fetch", "enabled": false }
      ]
    }
  },
  {
    "type": "mcp_toolset",
    "mcp_server_name": "{server-name}"
  },
  {
    "type": "custom",
    "name": "{tool_name}",
    "description": "{详细描述：功能、何时用、何时不用、参数含义。至少 3-4 句}",
    "input_schema": {
      "type": "object",
      "properties": {
        "param1": { "type": "string", "description": "{说明}" }
      },
      "required": ["param1"]
    }
  }
]

说明：

• 按需保留所需工具类型，删除不使用的条目
• agent_toolset_20260401：完整预置工具集（文件读写、bash、网络搜索等）
• mcp_toolset：接入指定 MCP 服务器的全部工具
• custom：自定义工具，需提供完整 input_schema

---

MCP Servers

[
  {
    "type": "url",
    "name": "{server-name}",
    "url": "https://example.com/mcp"
  }
]

无 MCP 依赖时，传 [] 或省略此字段。

---

Skills

[
  { "type": "anthropic", "skill_id": "xlsx" },
  { "type": "custom", "skill_id": "{skill_id}", "version": "latest" }
]

无 Skill 依赖时，传 [] 或省略此字段。

---

Callable Agents

[
  {
    "agent_id": "agent_xxx",
    "description": "{何时调用此子 Agent，触发条件要明确}"
  }
]

无多 Agent 编排需求时，传 [] 或省略此字段。此功能目前为研究预览，需申请访问权限。

---

Metadata

{
  "team": "{team}",
  "version": "1.0"
}

---

API 请求示例

创建 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": "{Agent Name}",
    "description": "{一句话描述}",
    "model": "claude-sonnet-4-6",
    "system": "（粘贴上方 System Prompt 全文）",
    "tools": [ ... ],
    "mcp_servers": [ ... ],
    "skills": [],
    "callable_agents": [],
    "metadata": {
      "team": "{team}",
      "version": "1.0"
    }
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")
echo "Agent ID: $AGENT_ID, Version: $AGENT_VERSION"

更新 Agent

# 仅传需要变更的字段，其余字段自动保留
updated=$(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": "（更新后的 System Prompt）"
}
EOF
)
echo "New version: $(jq -r '.version' <<< "$updated")"

查看版本历史

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)"'

归档 Agent

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")"

---

字段更新语义

字段类型	更新行为
标量 （model、system、name 等）	以新值替换；system、description 可传 null 清空
数组 （tools、mcp_servers、skills、callable_agents）	完整替换；传 null 或 [] 可清空
metadata	键级合并；删除某键需将其值设为空字符串
未传字段	自动保留原值

---

相关文档

• Managed Agents 概览
• 定义 Agent
• 工具配置
• Skills 配置
• Session 管理
• 多 Agent 编排
• MCP Connector