会话操作

会话创建后，您可以使用以下操作来读取、更新、归档或删除它。有关创建会话并向其发送任务的信息，请参阅启动会话。



会话状态

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



更新智能体配置

您可以在会话进行中更新会话的 agent.tools 和 agent.mcp_servers（包括权限策略），而无需创建新的智能体版本。更新仅作用于当前会话，不会传播回底层智能体。

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

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

会话必须处于 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 来移除上限。这两种操作都会自动恢复因会话达到上限而暂停的工作。替换的上限可以高于或低于当前上限，但必须严格大于会话已消耗的标价成本（list cost）；移除操作是单向的：只有当前已设置 budget 的会话才接受非 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 过滤器以致排除游标所在位置时也会返回 400 错误。其他查询参数（包括其余过滤器和 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 状态的会话无法归档；如果您需要立即归档，请发送中断事件。

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



删除会话

删除会话会永久移除其记录、事件和关联的沙箱。处于 running 状态的会话无法删除；如果您需要立即删除，请发送中断事件。

内存存储、保险库、技能、环境和智能体是独立的资源，不受会话删除的影响。您通过 Files API 上传的文件也不受影响，但会话本身生成的文件作用域限定于该会话，会随其文件系统一起被永久删除。请在删除会话之前下载您需要保留的任何内容。

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