managed-agents-overview

# 智能体 — 概览 智能体为每个会话提供一个容器作为智能体的工作区。智能体循环在 Anthropic 的编排层运行；容器是智能体*工具*执行的地方——bash 命令、文件操作、代码。您创建一个持久化的**智能体**配置（模型、系统提示词、工具、MCP 服务器、技能），然后启动引用它的**会话**。会话将事件流式传输回给您；您发送用户消息和工具结果。 ## ⚠️ 强制流程：智能体（一次）→ 会话（每次运行） **为什么智能体是独立的对象：版本控制。** 智能体是一个持久化、有版本的配置——每次更新都会创建一个新的不可变版本，会话在创建时绑定到特定版本。这使您可以在不破坏正在运行的会话的情况下迭代智能体（调整提示词、添加工具），在更改出现回归时回滚，并进行版本 A/B 测试。如果您在每次运行时都 `agents.create()` 新的，这些都无法实现。 每个会话都引用一个预先创建的 `/v1/agents` 对象。创建一次智能体，存储 ID，并在多次运行中重用它。 | 步骤 | 调用 | 频率 | |---|---|---| | 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` 在此定义 | **一次。** 存储 `agent.id` **和** `agent.version`。 | | 2 | `POST /v1/sessions` — `agent: "agent_abc123"` 或 `{type: "agent", id, version}` | **每次运行。** 字符串简写使用最新版本。 | 如果您正准备在会话主体中编写带有 `model`, `system` 或 `tools` 的 `sessions.create()` — **请停止**。这些字段位于 `agents.create()` 中。会话仅接受一个*指针*。 **生成代码时，将设置与运行时分开。** `agents.create()` 属于设置脚本（或受保护的 `if agent_id is None:` 块），而不是热路径的顶部。如果用户的代码在每次调用时都执行 `agents.create()`，他们会积累孤立的智能体并无谓地支付创建延迟。正确的形态是：创建一次 → 持久化 ID（配置文件、环境变量、密钥管理器）→ 每次运行加载 ID 并调用 `sessions.create()`。 **要更改智能体的行为，请使用 `POST /v1/agents/{id}` — 不要创建一个新的。** 每次更新都会增加版本号；正在运行的会话保持其绑定的版本，新会话获取最新版本（或通过 `{type: "agent", id, version}` 显式绑定）。请参阅 `shared/managed-agents-core.md` → 智能体 → 版本控制。 ## 测试版请求头 智能体处于测试阶段。SDK 会自动设置所需的测试版请求头： | 测试版请求头