启动会话

"Session"（会话）是环境中的一个智能体实例。每个会话引用一个智能体和一个环境（两者均需单独创建），并在多次交互中维护对话历史记录。会话遵循两步生命周期：首先创建会话以配置其沙箱，然后发送用户事件以开始工作。



创建会话

会话需要一个 agent ID 和一个 environment ID。智能体是带版本的资源；以字符串形式传入 agent ID 会使用最新的智能体版本启动会话。

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

要将会话固定到特定的智能体版本，请传入一个对象。这样您可以精确控制运行的版本，并独立地分阶段推出新版本。

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



为会话覆盖智能体配置

您可以通过三种形式传递 agent：智能体 ID 字符串、固定版本对象（type: "agent"）或覆盖对象。覆盖形式可为单个会话更改智能体配置的部分内容。使用它可以在某个会话中尝试不同的模型或授予额外的工具，而无需为智能体创建新版本。对于覆盖形式，将 type 设置为 agent_with_overrides，并传入智能体的 id，可选地传入 version（省略 version 则使用智能体的最新版本）。然后包含 model、system、tools、mcp_servers 或 skills 中的任意字段，并设置会话应使用的值。

每个可覆盖字段都遵循相同的三条规则：

• 省略该字段： 会话从其引用的智能体版本继承该值。
• 将字段设置为 null，或对于列表字段设置为空数组： 会话运行时该字段被清空。此规则完全适用于 system、mcp_servers 和 skills。有两个例外：
  • model 永远不可清空。会话始终需要一个模型，因此 model: null 会返回 400 agent_model_required 错误。
  • 当会话的有效 skills 非空时，清空 tools 会返回 400 错误，因为技能需要 read 工具。否则，tools: null 和 tools: [] 会清空该字段。
• 将字段设置为某个值： 该值会完全替换智能体的值。覆盖永远不会与智能体的配置合并，因此 tools 覆盖必须列出会话应拥有的所有工具。

覆盖仅应用于您创建的会话。它们不会修改智能体资源，也不会创建新的智能体版本，因此引用同一智能体的其他会话不受影响。

在响应中，agent 对象反映的是应用覆盖后会话所运行的配置。其 id 和 version 仍然标识覆盖所应用到的智能体和版本。这使您能够将会话追溯到其基础智能体。

# 响应中的 `agent` 是解析后的快照：每个覆盖项仅替换
# 此会话的该字段，而 agent 资源保留其 id 和版本。
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



通过保管库进行 MCP 身份验证

如果您的智能体使用需要身份验证的 MCP 工具，请在创建会话时传入 vault_ids，以引用包含已存储 OAuth 凭据的 "vault"（保管库）。Anthropic 会代表您管理令牌刷新。有关如何创建保管库和注册凭据，请参阅使用保管库进行身份验证。

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



启动会话

创建会话会配置环境的沙箱，但不会启动任何工作。要委派任务，请使用用户事件向会话发送事件。会话充当跟踪进度的状态机，而事件驱动实际的执行。

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

有关如何流式传输智能体的响应和处理工具确认，请参阅会话事件流。

有关会话所经历的各种状态，请参阅会话状态；有关检索、列出、更新、归档和删除会话，请参阅会话操作。

要按定期计划自动创建会话，请参阅计划部署。