啟動工作階段

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

建立工作階段

工作階段需要一個 agent ID 和一個 environment ID。代理程式是具有版本的資源；以字串形式傳入 agent ID 會使用最新的代理程式版本建立工作階段。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

若要將工作階段固定至特定的代理程式版本，請傳入一個物件。這讓您能精確控制執行的版本，並獨立地分階段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

以初始事件為工作階段設定種子

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

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

seeded_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# initial_events 不會在建立回應中回傳；請從
# session 的事件清單中讀回。
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

不接受其他事件類型。回應代理程式回合的事件（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 覆寫會完整取代代理程式的 model 物件，因此代理程式本身的 effort 不會被沿用。若要讓工作階段以特定的 effort 等級執行，請在覆寫的 model 物件中設定 effort。模型不支援的等級會傳回 400 錯誤，而未包含 effort 的 model 覆寫則會以該模型的預設 effort 等級執行。

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

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

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

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# 回應中的 agent 是套用覆寫後解析出的快照。
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

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

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

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

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

設定工作階段預算

若要限制工作階段的花費上限，請在建立時傳入選用的 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 會代您管理權杖更新。請參閱使用保管庫進行驗證，了解如何建立保管庫及註冊憑證。

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

啟動工作階段

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

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

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

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

後續步驟