工作階段操作

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



工作階段狀態

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



更新代理設定

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

工作階段建立後，只有代理的 tools 和 mcp_servers 可以變更。若要以不同於代理的 model、system 或 skills 值執行工作階段，請在建立工作階段時使用代理設定覆寫。代理設定的 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



擷取工作階段

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 錯誤；其他查詢參數（包括篩選條件和 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 狀態的工作階段無法刪除；如果您需要立即刪除，請傳送中斷事件。

檔案、記憶體儲存區、保管庫、技能、環境和代理都是獨立的資源，不會受到工作階段刪除的影響。

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