啟動工作階段

「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-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 的覆寫會固定處理工作階段模型請求的地理區域，而省略它的覆寫則會清除代理的固定設定，使工作階段遵循工作區的 default_inference_geo。覆寫的值會在建立工作階段時依據工作區的 allowed_inference_geos 進行驗證。

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

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # 完整取代代理程式的 `model`：重新指定 `id`，並加入 `inference_geo` 以固定位置。
        "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 是以字串表示的美分整數，例如 "125" 代表 $1.25。API 採用字串而非數字，因此永遠不會套用浮點數捨入。USD 是目前唯一支援的貨幣。當工作階段達到上限時，它會暫停並進入閒置狀態，停止原因為 budget_reached。上限是在模型請求之間強制執行的，因此跨越上限的那個請求會先完成，工作階段最終的牌價成本可能會略微超過上限。預算只能在建立時附加：您之後可以變更或移除它，但無法為建立時未設定預算的工作階段新增預算。

以下範例建立一個預算為 $1.25 的工作階段：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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

透過保管庫進行 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."}
            ],
        },
    ],
)

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

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

後續步驟