会话操作

会话存在后，可使用这些操作来读取、更新、归档或删除它。有关创建会话并向其发送工作的信息，请参阅启动会话。

会话状态

会话会经历以下状态。有关会话生命周期，请参阅启动会话。

更新智能体配置

您可以在会话进行中更新会话的 agent.tools 和 agent.mcp_servers，包括权限策略和每个工具的 Web 设置（例如域名过滤器），而无需创建新的智能体版本。更新仅作用于当前会话，不会传播回底层智能体。更新后的 allowed_domains 和 blocked_domains 将应用于会话的剩余部分。

会话创建后，只有智能体的 tools 和 mcp_servers 可以更改。若要使用与智能体不同的 model、system 或 skills 值运行会话，请在创建会话时使用智能体配置覆盖。智能体的模型配置（包括其 inference_geo 固定设置）同样无法在会话进行中更改：请在保存智能体时设置该固定设置，或在创建会话时通过 model 覆盖为单个会话设置或清除它。智能体配置的 system 字段在会话的整个生命周期内保持不变。在支持该功能的模型上，您仍然可以通过发送 system.message 事件在会话进行中追加系统级指导。

tools 或 mcp_servers 更新的语义是完全替换：提供的数组即为新值。若要保留现有条目，请先 GET 会话，修改数组，然后再 POST 回去。

会话必须处于 idle 状态才能更新智能体。要在会话运行时更新智能体，请单独发送一个 user.interrupt 事件，并等待会话变为 idle。如果有工作流运行处于打开状态，无论它正在运行还是已暂停，更新都会返回 400 错误，即使会话处于 idle 状态也是如此。中断不会结束运行，因此在您中断会话后，更新仍会失败。请发送一条 user.message 要求智能体停止其运行，或等待所有运行结束。

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

更新会话预算

创建时设置了预算的会话接受两种预算更新：使用新的 max_list_cost 替换上限，以及通过传递 budget=None 移除上限。这两种方式都会自动恢复因会话达到上限而暂停的工作。替换后的上限可以高于或低于当前上限，但必须严格大于会话已消耗的标价成本；而移除是单向的：只有当前已有预算的会话才接受非 null 的 budget，因此您无法重新添加已移除的预算，也无法为创建时未设置预算的会话添加预算。有关请求示例、错误行为以及哪些内容计入标价成本，请参阅会话预算。

检索会话

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出会话

GET /v1/sessions 的结果是分页的。使用 limit 查询参数控制页面大小。每个响应都包含一个 next_page 游标；在下一次请求中将其作为 page 参数传递即可获取下一页。当没有更多结果时，next_page 为 null。

若要返回上一页，请将 prev_page 作为 page 参数传递。当您位于第一页时，prev_page 为 null。

page 游标是不透明的，并编码了生成它的请求的 order。order 查询参数设置结果的排序方向，按创建时间 asc 或 desc；默认为 desc（最新的在前）。以不同的 order 重用游标会返回 400 错误，更改 created_at 过滤器使其排除游标所在位置也会如此。其他查询参数（包括其余过滤器和 limit）可以在分页请求之间更改。有关各列表端点共用的分页字段，请参阅分页。

# 将 `limit` 设得较低，使结果跨越多页。
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# 第一页的 `prev_page` 为 None；最后一页的 `next_page` 为 None。
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# 将 `next_page` 作为 `page` 传回以获取下一页。
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# 将 `prev_page` 作为 `page` 传回以返回上一页。
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# 对于仅向前的迭代，页面对象也可以直接迭代。

归档会话

归档会话可以阻止向其发送新事件，同时保留其历史记录。处于 running 状态的会话无法归档；要归档此类会话，请单独发送一个 user.interrupt 事件，并等待会话变为 idle。如果有工作流运行处于打开状态，即使会话处于 idle 状态，归档也可能返回 400 错误，或者可能成功并结束该运行。在归档之前，请发送一条 user.message 要求智能体停止其运行，或等待每个运行结束。然后在会话变为 idle 后将其归档。

client.beta.sessions.archive(session.id)

删除会话

删除会话会永久移除其记录、事件以及关联的沙箱。处于 running 状态的会话无法删除；要删除此类会话，请单独发送一个 user.interrupt 事件，并等待会话变为 idle。如果有工作流运行处于打开状态，即使会话处于 idle 状态，删除也可能返回 400 错误，或者可能成功。删除成功后，不会有 workflow_run 事件报告该会话运行的结束。在删除之前，请发送一条 user.message 要求智能体停止其运行，或等待每个运行结束。然后在会话变为 idle 后将其删除。

记忆存储、保管库、技能、环境和智能体是独立的资源，不受会话删除的影响。您通过 Files API 上传的文件同样不受影响，但会话自身生成的文件的作用域限定于该会话，会随其文件系统一起被永久删除。在删除会话之前，请下载您需要保留的所有内容。在最后一轮结束时写入的输出文件，可能需要在会话进入 idle 状态后几秒钟才会出现在会话的文件列表中，因此请先确认您期望的文件已列出。

client.beta.sessions.delete(session.id)