启动会话

"Session"（会话）是环境中的一个智能体实例。每个会话引用一个智能体和一个环境（两者均单独创建），并在多次交互中维护对话历史。会话遵循两步生命周期：首先创建会话，然后发送用户事件以开始工作。您也可以使用 initial_events 将这两个步骤合并为一次调用。

创建会话

会话需要一个 agent ID 和一个 environment ID。智能体是版本化资源；以字符串形式传入 agent ID 会使用最新的智能体版本创建会话。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

要将会话固定到特定的智能体版本，请传入一个对象。这使您可以精确控制运行哪个版本，并独立地分阶段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

使用初始事件为会话设定初始内容

您可以在一次调用中创建会话并启动其工作。initial_events 是一个可选数组，包含在创建时发送给会话的初始事件，按顺序处理。它支持 user.message 和 user.define_outcome 事件，最多接受 50 个事件。非空列表会在同一次调用中启动智能体循环：会话直接以 running 状态创建，无需进一步请求。

以下示例创建一个在 initial_events 中包含单个 user.message 的会话：

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# initial_events 不会在创建响应中回显；需从
# 会话的事件列表中读回它们。
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

不接受其他事件类型。响应智能体轮次的事件（user.tool_confirmation、user.tool_result 和 user.custom_tool_result）不被接受，因为尚不存在智能体轮次；user.interrupt 也不被接受，因为没有可停止的轮次。与计划部署上的 initial_events 不同，会话的 initial_events 不接受 system.message。

initial_events 中的每个事件都会在创建响应返回之前按列表顺序进行验证和持久化，并分配一个服务器生成的 ID，就如同您在创建后立即将其发布到发送事件端点一样。每个事件的内容规则也与该端点相同。空列表等同于省略该字段。验证是全有或全无的：如果任何事件验证失败，整个请求将被拒绝，且不会创建会话。

在以下情况下，创建请求会被拒绝：

initial_events 中的 user.define_outcome 事件在与向现有会话发送该事件相同的条件下被接受；请参阅定义结果。

为会话覆盖智能体配置

您可以通过三种形式传入 agent：智能体 ID 字符串、固定版本对象（type: "agent"）或覆盖对象。覆盖形式会为单个会话更改智能体配置的部分内容。使用它可以在一个会话中尝试不同的模型或授予额外的工具，而无需对智能体进行版本化。对于覆盖形式，将 type 设置为 agent_with_overrides，并传入智能体的 id 以及可选的 version（省略 version 则使用智能体的最新版本）。然后包含 model、system、tools、mcp_servers 或 skills 中的任意字段，并赋予会话应使用的值。

每个可覆盖字段都遵循相同的三条规则：

• 省略该字段： 会话从其引用的智能体版本继承该值。
• 将该字段设置为 null，或对于列表字段设置为空数组： 会话在该字段被清除的情况下运行。此规则完全适用于 system 和 skills。有三个例外：
  • model 永远不可清除。会话始终需要一个模型，因此 model: null 会返回 400 agent_model_required 错误。
  • 当会话的有效 skills 非空时，清除 tools 会返回 400 错误，因为技能需要 read 工具。否则，tools: null 和 tools: [] 会清除该字段。
  • 当会话的有效 tools 仍包含引用智能体某个服务器的 mcp_toolset 时，清除 mcp_servers 会返回 400 错误。请在同一请求中覆盖 tools 以移除这些 mcp_toolset 条目，然后再清除 mcp_servers。
• 将该字段设置为某个值： 该值会完全替换智能体的值。覆盖永远不会与智能体的配置合并，因此 tools 覆盖必须列出会话应拥有的每个工具。同样，model 覆盖会完全替换智能体的 model 对象，因此智能体自身的 effort 不会被沿用。要让会话以特定的 effort 级别运行，请在覆盖的 model 对象中设置 effort。模型不支持的级别会返回 400 错误，而不含 effort 的 model 覆盖会以该模型的默认 effort 级别运行。

覆盖仅适用于您创建的会话。它们不会修改智能体资源或创建新的智能体版本，因此引用同一智能体的其他会话不受影响。

在响应中，agent 对象反映应用覆盖后会话运行所使用的配置。其 id 和 version 仍然标识覆盖所应用的智能体和版本。这使您可以将会话追溯到其基础智能体。

以下示例启动一个覆盖模型并清除系统提示的会话：

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# 响应中的 agent 是应用了覆盖后的已解析快照。
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

为会话固定推理地理位置

由于 model 覆盖会完全替换智能体的 model 对象，它也会为会话设置或清除模型的 inference_geo 固定：包含 inference_geo 的覆盖会固定为会话的模型请求提供服务的地理位置，而省略它的覆盖会清除智能体的固定，使会话遵循工作区的 default_inference_geo。覆盖的值会在创建会话时根据工作区的 allowed_inference_geos 进行验证。

以下示例从一个模型没有地理位置固定的智能体启动会话，通过在 model 覆盖中包含 inference_geo 将会话的模型请求固定到美国推理，并打印响应的 agent.model 中回显的值：

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

设置会话预算

要限制会话的支出上限，请在创建会话时传入可选的 budget 对象。预算是会话标价成本的硬性上限：平台按公开标价对会话消耗的所有内容进行计价，一旦累计总额达到 max_list_cost，会话就会停止发出新的模型请求。将 type 设置为 limit，并为 max_list_cost 提供 amount 和 currency。amount 是以字符串形式书写的美分整数，例如 "2500" 表示 $25.00；API 接受字符串而非数字，因此永远不会应用浮点舍入。USD 是目前唯一支持的货币。当会话达到上限时，它会暂停并进入空闲状态，停止原因为 budget_reached。上限在模型请求之间强制执行，因此跨越上限的请求会先完成，会话的最终标价成本可能会略微超出上限。预算只能在创建时附加：您可以稍后更改或移除它，但不能为创建时没有预算的会话添加预算。

以下示例创建一个预算为 $25.00 的会话；响应会在会话资源上回显 budget：

curl -fsSL https://api.anthropic.com/v1/sessions \
  -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
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

请参阅会话预算，了解强制执行的工作方式、哪些内容计入标价成本，以及预算在多智能体会话中的行为。

通过保管库进行 MCP 身份验证

如果您的智能体使用需要身份验证的 MCP 工具，请在创建会话时传入 vault_ids，以引用包含已存储 OAuth 凭据的保管库。Anthropic 代您管理令牌刷新。请参阅使用保管库进行身份验证，了解如何创建保管库和注册凭据。

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

启动会话

在不带 initial_events 的情况下创建会话会注册该会话，但不会启动任何工作；环境的沙箱在会话创建后立即开始配置，因此第一次工具调用无需等待它。要委派任务，请使用用户事件向会话发送事件。若要改为在创建请求中提供第一个事件，请参阅使用初始事件为会话设定初始内容。会话充当跟踪进度的状态机，而事件驱动实际执行。

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

请参阅会话事件流，了解如何流式传输智能体的响应以及处理工具确认。

请参阅会话状态，了解会话所经历的各种状态。

后续步骤