工作階段操作

工作階段建立後，您可以使用這些操作來讀取、更新、封存或刪除它。請參閱啟動工作階段以了解如何建立工作階段並向其傳送工作。



工作階段狀態

工作階段會經歷以下狀態。請參閱啟動工作階段以了解工作階段生命週期。



更新代理程式設定

您可以在工作階段進行中更新其 agent.tools 和 agent.mcp_servers（包括權限政策），而無需建立新的代理程式版本。更新僅限於該工作階段，不會傳播回底層的代理程式。

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

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

工作階段必須處於 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），且移除是單向的：只有目前具有 budget 的工作階段才接受非 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 狀態的工作階段無法封存；如果您需要立即封存，請傳送中斷事件。

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



刪除工作階段

刪除工作階段會永久移除其記錄、事件及相關聯的沙箱。處於 running 狀態的工作階段無法刪除；如果您需要立即刪除，請傳送中斷事件。

記憶體儲存區、保管庫、技能、環境和代理程式是獨立的資源，不受工作階段刪除的影響。您透過 Files API 上傳的檔案也不受影響，但工作階段本身產生的檔案是限定於該工作階段的，會連同其檔案系統一起永久刪除。在刪除工作階段之前，請先下載您需要保留的任何內容。

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