以 OpenAI Agents SDK 為例，理解 Agent 定義、Sandbox Client 和 Manifest 怎樣連接執行環境，以及目錄權限、產物保存、Snapshot 與運行狀態怎樣支持持續工作。
上一篇解釋了為什麼任務記錄、Harness 和執行環境需要獨立演進。這一篇把視角放到開發者接口：應用拿到 SDK 後，怎樣為 Agent 準備工作區，把工具請求送進執行環境，並在暫停或環境更換後接着工作？
OpenAI 的《The next evolution of the Agents SDK》將 model-native harness 與 native sandbox execution 放在一起介紹。本文沿着一次運行整理：先連接 Agent 與計算環境，再聲明工作區和權限，隨後保存產物與恢復狀態，最後分析跨環境遷移時哪些東西可以複用、哪些仍需核對。
繼續使用假設的 CSV 修復任務：應用提供源碼和輸入樣本，Agent 定位解析錯誤、修改代碼、運行測試，最後交出補丁與説明。樣本需要保持原樣，代碼需要可修改，輸出需要被應用取走。這些要求既是任務説明，也是工作環境必須落實的條件。
一、SDK 怎樣連接 Agent 與執行環境h2
1. Harness：模型交互與執行控制h3
SDK 提供的不只是一次模型請求的包裝。Harness 負責驅動 Agent Loop，處理模型返回的工具請求、結果回傳、審批和運行狀態；應用則在這個框架上定義任務目標、領域工具與業務約束。
這裏的 model-native 可以理解為：Harness 的工具和執行方式圍繞模型擅長使用的能力組織，例如文件檢查、Shell、補丁編輯與分層加載資料。它不是讓模型直接取得操作系統控制權，也不意味着所有任務都應該套用同一組工具。
對於 CSV 任務，模型可以提出“先讀解析器，再運行這個測試”。Harness 將請求送到相應工具，把真實輸出帶回下一輪；缺少授權時則按配置暫停或處理。模型決定下一步，運行程序組織這一步怎樣發生。
Sandbox 參與以後，這個關係沒有改變。新增的是文件和命令的實際執行位置，而不是重新定義一種脱離普通 Agent 機制的智能體。
2. Sandbox Client 與 Session：接入方式和運行實例h3
開發者需要區分“怎樣連接環境”和“這一次使用哪個環境”。Sandbox Client 封裝 Provider 的接入方式；Sandbox Session 則是已經準備出來、能夠執行命令和保存當前文件的實例。
可以按下面幾個問題看 SDK 接口，而不是把所有對象都叫作 Agent：
| 接口對象 | 回答的問題 | CSV 任務中的對應內容 |
|---|---|---|
SandboxAgent | 要做什麼，默認帶哪些能力？ | 修復解析器的指令、工具與默認工作區 |
Manifest | 新工作區從什麼內容開始？ | 源碼、樣本、任務説明和輸出目錄 |
| Sandbox Client | 通過什麼實現準備和操作環境？ | 本地、容器或託管環境的適配入口 |
| Sandbox Session | 當前命令和文件變化發生在哪裏？ | 這一次修復任務使用的工作區實例 |
| Sandbox Run Config | 這一輪創建、複用還是恢復環境？ | 指定 Client，或傳入已有 Session |
這些名稱沿用官方 Sandbox Agents 文檔。其中 Session 指 Sandbox 的執行會話，不能直接等同於上一篇的持久化事件日誌，也不能與 SDK 保存消息歷史的會話混為一談。
原文支持把 Harness 與 Compute 放在同一機器，也支持分開。分開以後，應用側可以保留模型認證、審批和審計等職責，Sandbox 只接收完成當前工作需要的資源與執行請求。
OpenAI 的代碼遷移 Cookbook就採用了這種組織：宿主進程運行 Harness，任務代碼在可替換的 Sandbox 中處理，再把補丁和報告交回宿主。這裏值得借鑑的是職責分配，不是要求所有應用複製它的部署方案。
二、Workspace 怎樣聲明和使用h2
3. Manifest：新工作區的初始契約h3
Manifest 説明一個新環境準備好時應該有什麼：哪些文件來自本地，哪個倉庫需要放進來，外部存儲出現在哪個路徑，以及輸出應該寫到哪裏。
對 CSV 任務，可以先設計下面這個佈局。它是本文的工作區示意，不是可直接提交給 SDK 的配置文件：
/workspace/ repo/ 源码、测试与任务说明 task.md src/ tests/ samples/ 原始 CSV 样本 output/ 补丁、测试报告与修复说明工作區路徑讓任務説明有了明確對象：從 samples/ 取證據，在 repo/ 修改實現，把可交付結果寫到 output/。應用不必把整個倉庫和全部樣本都塞進 Prompt，模型也能通過工具取得需要的文件。
這裏有一個容易混淆的生命週期：Manifest 描述新工作區的起點，不是每輪運行都強制同步的最終狀態。 任務已經改過文件時，繼續使用同一個 Sandbox，應該接着看當前文件；從快照創建環境時，也要保留所選快照代表的工作狀態，而不是默默回到最初源碼。
因此，應用在開始一輪工作之前，需要先決定“複用、恢復還是新建”。只有確定是新建，初始 Manifest 才成為這次準備工作區的重要輸入。不能把重新傳一份 Manifest 當作通用的更新或恢復操作。
4. Capabilities：把工作區連接到模型可用的工具h3
文件已經存在，不代表模型已經獲得相應的操作入口。Capabilities 用來把 Sandbox 相關工具與行為接到 Agent 上。
對於 CSV 修復，Shell 可以啓動測試和搜索程序，文件編輯能力可以生成補丁；只有任務需要專門操作知識時，再接入 Skills。Memory 與 Compaction 則分別服務於可複用經驗和上下文維護，不能用它們代替源碼與產物保存。
這個組合關係比“工具越多越好”更具體：模型要運行測試，就需要可用的命令入口和正確的依賴環境；模型要改代碼，就需要編輯能力和實際寫權限。只有一個名字叫作 Shell 的工具，卻沒有測試運行時，任務仍然做不下去。
指令也要與能力一致。比如要求保留原始樣本、補充邊界測試並給出修改説明，工具和目錄就必須允許完成這些動作。反過來，任務只要求閲讀資料時，沒有必要為了統一模板就開放修改和命令執行能力。
5. Permissions 與 Mounts：目錄訪問和外部數據範圍h3
目錄佈局説明“東西在哪裏”，權限説明“當前執行身份能夠怎樣訪問”。對這個任務，一個合理的目標是樣本只讀、源碼可修改、輸出目錄可寫。
這不能只靠 task.md 裏一句“不要修改樣本”。應當核對 Provider 支持的賬號、文件權限與掛載設置，並檢查工具是否確實以預期身份運行。SDK 可以表達工作區配置，但具體隔離能力還取決於執行實現。
| 工作區位置 | 本文場景希望允許的操作 | 原因 |
|---|---|---|
samples/ | 讀取，不覆蓋原件 | 保留用於復現的輸入證據 |
repo/ | 讀取、修改和運行測試 | 讓 Agent 完成實際修復 |
output/ | 寫入並由應用取回 | 保存可以審閲的結果 |
這張表是權限設計目標，不代表創建這些目錄以後就自動具備表中的限制。驗證時要看允許動作能否完成，也要看越界動作是否真的失敗。
外部存儲掛載還增加了一層範圍問題。原文介紹了通過 Manifest 接入 S3、GCS、Azure Blob 和 R2 等存儲，但“能接入”不是“應該把整個存儲賬户暴露給任務”。CSV 修復只需要對應樣本，就應圍繞這組數據安排路徑和授權。
憑證也應作為運行時資源管理，而不是寫進任務文件、提交的 Manifest 或模型指令。把 Harness 放在 Sandbox 外，有助於保留控制面憑證；確實需要交給執行層的掛載或工具授權，則仍需限制範圍。
三、一次運行怎樣保存結果並繼續h2
6. Artifacts：模型答覆與可交付文件h3
模型回答“已經修好了”與應用拿到一份可檢查的補丁，是兩種不同的結果。前者是答覆，後者是產物；文件還留在即將清理的環境裏，也不等於已經完成交付。
在 CSV 任務結束時，應用至少要知道補丁和報告保存在哪裏、對應哪個代碼版本，以及測試返回了什麼。然後把需要保留的文件複製到可靠存儲或交給審閲流程，再處理環境的關閉與清理。
前面的代碼遷移 Cookbook 將補丁、報告和審計記錄交回宿主後再清理任務環境，體現的正是這條交付邊界。應用負責接收和檢查產物，不能只把 Agent 的最後一段話當作文件已經保存的證據。
下面的關係圖把初始準備、執行和保存連在一起。真實部署中，Sandbox 可以在宿主本機，也可以由其他 Provider 承載。
7. Snapshot 與 Run State：恢復文件和恢復執行進度h3
原文介紹了 snapshotting 與 rehydration：保存狀態後，可以在新環境中重新準備工作區，避免容器失效就讓任務從頭開始。要把這個能力用對，還需要明確保存的究竟是哪種狀態。
可以用三個問題區分它們：
- Harness 運行狀態： Agent 正停在哪裏，有哪些模型交互、工具狀態或待處理審批？
- Sandbox 會話狀態： 應用怎樣重新連接或恢復對應的執行會話？
- Workspace Snapshot： 新工作區從哪一份已經保存的文件內容開始？
官方文檔分別使用 RunState、序列化 Sandbox Session State 和 snapshot 描述這些恢復入口，而不是把三者當成可互換的備份。來源：Resume or seed future work
在 CSV 任務中，假設 Agent 修改瞭解析器，保存快照後暫停等待審閲。恢復工作區可以取回那一版代碼，但要繼續之前的執行，還需要對應的會話與運行背景。如果只把文件快照交給一個新任務，它可以在這些文件上工作，卻不等於接續了原來那個暫停點。
Checkpoint 之後尚未保存的變化，也不能被當作已經恢復。恢復完成後，應用和 Agent 應先確認源碼版本、必要依賴與已有測試產物，再繼續操作；不能拿一份更早的測試報告證明後來恢復出的工作區正確。
外部掛載還有不同語義：工作區快照並不自動複製所有遠程存儲內容。遠程數據可能需要重新掛載，並核對訪問授權和數據版本。由此可見，保存會話、保存文件和保存外部資源，都需要對應的契約，而不是一個統一的“保存全部”。
四、環境更換後哪些部分可以複用h2
8. Provider Portability：應用契約與執行差異h3
SDK 將 Provider 接入與 Agent 定義分開，讓開發者可以保留任務指令、工作區佈局和工具能力，改變承載它們的計算環境。
例如，CSV 修復可以先在適合本地驗證的環境中組織流程，再接入獨立容器或託管 Provider。原文列出了多種集成，也支持自行接入 Sandbox；這裏重要的不是背 Provider 名單，而是應用不必把“修復解析器”的業務邏輯寫死在某個容器服務裏。
但接口可移植，不等於運行條件完全一致。切換前仍要核對運行時和依賴、賬號權限、網絡、掛載方式、存活時間，以及快照和恢復能力。本地工具能夠啓動，不證明新的環境已經具備同樣條件。
適配層隱藏的是接入細節，不應該隱藏影響任務正確性的差異。如果某個環境沒有所需測試運行時，就要準備依賴；如果輸入來自外部掛載，就要核對範圍；如果環境會到期，就要安排保存和取回產物。
這也明確了 SDK 的職責邊界：應用仍然運行 Harness，並決定資源、授權、交付和恢復策略。 使用託管 Sandbox，只是將計算環境交給 Provider，不代表整個 Agent Runtime 的運維都已經交出去了。
幾個關鍵問題，串起工作區、執行與恢復h2
Manifest 與 Prompt 都能告訴 Agent 去哪裏找文件，為什麼還需要兩者？
Prompt 指導模型怎樣工作，Manifest 準備新工作區實際有什麼。寫一句“讀取樣本”不能讓文件自動出現；準備一個樣本目錄，也不能替代對任務目標和完成條件的説明。
每輪都傳同一個 Manifest，能保證工作區始終一致嗎？
不能這樣理解。Manifest 主要描述新環境的起點，已有 Session、恢復狀態和快照可能決定當前工作區。繼續任務時，應先明確環境來源，再檢查實際文件，不能把初始聲明當作當前狀態。
Sandbox Client、Sandbox Session 和會話歷史有什麼區別？
Client 是 Provider 接入實現，Sandbox Session 是當前執行實例，會話歷史保存模型交互。知道怎樣連接一個 Provider，不代表已經擁有一個工作區；保留消息歷史，也不代表磁盤文件仍在。
有了文件編輯工具，是否就擁有所有文件的寫權限？
沒有。工具暴露操作入口，權限限制入口實際能夠作用的資源。樣本只讀、源碼可寫，應該由執行身份和底層權限落實，而不是依賴模型記住一條指令。
Snapshot、Memory 和 Compaction 都能幫助繼續任務，能互相替代嗎？
不能。Snapshot 保存可用於恢復工作區的內容，Memory 組織可複用經驗，Compaction 處理當前上下文規模。保存了一條“CSV 引號需要特殊處理”的經驗，不能恢復尚未保存的解析器補丁。
工作區已經恢復，為什麼還需要運行狀態？
文件回答“當前有什麼”，運行狀態回答“執行停在哪裏”。暫停審批、待處理工具調用和活躍 Agent 位置，不能只從源碼推斷。恢復文件可以成為新任務的起點，但不自動還原原任務的控制過程。
更換 Provider 只需要改一個 Client 嗎？
接入接口可以保持簡潔，但實際遷移仍需驗證能力與約束是否兼容。目錄路徑不變，不代表依賴、權限、網絡和恢復語義都相同。可移植性減少業務代碼與 Provider 的耦合，不是取消環境驗證。