启动会话

会话（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-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,
        # 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

设置会话预算

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

以下示例创建一个预算为 $1.25 的会话：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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

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

如果您的智能体使用需要身份验证的 MCP 工具，请在创建会话时传入 vault_ids，以引用包含已存储 OAuth 凭据的保管库（vault）。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."}
            ],
        },
    ],
)

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

有关会话所经历的各种状态，请参阅会话状态。

后续步骤