啟動工作階段

「Session」（工作階段）是環境中的一個代理程式實例。每個工作階段都會參照一個代理程式和一個環境（兩者皆為分別建立），並在多次互動之間維護對話歷史記錄。工作階段遵循兩步驟的生命週期：首先建立工作階段，然後傳送使用者事件以開始工作。您也可以使用 initial_events 將這兩個步驟合併為一次呼叫。



建立工作階段

工作階段需要一個 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



使用初始事件為工作階段設定種子

您可以在一次呼叫中建立工作階段並開始其工作。initial_events 是一個選用的初始事件陣列，會在建立時傳送至工作階段，並依序處理。它支援 user.message 和 user.define_outcome 事件，最多接受 50 個事件。非空的清單會在同一次呼叫中啟動代理程式迴圈：工作階段會直接以 running 狀態建立，無需進一步的請求。

以下範例建立一個在 initial_events 中包含單一 user.message 的工作階段：

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML
)

# initial_events 不會在建立回應中回傳；列出工作階段的
# 事件即可看到植入的訊息。
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

不接受其他事件類型。回應代理程式回合的事件（user.tool_confirmation、user.tool_result 和 user.custom_tool_result）不被接受，因為尚不存在任何代理程式回合；而 user.interrupt 也不被接受，因為沒有可停止的回合。與排程部署上的 initial_events 不同，工作階段的 initial_events 不接受 system.message。

initial_events 中的每個事件都會在建立回應傳回之前，依清單順序進行驗證並持久化，並由伺服器指派 ID，就如同您在建立後立即將其發佈至傳送事件端點一樣。每個事件的內容規則也與該端點相同。空清單等同於省略該欄位。驗證採全有或全無的方式：若任何事件驗證失敗，整個請求都會被拒絕，且不會建立任何工作階段。

在下列情況下，建立請求會被拒絕：

initial_events 中的 user.define_outcome 事件，其接受條件與傳送至現有工作階段時相同；請參閱定義成果。



覆寫工作階段的代理程式設定

您可以用三種形式傳入 agent：代理程式 ID 字串、固定版本物件（type: "agent"），或覆寫物件。覆寫形式會針對單一工作階段變更代理程式設定的部分內容。您可以用它在某個工作階段中嘗試不同的模型或授予額外的工具，而無需為代理程式建立新版本。對於覆寫形式，請將 type 設為 agent_with_overrides，並傳入代理程式的 id 以及選用的 version（省略 version 則使用代理程式的最新版本）。接著加入 model、system、tools、mcp_servers 或 skills 中的任何欄位，並填入工作階段應使用的值。

每個可覆寫的欄位都遵循相同的三條規則：

• 省略該欄位： 工作階段會從其參照的代理程式版本繼承該值。
• 將欄位設為 null，或對清單欄位設為空陣列： 工作階段會在該欄位被清除的情況下執行。此規則完全適用於 system 和 skills。有三個例外：
  • model 永遠無法清除。工作階段始終需要一個模型，因此 model: null 會傳回 400 agent_model_required 錯誤。
  • 當工作階段的有效 skills 非空時，清除 tools 會傳回 400 錯誤，因為技能需要 read 工具。否則，tools: null 和 tools: [] 會清除該欄位。
  • 當工作階段的有效 tools 仍包含參照代理程式某個伺服器的 mcp_toolset 時，清除 mcp_servers 會傳回 400 錯誤。請在同一請求中覆寫 tools 以移除那些 mcp_toolset 項目，然後再清除 mcp_servers。
• 將欄位設為某個值： 該值會完整取代代理程式的值。覆寫永遠不會與代理程式的設定合併，因此 tools 覆寫必須列出工作階段應擁有的每一個工具。有一個例外：
  • 每個工作階段的 model 覆寫中的 effort 等級不會被套用，而且由於覆寫會完整取代代理程式的 model 物件，代理程式本身的 effort 也不會被沿用：以 model 覆寫建立的工作階段會以模型的預設 effort 等級執行。若要以特定的 effort 等級執行，請在代理程式上設定 effort，且不要為該工作階段覆寫 model。

覆寫僅適用於您建立的工作階段。它們不會修改代理程式資源或建立新的代理程式版本，因此參照同一代理程式的其他工作階段不受影響。

在回應中，agent 物件反映的是套用覆寫後工作階段執行所用的設定。其 id 和 version 仍然標識覆寫所套用的代理程式與版本。這讓您能將工作階段追溯回其基礎代理程式。

以下範例啟動一個覆寫模型並清除系統提示的工作階段：

# 回應中的 `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



固定工作階段的推論地理區域

由於 model 覆寫會完整取代代理程式的 model 物件，它也會設定或清除工作階段中模型的 inference_geo 固定值：包含 inference_geo 的覆寫會固定為工作階段模型請求提供服務的地理區域，而省略它的覆寫則會清除代理程式的固定值，使工作階段遵循工作區的 default_inference_geo。覆寫的值會在建立工作階段時依據工作區的 allowed_inference_geos 進行驗證。

以下範例從一個模型沒有地理區域固定值的代理程式啟動工作階段，透過在 model 覆寫中加入 inference_geo 將工作階段的模型請求固定至美國推論，並印出回應的 agent.model 中回傳的值：

# 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定。
session=$(ant beta:sessions create <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-opus-5
    inference_geo: us
environment_id: $ENVIRONMENT_ID
YAML
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"



設定工作階段預算

若要限制工作階段的花費上限，請在建立時傳入選用的 budget 物件。預算是工作階段定價成本的硬性上限：平台會以公開定價費率計算工作階段所消耗的一切，一旦累計總額達到 max_list_cost，工作階段便會停止發出新的模型請求。請將 type 設為 limit，並為 max_list_cost 提供 amount 和 currency。amount 是以字串表示的美分整數，例如 "2500" 代表 $25.00；API 接受字串而非數字，因此永遠不會套用浮點數捨入。USD 是目前唯一支援的貨幣。當工作階段達到上限時，它會暫停並進入閒置狀態，停止原因為 budget_reached。上限是在模型請求之間強制執行的，因此跨越上限的請求會先完成，而工作階段的最終定價成本可能會略微超過上限。預算只能在建立時附加：您之後可以變更或移除它，但無法為未設定預算而建立的工作階段新增預算。

以下範例建立一個預算為 $25.00 的工作階段；回應會在工作階段資源上回傳 budget：

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

請參閱工作階段預算以了解強制執行的運作方式、哪些項目計入定價成本，以及預算在多代理程式工作階段中的行為。



透過保存庫進行 MCP 驗證

如果您的代理程式使用需要驗證的 MCP 工具，請在建立工作階段時傳入 vault_ids，以參照包含已儲存 OAuth 憑證的保存庫。Anthropic 會代您管理權杖更新。請參閱使用保存庫進行驗證以了解如何建立保存庫及註冊憑證。

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



啟動工作階段

在沒有 initial_events 的情況下建立工作階段會註冊該工作階段，但不會開始任何工作；環境的沙箱會在工作階段建立後立即開始佈建，因此第一次工具呼叫不需等待它。若要委派任務，請使用使用者事件將事件傳送至工作階段。若要改為在建立請求中提供第一個事件，請參閱使用初始事件為工作階段設定種子。工作階段充當追蹤進度的狀態機，而事件則驅動實際的執行。

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

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

請參閱工作階段狀態以了解工作階段會經歷的各種狀態。



後續步驟