智慧體的環境停止後,工作階段仍可繼續存在。self_hosted 環境使用的運算資源和檔案由你的應用程式管理。
啟動環境
應用程式可以在建立工作階段後啟動運算資源。先使用供應商的 SDK 或 API 啟動資源,再使用工作階段的環境 ID 和環境金鑰連接執行器。
請參閱 OpenAI Cookbook 中由應用程式管理沙盒的範例。

每個工作階段的環境都應由單一元件管理。儲存工作階段與供應商運算資源之間的對應關係。即使收到重複或並行的請求,也不得重複建立環境。
透過 webhook 啟動運算資源
你也可以等到處理輸入需要連線至環境時,再啟動運算資源。API 會先發出 agent.session.action_required 事件,其中包含 required_action.type: "environment_connection",然後等待執行器連線。你的 webhook 處理常式會啟動環境或重新連線至環境。
請參閱 OpenAI Cookbook 中透過 webhook 管理沙盒的範例。

依照 webhook 設定步驟,註冊處理常式以接收 agent.session.action_required 和 agent.session.failed 事件。處理常式使用的簽署密鑰和工作階段讀取憑證,必須與執行器的環境金鑰分開保管。如果多個供應商的處理常式共用同一個專案,請將事件送至負責該工作階段的處理常式。
處理常式和背景工作程式各有分工:
- 驗證事件並加入佇列。 處理常式先驗證 webhook 簽章。只有當
data.required_action.type為environment_connection時,才將連線請求加入佇列。工作階段失敗事件也要加入佇列。只有成功加入佇列後,才回傳表示成功的 HTTP 回應。 - 檢查目前狀態。 背景工作程式會取得工作階段資料。略過已刪除的工作階段和已處理完畢的動作。如果自架的工作階段仍需要連線,請使用
session.environment.id和session.environment.remote_url啟動其執行器或讓執行器重新連線。如果工作階段仍處於失敗狀態,請釋放其運算資源。
工作階段的事件串流會以 agent.session.requires_action 回報同一個請求。當必要動作為 function_call 時,應提供函式執行結果,無須啟動環境。若等到收到回合建立事件或 agent.session.in_progress 事件才啟動離線的執行器,就已經太晚了。
部署處理常式後,建立自架的工作階段並傳送輸入。請確認工作目錄與處理常式中的設定一致,且所選的智慧體符合處理常式設定的所有篩選條件。如果執行器在期限內連線,原先提交的輸入就會繼續處理。
保持環境可用或停止環境
你可以讓運算資源在回合之間持續運作,供後續回合使用,也可以在回合結束後保留一段緩衝時間再停止資源。請協調關閉作業與新進工作。收到連線請求或開始執行工作時,請取消尚未執行的關閉作業。停止運算資源前,請再次確認狀態。
不能只憑閒置事件就判定可以安全關閉環境。連線請求解除時,就可能收到閒置事件,此時等候中的輸入可能尚未開始執行回合。如果應用程式無法協調關閉作業與新進工作,請讓環境持續運作。
中斷連線後重新連線
連線事件會回報狀態。使用 agent.session.environment.connected 和 agent.session.environment.disconnected 觀察連線狀態。建立連線的過程中也可能發出 agent.session.environment.pending 或 agent.session.environment.failed 事件。這些事件不會要求啟動運算資源。請以 environment_connection 必要動作觸發啟動程序,並另外檢查供應商服務的運作狀態。
如果在回合中途斷線,即使回合順利完成,工具執行仍可能失敗。請檢查工具結果和智慧體的最終回應。斷線不會自動透過 webhook 要求重新連線,也不會重新執行已遭終止的指令。後續輸入可能會要求重新連線。
收到輸入時,API 最多會等待五分鐘讓執行器連線。請依此等待時間設定用戶端和 Proxy 的逾時值。如果等候逾時,這次提交就會失敗。初次提交的輸入可能以非同步方式失敗,使工作階段停留在 failed 狀態。
處理程序當機後,API 不保證能復原尚待處理的輸入。重試前,請先確認請求或工作階段的結果。如果原請求仍在等候,請勿重新提交。逾時後才建立連線,不會重新處理已逾時的輸入。
重複使用環境 ID 並不會在替換後的運算資源上還原檔案。請使用供應商的儲存空間或快照保留檔案。
清理資源
停止接收新的輸入。請協調清理作業與已在進行的啟動作業,以免清理後仍有運算資源在執行。
請刪除工作階段,並另外停止供應商的運算資源。刪除工作階段不會停止其環境,也不會發出刪除事件的 webhook 通知。