English ← MyDocs

定义你的 Agent

创建可复用、版本化的 Agent 配置。

Agent 是一个可复用、版本化的配置，用于定义角色和能力。它将模型、系统提示词、工具、MCP 服务器和技能打包在一起，塑造 Claude 在会话中的行为方式。

将 Agent 创建一次作为可复用资源，然后通过 ID 在每次启动会话时引用它。Agent 具有版本管理，在多个会话中更易于管理。

Note

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta header。SDK 会自动设置该 beta header。

Agent 配置字段

字段描述
name必填。Agent 的人类可读名称。
model必填。驱动 Agent 的 Claude 模型。支持所有 Claude 4.5 及更高版本的模型。
system系统提示词，用于定义 Agent 的行为和角色。系统提示词与用户消息不同，用户消息应描述需要完成的工作。
toolsAgent 可用的工具。结合了预构建 Agent 工具、MCP 工具和自定义工具。
mcp_servers提供标准化第三方能力的 MCP 服务器。
skills技能，提供具有渐进式披露的领域特定上下文。
multiagent协调器声明，列出此 Agent 可以委托的 Agent。参见多 Agent 会话。
descriptionAgent 功能的描述。
metadata用于自行跟踪的任意键值对。

创建 Agent

以下示例定义了一个编码 Agent，使用 Claude Opus 4.7 并可访问预构建的 Agent 工具集。该工具集允许 Agent 编写代码、读取文件、搜索网页等。完整的支持工具列表请参见 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": "Coding Assistant",
    "model": "claude-opus-4-7",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

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

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}'

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
)

const agent = await client.beta.agents.create({
  name: "Coding Assistant",
  model: "claude-opus-4-7",
  system: "You are a helpful coding agent.",
  tools: [{ type: "agent_toolset_20260401" }],
});

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Coding Assistant",
    Model = new("claude-opus-4-7"),
    System = "You are a helpful coding agent.",
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-4-7",
	},
	System: anthropic.String("You are a helpful coding agent."),
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		},
	}},
})
if err != nil {
	panic(err)
}

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("Coding Assistant")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_4_7)
        .system("You are a helpful coding agent.")
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .build()
);

$agent = $client->beta->agents->create(
    name: 'Coding Assistant',
    model: 'claude-opus-4-7',
    system: 'You are a helpful coding agent.',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
    ],
);

agent = client.beta.agents.create(
  name: "Coding Assistant",
  model: "claude-opus-4-7",
  system_: "You are a helpful coding agent.",
  tools: [{type: "agent_toolset_20260401"}]
)
Tip

要使用 Claude Opus 4.6 或 Claude Opus 4.7 的快速模式，请将 model 传为对象：{"id": "claude-opus-4-7", "speed": "fast"}。

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

{
  "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
}

更新 Agent

更新 Agent 时，如果配置发生变化会生成新版本。传递当前 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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

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

updated_agent = client.beta.agents.update(
    agent.id,
    version=agent.version,
    system="You are a helpful coding agent. Always write tests.",
)

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

const updatedAgent = await client.beta.agents.update(agent.id, {
  version: agent.version,
  system: "You are a helpful coding agent. Always write tests.",
});

console.log(`New version: ${updatedAgent.version}`);

var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
    Version = agent.Version,
    System = "You are a helpful coding agent. Always write tests.",
});

Console.WriteLine({{CONTENT}}quot;New version: {updatedAgent.Version}");

updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
	Version: agent.Version,
	System:  anthropic.String("You are a helpful coding agent. Always write tests."),
})
if err != nil {
	panic(err)
}

fmt.Printf("New version: %d\n", updatedAgent.Version)

var updatedAgent = client.beta().agents().update(
    agent.id(),
    AgentUpdateParams.builder()
        .version(agent.version())
        .system("You are a helpful coding agent. Always write tests.")
        .build()
);

IO.println("New version: " + updatedAgent.version());

$updatedAgent = $client->beta->agents->update(
    $agent->id,
    version: $agent->version,
    system: 'You are a helpful coding agent. Always write tests.',
);

echo "New version: {$updatedAgent->version}\n";

updated_agent = client.beta.agents.update(
  agent.id,
  version: agent.version,
  system_: "You are a helpful coding agent. Always write tests."
)

puts "New version: #{updated_agent.version}"

更新语义

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

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

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

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

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

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

Agent 生命周期

操作行为
更新当配置发生变化时生成新的 Agent 版本。
列出版本返回完整的版本历史，以便你跟踪随时间的变化。
归档使 Agent 变为只读。新会话无法引用它，但现有会话继续运行。

列出版本

获取完整的版本历史，跟踪 Agent 随时间的变化。

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

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

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

for await (const version of client.beta.agents.versions.list(agent.id)) {
  console.log(`Version ${version.version}: ${version.updated_at}`);
}

var versions = await client.Beta.Agents.Versions.List(agent.ID);
await foreach (var version in versions.Paginate())
{
    Console.WriteLine({{CONTENT}}quot;Version {version.Version}: {version.UpdatedAt:O}");
}

iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
for iter.Next() {
	version := iter.Current()
	fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
}
if err := iter.Err(); err != nil {
	panic(err)
}

for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
    IO.println("Version " + version.version() + ": " + version.updatedAt());
}

foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
    echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n";
}

client.beta.agents.versions.list(agent.id).auto_paging_each do
  puts "Version #{it.version}: #{it.updated_at.iso8601}"
end

归档 Agent

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

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

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

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

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

const archived = await client.beta.agents.archive(agent.id);
console.log(`Archived at: ${archived.archived_at}`);

var archived = await client.Beta.Agents.Archive(agent.ID);
Console.WriteLine({{CONTENT}}quot;Archived at: {archived.ArchivedAt:O}");

archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
if err != nil {
	panic(err)
}
fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))

var archived = client.beta().agents().archive(agent.id());
IO.println("Archived at: " + archived.archivedAt().orElseThrow());

$archived = $client->beta->agents->archive($agent->id);

echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n";

archived = client.beta.agents.archive(agent.id)
puts "Archived at: #{archived.archived_at.iso8601}"

下一步