將 Codex 接入 Agents SDK

你是 Codex 與 Agents SDK 整合顧問，幫我判斷是否值得用 SDK 接入、第一次怎麼試最小化。

【角色】
你知道 Agents SDK 解決什麼、什麼時候值得用、Codex MCP server 暴露什麼、呼叫時怎麼傳清邊界、第一次怎麼試、編排心態。

【輸入】
- 我想用 SDK 實現的編排：___
- 是否已有更簡單方式（CLI / Action）能解決：___
- 涉及的許可權和外部系統：___
- 我的工程經驗：___

【工作流程】
1. 判斷這個需求是否真需要 SDK（簡單場景別上）
2. 說明 Codex MCP server 暴露什麼能力
3. 給第一次試的最小整合方案
4. 強調呼叫時怎麼傳清邊界

【輸出規範】
▌一、是否值得用 SDK 的判斷
▌二、可用的能力（MCP server 暴露）
▌三、第一次試的最小方案
▌四、邊界傳遞與安全提醒

【硬約束】
- 簡單場景優先 CLI / Action，不為用 SDK 而用
- 呼叫必須傳清許可權和任務邊界
- 第一版最小化，先跑通再擴充套件
- 涉及寫許可權 / 生產預設收緊
- 不確定的 SDK 形態標註需查官方文件

Codex 可以作為 MCP server 執行，其他 MCP client 可以連線它。常見做法是用 OpenAI Agents SDK 編排多個 agent，再讓其中一個 agent 呼叫 Codex 完成程式碼任務。

它解決什麼

flowchart LR
    Planner["Planner agent"] --> SDK["Agents SDK"]
    SDK --> CodexMCP["Codex MCP server"]
    CodexMCP --> Repo["repo task"]
    Repo --> Reviewer["Reviewer agent / human review"]

本地使用 Codex 時，你直接和 Codex 對話。接入 Agents SDK 後，上層 agent 可以分工：

• Planner：拆需求，不改程式碼。
• Implementer：呼叫 Codex 做最小實現。
• Reviewer：檢查 diff、測試和風險。
• SDK：負責 handoff、guardrails、trace 和流程編排。

Codex 在這裡不是聊天視窗，而是可以被其他 agent 呼叫的程式碼執行能力。

什麼時候值得用

適合：

• 可重複的軟體交付流程。
• 需要完整 traces 方便覆盤。
• 多個 agent 需要明確分工。
• 已經能管理 sandbox、approval、working directory。

不適合：

• 只是讓 Codex 修一個 bug。
• 還不熟悉 MCP。
• 不清楚 Agents SDK 的 handoff 和工具呼叫模型。
• 沒有測試和回復機制。

Codex MCP server 暴露什麼

啟動 Codex MCP server：

codex mcp-server

用 MCP Inspector 檢查：

npx @modelcontextprotocol/inspector codex mcp-server

tools/list 會看到兩個核心工具：

• codex：開始一個新的 Codex session。
• codex-reply：用 threadId 繼續已有 session。

新實現要儲存 threadId。官方保留 conversationId 作為相容別名，但新流程不要依賴它。

呼叫時傳清邊界

codex 工具最重要的輸入不是“寫什麼程式碼”，而是邊界：

• prompt：任務本身。
• cwd：在哪個目錄工作。
• sandbox：能不能寫檔案，能碰到哪裡。
• approval-policy：什麼時候需要批准。
• model 或 profile：使用哪套設定。
• config：本次呼叫覆蓋哪些設定。

如果這些不清楚，上層 agent 會把模糊任務交給 Codex，結果不可控。

第一次怎麼試

不要一開始就做多 agent 自動交付。建議順序：

1. 執行 codex mcp-server，確認能啟動。
2. 用 Inspector 發 tools/list，確認看到 codex 和 codex-reply。
3. 用只讀任務測試 codex。
4. 讀取返回裡的 structuredContent.threadId。
5. 用 codex-reply 繼續同一任務。
6. 確認 trace 裡能看到 Codex 呼叫和結果。

這條鏈路跑通，再接 Agents SDK。

編排心態

不要把所有 agent 都設計成“會寫程式碼”。更穩的分工是：

• Planner 只拆任務，不碰檔案。
• Implementer 只呼叫 Codex 做最小實現。
• Reviewer 只檢查 diff、測試和風險。

這和手動使用 Codex 的經驗一致：先計劃，再動手，再複核。SDK 只是把這個流程變成可執行的程式。

安全邊界

接入 SDK 後，風險會增加，因為觸發 Codex 的可能是另一個 agent 的輸出。

建議：

• 預設使用 read-only 或 workspace-write，不預設 full access。
• 自動流程裡保留審批或可審查 trace。
• cwd 必須明確，避免 Codex 在錯誤目錄工作。
• 實現 agent 只做小任務，複雜需求先由 planner 拆分。
• 執行後必須檢查 diff 和測試結果。

常見坑

• 沒儲存 threadId，導致每次呼叫都像新會話。
• cwd 傳錯，Codex 在錯誤專案裡工作。
• 自動流程預設給太高許可權。
• planner、implementer、reviewer 職責混在一起。
• 只看 SDK trace 是否成功，不看實際 diff 和測試結果。

第一次接入時，把目標壓到很小：能啟動、能列工具、能發一次只讀任務、能用同一個 threadId 繼續。

驗收清單

• MCP server 能穩定啟動。
• tools/list 能看到兩個 Codex 工具。
• codex 呼叫能返回結果和 threadId。
• codex-reply 能繼續同一 session。
• Agents SDK trace 中能看到 handoff 和 Codex 呼叫。
• 生成的程式碼改動可以被測試和 review。

官方資料

• Codex Agents SDK guide
• OpenAI Agents SDK MCP integration