会话操作

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

会话状态

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

更新智能体配置

您可以在会话进行中更新会话的 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。

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML

更新会话预算

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

检索会话

ant beta:sessions retrieve --session-id "$SESSION_ID"

列出会话

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）可以在分页请求之间更改。有关各列表端点共用的分页字段，请参阅分页。

# --format raw 返回一个包含 prev_page 和 next_page 游标的
# 分页封装；默认输出会自动分页且仅输出会话。
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# 将 next_page 游标作为 --page 传回以获取下一页。
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# 将该响应的 prev_page 作为 --page 传入即可按同样方式返回上一页。

归档会话

归档会话可阻止发送新事件，同时保留其历史记录。处于 running 状态的会话无法归档；若要归档，请单独发送一个 user.interrupt 事件，并等待会话变为 idle。

ant beta:sessions archive \
  --session-id "$SESSION_ID"

删除会话

删除会话可永久移除其记录、事件和关联的沙箱。处于 running 状态的会话无法删除；若要删除，请单独发送一个 user.interrupt 事件，并等待会话变为 idle。

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

ant beta:sessions delete \
  --session-id "$SESSION_ID"