啟動工作階段

「Session」（工作階段）是環境中的代理程式實例。每個工作階段都會參照一個 agent（代理程式）和一個 environment（環境）（兩者皆需分別建立），並在多次互動中維護對話歷史記錄。工作階段遵循兩步驟的生命週期：首先建立工作階段以佈建其沙箱，然後傳送使用者事件以開始工作。



建立工作階段

工作階段需要一個 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` 是解析後的快照：每個覆寫僅替換此 session 的
# 該欄位，而 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

請參閱工作階段事件串流以了解如何串流代理程式的回應並處理工具確認。

請參閱工作階段狀態以了解工作階段會經歷的各種狀態，以及工作階段操作以了解如何擷取、列出、更新、封存和刪除工作階段。

若要依照週期性排程自動建立工作階段，請參閱排程部署。