Skip to Content
操作流程Agent 確認流程

Agent 確認流程

重點：Agent 的 sandbox 提交是一個 LangGraph 工具（src/components/tools/custom/sandbox/factory.py），由 Agent 在對話回合中呼叫。前端沒有專屬的 confirm/reject 端點。前端的角色是「呈現提案、觀察結果」，實際確認發生在後續的對話回合。

為什麼有這個流程

當任務 requires_confirmation = true，Agent 不能在同一回合直接執行——它先提案，經過人為確認（下一回合）才提交執行。這是防止 Agent 未經同意就跑有副作用的任務。

兩段式（工具內部語意）

  1. 提案 mode="request"：Agent 帶 task_version_id + input 呼叫工具。後端建立一個 prepared 提案，回： 
    { "kind": "prepared", "proposal_id": "...", "proposal_receipt": "<簽章 token>",
  "summary": "...", "requires_confirmation": true, "task_id": "...", "task_version_id": "..." }
    • 會取代同一 principal 其他 pending 提案（superseded）。
    • proposal_receipt 是簽章多段 token（含 4 個點；只給不透明 id 會被判 forged_receipt）。
  2. 提交 mode="commit"：必須是後續回合（不允許同回合繞過）。Agent 只帶 proposal_receipt。後端驗證提案 receipt + 帶外的 turn receipt（綁定 company/chatroom/principal/human-message），才建立 run（submission_source="agent"），回： 
    { "status": "ok", "run_id": "...", "proposal_id": "..." }
    • 回應遺失重送：回 { "kind": "replay", "run_id": "..." }。

提案狀態 SandboxProposalState

prepared → committing → committed
其他：superseded / cancelled / expired / failed

前端要做什麼

前端不呼叫工具，但要把「有一個待確認的提案」呈現給使用者，並在確認後觀察結果：

  • menu 上的 requires_confirmation: true 告訴你這個任務會走確認流程。
  • 提案的 summary / requires_confirmation 透過對話/助理頻道呈現給使用者。
  • 工具的 list_submitted 會回該 principal 自己的 proposals[]（各帶 proposal_receipt）與 runs[]，讓後續回合能接續處理。
  • 確認提交後，前端就照 執行與取回結果 用 run 狀態端點觀察那個 run_id。

錯誤碼（工具層）

SandboxAgentConfirmError：validation_error、forged_receipt、not_found、internal_error。過期/他人的 receipt → { "status": "error", "error": "not_found" }。

人類使用者的提交走 POST /chatrooms/{id}/runs（見 執行流程）；Agent 提交走這個工具。兩者最終都產生一個可用 run 狀態端點觀察的 run。

Last updated on
執行與取回結果總覽