会话操作

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



会话状态

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



更新智能体配置

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