工作階段操作

一旦工作階段（session）存在，即可使用這些操作來讀取、更新、封存或刪除它。關於建立工作階段並向其傳送工作，請參閱啟動工作階段。

工作階段狀態

工作階段會依序經歷以下狀態。關於工作階段生命週期，請參閱啟動工作階段。

更新代理設定

您可以在工作階段進行中更新其 agent.tools 和 agent.mcp_servers，包括權限政策以及各工具的網頁設定（例如網域篩選器），而無需建立新的代理版本。更新僅作用於該工作階段，不會回傳至底層代理。更新後的 allowed_domains 和 blocked_domains 會套用於工作階段的其餘部分。

工作階段建立後，只有代理的 tools 和 mcp_servers 可以變更。若要以不同於代理的 model、system 或 skills 值執行工作階段，請在建立工作階段時使用代理設定覆寫。代理的模型設定（包括其 inference_geo 固定設定）同樣無法在工作階段進行中變更：請在儲存代理時設定此固定設定，或在建立單一工作階段時透過 model 覆寫來設定或清除它。代理所設定的 system 欄位在工作階段的整個生命週期內固定不變。在支援此功能的模型上，您仍可透過傳送 system.message 事件，在工作階段進行中附加系統層級的指引。

tools 或 mcp_servers 更新的語意為完全取代：所提供的陣列即為新值。若要保留現有項目，請先 GET 工作階段，修改陣列後再 POST 回去。

工作階段必須處於 idle 狀態才能更新代理。若要在工作階段執行中更新代理，請單獨傳送一個 user.interrupt 事件，並等待工作階段變為 idle。如果有工作流程執行處於開啟狀態，無論是執行中或已暫停，即使工作階段為 idle，更新也會傳回 400 錯誤。中斷並不會結束執行，因此在您中斷工作階段後，更新仍會失敗。請傳送一則 user.message 要求代理停止其執行，或等到所有執行都結束。

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

更新工作階段預算

以預算建立的工作階段接受兩種預算更新：以新的 max_list_cost 取代上限，以及透過傳遞 budget=None 將其移除。兩者都會自動恢復因工作階段達到上限而暫停的工作。取代用的上限可以高於或低於目前的上限，但必須嚴格大於工作階段已消耗的定價成本；而移除是單向的：非 null 的 budget 僅在目前已有預算的工作階段上才會被接受，因此您無法重新加入已移除的預算，也無法為未設定預算而建立的工作階段新增預算。如需請求範例、錯誤行為以及哪些項目計入定價成本，請參閱工作階段預算。

擷取工作階段

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出工作階段

GET /v1/sessions 的結果會分頁。使用 limit 查詢參數來控制每頁大小。每個回應都包含一個 next_page 游標；在下一次請求中將其作為 page 參數傳入，即可取得下一頁。當沒有更多結果時，next_page 為 null。

若要返回上一頁，請將 prev_page 作為 page 參數傳入。當您位於第一頁時，prev_page 為 null。

page 游標是不透明的，並編碼了產生它的請求之 order。order 查詢參數設定結果的排序方向，依建立時間為 asc 或 desc；預設為 desc（最新的在前）。以不同的 order 重複使用游標會傳回 400 錯誤，變更 created_at 篩選條件使其排除游標所在位置時亦然。其他查詢參數（包括其餘篩選條件和 limit）可以在分頁請求之間變更。關於各列表端點共用的分頁欄位，請參閱分頁。

# 將 `limit` 設低，讓結果跨越多個分頁。
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# 第一頁的 `prev_page` 為 None；最後一頁的 `next_page` 為 None。
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# 將 `next_page` 作為 `page` 傳回以取得下一頁。
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# 將 `prev_page` 作為 `page` 傳回以回到上一頁。
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# 若只需向前迭代，page 物件本身也可直接迭代。

封存工作階段

封存工作階段可防止傳送新事件，同時保留其歷史記錄。running 狀態的工作階段無法封存；若要封存，請單獨傳送一個 user.interrupt 事件，並等待工作階段變為 idle。如果有工作流程執行處於開啟狀態，即使工作階段為 idle，封存也可能傳回 400 錯誤，或者可能成功並結束該執行。在封存之前，請傳送一則 user.message 要求代理停止其執行，或等到每個執行都結束。然後在工作階段變為 idle 後再將其封存。

client.beta.sessions.archive(session.id)

刪除工作階段

刪除工作階段會永久移除其記錄、事件及相關聯的沙箱。running 狀態的工作階段無法刪除；若要刪除，請單獨傳送一個 user.interrupt 事件，並等待工作階段變為 idle。如果有工作流程執行處於開啟狀態，即使工作階段為 idle，刪除也可能傳回 400 錯誤，或者可能成功。刪除成功後，不會有任何 workflow_run 事件回報該工作階段各個執行的結束。在刪除之前，請傳送一則 user.message 要求代理停止其執行，或等到每個執行都結束。然後在工作階段變為 idle 後再將其刪除。

記憶儲存庫、保管庫、技能、環境和代理都是獨立的資源，不受工作階段刪除的影響。您透過 Files API 上傳的檔案同樣不受影響，但工作階段本身產生的檔案範圍僅限於該工作階段，會連同其檔案系統一併永久刪除。在刪除工作階段之前，請先下載您需要保留的任何內容。在最後一輪結束時寫入的輸出檔案，可能需要在工作階段進入 idle 後數秒才會出現在工作階段的檔案列表中，因此請先確認您預期的檔案已列出。

client.beta.sessions.delete(session.id)