工作階段操作

一旦工作階段（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。

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML

更新工作階段預算

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

擷取工作階段

ant beta:sessions retrieve --session-id "$SESSION_ID"

列出工作階段

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）可以在分頁請求之間變更。關於各列表端點共用的分頁欄位，請參閱分頁。

# --format raw 會回傳單一分頁封套及其 prev_page 與 next_page
# 游標；預設輸出會自動分頁且只輸出工作階段。
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# 將 next_page 游標以 --page 傳回即可擷取下一頁。
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# 將該回應的 prev_page 以 --page 傳入即可用同樣方式返回上一頁。

封存工作階段

封存工作階段可防止傳送新事件，同時保留其歷史記錄。running 狀態的工作階段無法封存；若要封存，請單獨傳送一個 user.interrupt 事件，並等待工作階段變為 idle。

ant beta:sessions archive \
  --session-id "$SESSION_ID"

刪除工作階段

刪除工作階段會永久移除其記錄、事件及相關的沙箱。running 狀態的工作階段無法刪除；若要刪除，請單獨傳送一個 user.interrupt 事件，並等待工作階段變為 idle。

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

ant beta:sessions delete \
  --session-id "$SESSION_ID"