Managed Agent Runtime：Session、Harness 與執行環境怎樣託管？

以 OpenAI Agents API 為例，理解託管 Harness 怎樣組織長期 Session、上下文和子任務，區分執行環境與會話狀態，並分析 Agents SDK 與託管 API 的職責邊界。

2026年10月14日

23 分鐘

4568 字

Agent OpenAI Runtime Infrastructure 學習筆記

上一篇討論了應用怎樣通過 SDK 組合 Harness、Sandbox 與 Workspace。組件可以複用以後，應用仍要運行 Harness，處理會話接續、執行恢復和環境生命週期。另一種組織方式，是把 Harness 本身也交給平台運行。

OpenAI 在《Introducing the Agents API》中介紹的正是這層託管能力。本文先分清應用、託管 Harness 與執行環境的職責，再看 Session 怎樣持續工作、平台怎樣處理上下文和子任務，最後比較環境選擇、產物保存，以及 SDK 與 API 的區別。

繼續使用假設的 CSV 修復任務：Agent 需要讀取源碼和樣本、修改解析器、運行測試，並交出補丁。用户還可能在完成一輪後補充“再檢查一下舊格式的兼容性”。這要求系統不僅能完成一次執行，還要保存足夠的工作背景，讓後續任務接得上。

一、託管 API 怎樣組織 Agent 運行h2

1. Managed Harness：由平台運行模型與工具循環h3

使用模型 API 時，應用拿到一次輸出後，通常還需要判斷是否執行工具、怎樣回傳結果，以及什麼時候繼續調用模型。SDK 可以提供這些運行機制，但 Harness 仍在開發者自己的應用中運行。

Agents API 將這層運行職責放到 OpenAI：平台運行 Codex Harness，組織模型調用、工具使用與會話管理。應用通過 API 提交工作、接收進展，並提供任務所需的工具和環境。來源：Agents API Overview

對 CSV 任務來説，應用不必親自推動每一次“讀文件 → 看結果 → 改代碼 → 再測試”的循環，但仍需告訴 Agent 修什麼、允許改哪裏，以及什麼結果才算完成。

因此，這裏的託管不是把業務需求變成平台的責任，而是把通用執行機制交給平台。運行一套 Harness，與定義一個值得執行的任務，是兩種不同的工作。

2. Agent、Environment 與 Session：配置和運行實例h3

看創建請求時，可以先區分三個對象：

對象	描述什麼	CSV 修復中的例子
Agent	模型、指令和可用工具	修復目標、代碼檢查能力與協作配置
Environment	命令和文件操作的執行位置	放着源碼、樣本和測試依賴的工作區
Session	持續接收輸入、保留工作的運行實例	從定位錯誤到補充兼容性檢查的同一項工作

Agent 描述能力與規則，Environment 承載實際操作，Session 將配置、交互和工作過程組織起來。只有 Agent 配置，不等於已有源碼；準備了一個容器，也不等於已經開始任務。

環境還是可選的。任務如果只通過遠程工具查詢資料，就可以不配獨立 Sandbox；CSV 修復需要讀寫文件和啓動測試，才需要相應環境。託管 Agent 不意味着每次都必須先創建一台工作機。 來源：Architecture

二、Session 怎樣接續長期任務h2

3. Turn 與 Events：提交工作、觀察進展和繼續輸入h3

Session 可以包含多輪工作。一次 Turn 內部又可以有多次模型推理、工具調用和結果回傳，不能把它理解成一次 LLM 請求。

在這個例子中，應用創建 Session 並提交 CSV 修復任務；Agent 檢查實現、修改代碼、運行測試，最後返回補丁説明。這是一輪工作。用户再補充舊格式樣本時，應用向同一個 Session 發送消息，沿用已有背景繼續檢查，而不是重新拼接整段歷史。

輸入發生的時機也有區別：Session 空閒時，新消息啓動下一輪；正在工作時，新消息可以引導當前輪的執行。應用需要把產品中的會話與對應的 Session ID 關聯起來，不能每次收到一句補充就重新創建實例。

運行過程是異步的，應用可以通過流式事件展示進展，或通過 Webhook 接收狀態變化。這裏要分清進展事件與最終結果：看到測試開始，不等於測試通過；Session 回到空閒，也不等於這一輪成功。需要檢查 Turn 的完成、失敗或取消狀態，再結合實際輸出判斷。來源：Run and continue sessions

4. Context 與 Tool Use：平台管理運行中的信息h3

長期任務積累的不只是用户消息，還有源碼片段、測試輸出、工具定義與分析記錄。平台接管 Harness 後，也就接管了這些信息怎樣進入下一輪推理的部分機制。

原文介紹了三種相互配合的能力：接近上下文限制時自動壓縮早期內容；按需發現相關工具定義；通過代碼組織工具調用、過濾和彙總結果。這些機制分別處理歷史增長、工具發現和中間數據量，不是同一種“壓縮”。

對 CSV 修復，可以這樣理解它們的作用：早期已解決的排查記錄整理為繼續工作需要的背景；需要查詢某項外部資料時再取得相關工具定義；大批樣本的統計與篩選在代碼中完成，只讓有用結果回到模型。

這裏整理的是運行分工，而不是聲稱平台會自動挑出所有重要信息。應用仍要提供清楚的任務約束和可核對的資料。測試標準只存在於某個沒有接入的內部文檔裏，Harness 再完善也無法憑空知道。

5. Subagents：由 Harness 協調子任務h3

任務複雜以後，主 Agent 可以將獨立工作交給子 Agent。例如，一個檢查解析器改動是否覆蓋錯誤輸入，另一個檢查舊格式樣本的兼容性，主 Agent 再結合兩份結果決定是否補充修改。

Agents API 的多 Agent 配置將創建、消息傳遞、等待和中斷等協調工具交給 Harness 提供。每個子 Agent 有自己的上下文，主 Agent 負責組織和彙總。開發者不需要重新實現一套同樣的基礎調度機制。來源：Multi-agent

但平台能夠協調，不意味着任務天然適合並行。必須先修改解析器才能驗證新行為的步驟，仍有依賴；多個 Agent 同時編輯同一個文件，也仍需要約定修改範圍和集成順序。

在這個場景裏，兩個只讀檢查任務更容易獨立進行，再由主 Agent 統一落實改動。獨立 Context 解決信息組織問題，不自動解決共享工作區的寫入衝突。 託管改變的是協調機制由誰運行，不是取消任務分解本身的工程判斷。

三、執行環境與文件怎樣管理h2

6. Hosted 與 Self-hosted：選擇計算環境h3

Harness 託管在 OpenAI，並不要求文件和命令執行也必須使用 OpenAI 的環境。原文同時提供了 OpenAI-hosted、自有基礎設施和合作 Sandbox Provider 的接入方向。

下面的圖將這條邊界畫出來：應用與平台交換任務和事件，託管 Harness 再連接所選執行環境。三種環境是選擇關係，不代表每個 Session 同時創建三個 Sandbox。

圖 1 · Harness 託管與 Compute 選擇：應用提交任務，平台組織執行，環境承載文件和命令

環境是可選項；僅使用遠程工具的任務也可以不配 Sandbox。窄屏可在圖內左右滑動查看。

選擇 OpenAI-hosted 時，平台準備並連接工作區，應用提供文件、依賴和所需配置。選擇自有環境時，應用負責準備計算資源，並在環境中運行 Executor，讓託管 Harness 能發送命令、讀取文件和取得結果。

官方自有環境文檔使用 codex exec-server 承擔這層執行。它主動連接平台，接收請求並返回結果；應用仍需處理環境啓動、連接和關閉，而不是把容器創建以後就放着不管。來源：Self-hosted sandboxes

CSV 修復如果只依賴普通源碼和公開依賴，可以考慮託管環境；如果依賴私有網絡或特殊軟件，就需要圍繞這些條件選擇環境。判斷標準是任務所需資源與約束，不是簡單認定自管或託管哪種一定更高級。

7. Session State 與 Artifacts：保存工作背景和交付文件h3

繼續同一個 Session，能夠沿用已有工作背景；但會話記錄、活着的執行環境和已經發布的文件，是不同的資源。

在 OpenAI-hosted 環境中，官方文檔約定將輸出放到 /workspace/outputs，輪次完成時發佈為不可變 Artifact。已經發布的副本可以在環境到期後下載。自有環境的文件則由應用通過自己的基礎設施取回，不會因為用了相同目錄名，就自動進入平台的 Artifacts API。來源：Files and artifacts

因此，CSV 任務的結果應當具體到補丁、測試報告及對應輪次。後續檢查產生新版報告時，需要分清版本，不能把舊報告當成新工作區的驗證結果。需要長期保存的文件，還要進入應用自己的交付與存儲流程。

長期運行也不代表環境永不到期，或任何失敗都能原地恢復。連接中斷時，可以先查詢已有 Session、Turn 和保存的工作；如果 Session 已經失敗，則需處理原因，並用仍需要的輸入創建新實例。保留工作狀態提供了恢復依據，不是對每一種故障作出無損續跑的保證。 來源：Errors and recovery

四、託管之後開發者仍負責什麼h2

8. Application Integration：工具執行、權限與結果驗收h3

平台管理 Agent Loop，並不意味着所有工具都由平台實現。遠程 MCP 可以由 Harness 連接；應用自定義的 Function Tool 則仍需要應用接收調用、執行函數並返回結果。處理器不可用時，工作可能停在等待工具結果的位置。

對 CSV 任務，假設補丁生成後還要提交內部審閲，應用就應提供相應接口，並驗證用户身份、目標倉庫與提交範圍。Agent 的一句“請提交”不能代替業務授權；平台能運行循環，也不能替應用決定這份補丁是否可以合入。

失敗處理同樣需要應用參與。收到連接錯誤後，應先查詢工作是否已經完成、文件或外部操作是否已經發生，再決定繼續或重試。模型答覆、工具結果、Turn 狀態與交付文件需要一起核對，不能用重新發送整個任務代替恢復判斷。

自有環境也不能被直接理解為數據完全留在本地。工具結果仍可能進入托管會話。寫作時的官方 Overview 明確説明，選擇 Self-hosted Sandbox 不會讓 Agents API 獲得 Zero Data Retention 資格。計算資源在哪裏，與數據經過哪裏、保存多久，是兩組需要分別檢查的問題。

9. Agents SDK 與 Agents API：運行控制和運維職責h3

這兩種方式的主要區別，不在於是否都能調用工具，也不在於是否使用一個名為 SDK 的客户端包。API 本身也可以通過語言 SDK 調用；要比較的是 Harness 由誰運行與維護。

比較項	Agents SDK 的應用運行方式	Agents API 的託管運行方式
Harness	在開發者應用中運行	OpenAI 運行和維護
會話與接續	應用組織所需存儲和恢復流程	通過託管 Session 繼續工作
上下文與編排	應用組合 SDK 能力並控制執行	使用平台提供的運行能力
執行環境	應用接入所需 Provider	可選託管、自有或合作 Provider
自有環境生命週期	應用負責	仍然由應用負責
業務工具、授權與驗收	應用負責	仍然由應用負責

SDK 更接近把運行機制作為可組合的庫交給應用；託管 API 則把這些機制作為服務接口提供。前者保留更多內部控制，後者減少通用 Runtime 的運行負擔，但也需要接受平台接口、支持範圍與升級方式。

原文説明 Agents API 基於開源 Codex Harness，並隨模型能力持續演進。源碼可見有助於理解核心執行邏輯，但不等於託管服務的每一項基礎設施都能在本地等價複製。模型或 Harness 版本變化後，也仍需用應用自己的任務集檢查行為。

我的理解是，Managed Runtime 抽象的並不是“讓模型回答一句話”，而是讓應用通過穩定入口消費一段持續執行的工作。應用仍要知道任務由誰授權、工具作用在哪裏、結果怎樣驗收；只是不用再親自維護每一步通用運行機制。

幾個關鍵問題，串起託管、執行與應用責任h2

為什麼使用了託管 Sandbox，不等於已經使用了託管 Harness？

Sandbox 提供文件和計算環境，Harness 組織模型與工具循環。上一篇的 SDK 可以在應用側運行 Harness，再連接託管 Sandbox；本篇的 Agents API 則由平台運行 Harness。需要分別看控制循環和計算環境的責任方。

Session、Turn 和一次模型推理有什麼關係？

Session 承載持續工作，一次 Turn 是其中一輪執行，一輪內部可以包含多次推理和工具調用。修復完成後追加兼容性檢查，可以在同一 Session 開啓新 Turn，不需要重建全部背景。

Context 自動壓縮，是否意味着長期任務不需要外部文件？

不是。壓縮處理模型繼續推理需要的背景，源碼、補丁和報告承載實際工作與交付。把“已修復解析錯誤”保留在上下文裏，不能代替保存那份真實補丁。

平台提供多 Agent 協調，為什麼仍要限制並行修改？

創建、等待和消息傳遞解決執行協調，獨立上下文解決信息隔離；共享文件的衝突需要另外處理。兩個 Agent 可以分別檢查不同樣本，卻不應未經約定同時覆蓋同一份解析器。

工具調用已經交給 Harness，應用還需要接收工具請求嗎？

取決於工具的執行方式。Harness 可以連接遠程 MCP，Sandbox 的 Executor 可以執行環境內操作；應用自定義函數仍需要對應處理器。託管循環不等於平台自動擁有業務系統的實現和授權。

流式連接斷開，是否應該立即重發任務？

不應該直接重發。斷流不證明任務失敗，先查詢 Session、Turn 和保存結果，確認是否仍在工作、已經完成或需要處理。如果外部操作已經發生，還要避免重複執行。

使用自有計算環境，是否就能保證數據不離開自己的系統？

不能。執行位置與數據流是兩件事，工具輸出仍可能交給託管 Harness 和模型。要檢查哪些內容會回傳、平台的存儲與保留約定，以及業務是否允許這種處理方式。

SDK 與託管 API 的分界，是不是“靈活”和“方便”？

這兩個詞太籠統。更具體的分界是 Harness 的運行、狀態管理和升級由誰承擔，以及應用需要控制哪一層。託管能減少通用基礎設施工作，但不會自動承擔自有環境、領域權限和業務正確性。