会话操作

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



会话状态

会话会经历以下状态。请参阅启动会话了解会话生命周期。



更新代理配置

您可以在会话中途更新会话的 agent.tools 和 agent.mcp_servers（包括权限策略），而无需创建新的代理版本。更新仅限于会话本地，不会传播回底层代理。

会话创建后，只有代理的 tools 和 mcp_servers 可以更改。要使用与代理不同的 model、system 或 skills 值运行会话，请在创建会话时使用代理配置覆盖。代理配置的 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



检索会话

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 错误；其他查询参数（包括过滤器和 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 状态的会话无法删除；如果您需要立即删除，请发送中断事件。

文件、内存存储、保管库、技能、环境和代理是独立的资源，不受会话删除的影响。

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