我們用 Codex 改變了維護 OpenAI Agents SDK 程式碼庫的方式。透過程式碼庫內的技能、AGENTS.md 和 GitHub Actions,我們將驗證、發行準備、範例整合測試及 PR 審查等例行工程工作,整理成可重複執行的工作流程。即使設定相當簡單,也提高了這些活躍程式碼庫的開發吞吐量。2025 年 12 月 1 日至 2026 年 2 月 28 日,兩個程式碼庫共合併了 457 個 PR,高於前三個月(2025 年 9 月 1 日至 11 月 30 日)的 316 個。Python 從 182 個增至 226 個,TypeScript 從 134 個增至 231 個。
這套 SDK 提供 Python 和 TypeScript 版本,包含建構智慧體應用程式所需的核心元件。開發者也能用它在 Realtime API 上建構語音智慧體,以簡潔的方式整合多個智慧體、工具與人工介入控制機制。這套 SDK 的使用規模相當大。截至 2026 年 3 月 6 日,按兩個套件各自近期的 30 天統計,Python 套件在 PyPI 上約有 1,470 萬次下載,TypeScript 套件在 npm 上約有 150 萬次下載。
設定很簡單:
- 在
AGENTS.md中記錄程式碼庫規範 - 在
.agents/skills/中存放程式碼庫專用的技能 - 視需要在技能中加入指令碼與參考資料
- 需要在 CI 中執行相同工作流程時,使用 Codex GitHub Action
這樣一來,Codex 就有穩定的上下文可用來了解程式碼庫的運作方式,能更快、更準確地完成例行工程工作。
如果你維護公開的開源專案,請參閱 Codex for OSS。符合資格的維護者可申請包含 Codex 的 ChatGPT Pro、API 點數,以及有條件的 Codex Security 存取權。
將工作流程保存在程式碼庫中
我們用技能記錄各個程式碼庫專屬的工作流程。每項技能都把一小套操作知識封裝在一起,包括一份 SKILL.md 資訊清單,以及可選的 scripts/、references/ 和 assets/。Codex 自訂文件說明了這種做法為何有效:技能可以為重複執行的工作流程提供更詳盡的指示、指令碼與參考資料,又不會在一開始就占用智慧體過多的上下文空間。
這正是技能採用的漸進式揭露方式:
- 智慧體先看到
name和description等中繼資料 - 只有選用技能時,才載入
SKILL.md - 只有需要時,才讀取參考資料或執行指令碼
兩個 SDK 程式碼庫都將工作流程與程式碼放在一起:
Python 程式碼庫提供了一套較簡單的基本配置:
code-change-verification在程式碼或建置行為有變更時,依規定執行格式化、lint 檢查、型別檢查和測試。docs-sync對照程式碼檢查文件,找出遺漏、錯誤或過時的內容。examples-auto-run以自動模式執行範例、記錄日誌,並提供重新執行範例的輔助工具。final-release-review比較上一個發行版本的標籤與目前的候選版本,確認是否可以發行。implementation-strategy在動手修改執行階段或 API 之前,先確定需要維持相容的範圍與實作方式。openai-knowledge透過官方 Docs MCP 工作流程取得最新的 OpenAI API 與平台文件。pr-draft-summary在交接時產生建議的分支名稱、PR 標題與說明草稿。test-coverage-improver執行測試涵蓋率分析,找出最大的缺口,並建議最值得新增的測試。
JavaScript 程式碼庫採用類似的做法,另外針對其 npm 單一程式碼庫與發行流程加入幾項專用技能:
changeset-validation檢查變更集和版本號遞增層級是否確實符合套件的實際差異。integration-tests將套件發佈到本機 Verdaccio 套件登錄庫,並驗證能否在各個支援的執行階段中安裝與執行。pnpm-upgrade一併更新 pnpm 工具鏈和 CI 中鎖定的版本。
比起清單上有哪些技能,更重要的是它們的設計方式。每項技能都有明確而有限的職責、清楚的觸發條件,以及具體的輸出。
有些特別實用的技能不必設成強制關卡。docs-sync 和 test-coverage-improver 都會先提出報告:檢查目前的變更差異或測試涵蓋率報告,排出處理的優先順序,再於修改前要求核准。在 Python 程式碼庫中,docs-sync 也會以原始碼中的文件字串與註解為準,據此維護自動產生的參考文件,避免手動修補產生的內容。JavaScript 專用的 pnpm-upgrade 技能也是職責明確的維護流程:它會一併更新本機 pnpm 版本、packageManager 與工作流程中鎖定的版本,無須大範圍搜尋與取代。
規定何時必須執行工作流程
當程式碼庫明定在什麼情況下必須使用技能,技能就更能發揮作用。這正是 AGENTS.md 的用途。
根據 AGENTS.md 指南,這些檔案存放的是程式碼庫層級的指示,隨程式碼一同維護,在智慧體開始工作前就已適用。指南也建議保持檔案精簡。在 Agents SDK 程式碼庫中,我們用這個位置記錄 Codex 每次都應遵守的規則,並將最重要的幾條放在開頭。
實務上,兩個程式碼庫都用簡短的條件規則來指定何時必須使用哪些技能。修改執行階段或 API 之前,先呼叫 $implementation-strategy,確定需要維持相容的範圍與實作方式。如果變更影響 SDK 程式碼、測試、範例或建置行為,就呼叫 $code-change-verification。如果 JavaScript 套件的變更影響發行中繼資料,就呼叫 $changeset-validation。工作涉及 OpenAI API 或平台整合時,呼叫 $openai-knowledge。工作完成、可以交接時,呼叫 $pr-draft-summary。
這種結構也符合 agents.md 的建議:將專案概覽、建置與測試指令、程式碼風格、測試指引、安全考量及其他程式碼庫專屬規則集中在一處。Agents SDK 程式碼庫遵循這種結構,並將日常工作中最重要的觸發條件放在前面。精簡版如下:
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.
實際檔案會在這套基本配置上補充各程式碼庫的細節,例如 JavaScript 程式碼庫中的 $changeset-validation,以及兩份檔案中更詳細的執行階段、文件與發行指引。完整範例請參閱 openai-agents-python 的 AGENTS.md 和 openai-agents-js 的 AGENTS.md。
AGENTS.md 除了指定技能的觸發條件,還有其他用途。Python 程式碼庫也在這裡記錄了一條公開 API 相容性規則:維持匯出的建構函式參數與資料類別欄位在各位置上的原有意義,盡可能將新增的選用參數或欄位放在最後。如果無法避免調整順序,就新增相容性測試。這也是值得採用的做法:將攸關發行的相容性規則與技能觸發條件放在同一處。
驗證規則
以 $code-change-verification 為例。
兩個程式碼庫的規則都不是「每次都要執行一長串驗證」,而是「執行階段程式碼、測試、範例或建置/測試行為有變更時,就必須執行驗證,而且通過後才能將工作標示為完成」。
限定觸發條件,可以讓只修改文件的工作保持簡單。符合條件就強制執行,則能確保 SDK 程式碼變更都經過程式碼庫的標準驗證步驟。
實際的驗證步驟直接寫在技能裡。
在 Python 程式碼庫中,必須執行:
make format
make lint
make typecheck
make tests
在 JavaScript 程式碼庫中,技能要求嚴格依照以下順序執行:
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test
技能定義了程式碼庫所謂「已驗證」的標準,而 AGENTS.md 讓這項標準成為必須遵守的規則。
驗證變更集
JavaScript 程式碼庫對套件變更還有一道必要步驟:執行 $changeset-validation。這項技能以 Changesets 為基礎。
只要 packages/ 下的任何內容有變更,或 .changeset/ 有變更,模型除了執行測試,還必須建立或更新對應的變更集、驗證版本號遞增層級,並確認變更集確實符合實際差異。
這項技能不只檢查檔案是否存在,也要求 Codex 判讀 Git 差異。驗證規則存放在共用提示詞中,讓本機執行與 GitHub Actions 採用相同邏輯。技能也記錄了程式碼庫專屬的規範,例如:
- 如果分支已有變更集,就沿用現有變更集,無須另建一份
- 依 Conventional Commit 格式將摘要寫成一行,讓它也能用作提交標題
- 在 1.0 版之前,一般功能開發應避免遞增主版本號。若新增內容已明確標示為僅供預覽,且未改變既有行為,則視為修補版本變更
- 根據套件的實際變更,驗證應遞增哪一層版本號
因此,Codex 必須先驗證自己產生的發行中繼資料,才能宣告工作完成。
查閱最新文件
在這兩個程式碼庫中,只要工作涉及 OpenAI API 或平台整合,也都必須使用 $openai-knowledge。
這項技能簡單封裝了官方的 OpenAI Docs MCP。它會指示 Codex 使用 OpenAI 開發者文件 MCP 伺服器,查閱 Responses API、工具、串流、Realtime 與 MCP 等功能的最新文件,避免模型憑記憶回答。
如果本機 Codex 環境尚未設定 MCP 伺服器,技能會引導維護者參閱 Docs MCP 快速入門與官方 MCP 伺服器端點。
準備 PR 交接資料
完成實質工作後,兩個程式碼庫都會使用 $pr-draft-summary。
只有當任務大致完成或已可送審,而且變更涉及實質的程式碼、測試、範例、會影響行為的文件,或建置/測試設定時,才會觸發這項技能。接著,它會自動收集分支名稱、工作樹狀態、變更的檔案、差異統計與近期提交,並產生:
- 建議的分支名稱
- PR 標題
- PR 說明草稿
我們刻意固定了輸出格式。典型結果如下:
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.
當你已經信任模型能驗證並整理自己的工作成果,讓它在最後產生 PR 草稿就很自然。這能讓交接資料保持一致,也能減少程式碼寫完後重複撰寫說明的時間。
把技能說明寫得更明確
技能的 description 欄位位於 SKILL.md 的前置中繼資料中,也是決定如何選用技能的依據之一。
這牽涉到技能的結構,而不只是寫作風格。智慧體技能規格規定 name 和 description 是 SKILL.md 前置中繼資料的必要欄位。依其漸進式揭露方式,系統啟動時會為所有技能載入這些欄位。直到實際啟用某項技能,才會載入完整的 SKILL.md 內文,以及該技能的 scripts/、references/ 或 assets/。
關於 Codex 如何選用技能,Codex 技能文件與自訂文件說明了相同的行為:Codex 先透過各項技能的中繼資料找出可用技能,選定技能後才載入 SKILL.md,並只在需要時讀取參考資料或執行指令碼。OpenAI API Cookbook 的技能指南也清楚說明了託管 Shell 環境的運作方式:OpenAI 會先讀取各項技能的 name、description 與路徑,模型再根據這些資訊判斷何時讀取完整的 SKILL.md。其中的 SKILL.md 前置中繼資料一節說得更直接:name 和 description 對於發現與選用技能都很重要。
因此,在 Agents SDK 程式碼庫中,Codex 還沒讀取技能的其餘內容時,description 就已經是判斷該選用哪項技能的主要依據之一。
以 code-change-verification 為例。
過於籠統的寫法:
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.
更明確的寫法(實際使用的說明):
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.
較短的版本已經告訴 Codex 這項技能有什麼用途,卻沒有交代何時適用、哪些變更應觸發技能,以及在什麼情況下檢查是必要的。較具體的版本把這三點都說清楚了。
同樣的寫法也用在 pr-draft-summary 上。
過於籠統的寫法:
description: Create a PR title and draft description for a pull request.
更明確的寫法(實際使用的說明):
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.
同樣地,實際使用的說明是用來選擇技能的中繼資料。它告訴 Codex:
- 這項技能應在任務收尾時使用
- 有實質變更時才適用,無須在每輪對話中使用
- 輸出必須是可直接用於 PR 的完整區塊,只有一段文字摘要並不足夠
這些程式碼庫帶給我們一項實務經驗:值得花時間寫好 description。如果 Codex 經常選錯技能,先調整中繼資料,再考慮增加程式碼。
將固定操作寫成指令碼
接下來要決定的是,哪些工作該交給模型,哪些該寫進指令碼。
一種可靠的分工方式是:
- 由模型負責解讀、比較及撰寫報告
- 將步驟固定且重複執行的 shell 操作放進
scripts/
這也符合公開指引。Codex 自訂文件指出,技能能為可重複執行的工作流程提供更詳盡的指示、指令碼與參考資料,不必一開始就占用大量上下文空間。這很適合以模型為主的配置:讓 Codex 處理需要依上下文判斷的部分,只有在需要執行固定步驟時才使用指令碼。OpenAI API Cookbook 的技能指南也建議將技能指令碼設計成小型 CLI:可從指令列執行,對相同輸入產生一致的標準輸出,失敗時明確顯示用法或錯誤訊息,並視需要將結果寫入指定的檔案路徑。
在 Agents SDK 程式碼庫中,我們盡量將模型用在真正需要判斷力的地方,例如:
- 閱讀原始碼,推斷預期行為
- 將日誌與預期行為比對
- 判斷發行版本間的差異是否真的帶來相容性風險
- 撰寫說明,讓維護者知道如何採取行動
指令碼則負責配合這些工作的固定操作,例如:
- 依固定順序執行程式碼庫要求的驗證指令
- 啟動範例、分別收集各範例的日誌,並為執行失敗的範例產生重跑用檔案
- 在審查是否可以發行之前,取得上一個發行版本的標籤
- 提供
start、stop、status、logs、tail、collect和rerun等輔助指令,方便重複執行同一個工作流程
如果模型每次都得重新摸索同一套 shell 操作,通常就該把這套操作寫成指令碼。需要考量上下文、權衡取捨或解釋結果的部分,則應留給模型。
自動執行整合測試
在兩個程式碼庫中,自動化整合測試都是特別實用的工作流程。這裡有兩個相關層次:兩個程式碼庫都會自動驗證庫內的範例,而 JavaScript 程式碼庫還會另外驗證已發佈的套件,確認使用者依平常的方式安裝後,套件仍能正常運作。
採用這套配置之前,範例驗證仍有一部分得手動完成。範例可以直接執行,但最後往往得靠人逐一查看日誌,判斷輸出是否合理。只驗證一個範例時還能應付,面對持續成長的 SDK 程式碼庫就很難跟上。
第一層是 examples-auto-run,不過我們先有執行器,後來才有技能。為了自動驗證範例,我們必須先讓兩個程式碼庫都支援非互動式執行。這表示範例指令碼必須能以自動模式執行,即使是平常會提示使用者輸入或要求核准的範例也一樣。
這些前置工作包括:
- 自動回應常見的互動式提示
- 在執行器支援的情況下,自動核准 HITL、MCP、
apply_patch和 shell 操作 - 將仍不適合自動執行的範例列入自動略過清單,例如需要額外設定執行環境的即時互動範例或 Next.js 應用程式範例
- 為每次範例執行寫入結構化日誌
- 產生重跑用檔案,讓失敗的範例能單獨重試,無須全部重新執行
基礎功能就緒後,我們將它整理成技能,讓工作流程可以重複使用,也方便呼叫。在 Python 程式碼庫中,examples-auto-run 封裝了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 程式碼庫中,它會先執行封裝好的建置檢查,再以自動模式執行 pnpm examples:start-all,分別記錄各範例的日誌,並支援重新執行。
為了提高驗證品質,執行器負責執行範例,並將各範例的標準輸出與標準錯誤輸出保存在對應的日誌中。接著,技能會讓 Codex 逐一檢查日誌,並與原始碼比對:
- 閱讀範例的原始碼與註解
- 推斷預期的執行流程
- 開啟對應的日誌
- 將預期行為與實際的標準輸出及標準錯誤輸出比對
- 對每個成功執行的範例都完成上述步驟,而非只抽查一個
比起在指令碼中用固定的斷言判定結果是否正確,這種做法更準確,也更有彈性。代表執行成功的結束狀態碼很有用,但對於會呼叫實際 API、使用工具或產生結構化輸出的範例,光看狀態碼還不夠。我們先記錄實際輸出,再仔細對照原始碼,就能依每個範例原本要示範的行為進行驗證。
JavaScript 程式碼庫還有第二層驗證,由獨立的 integration-tests 技能負責。這個工作流程會將套件發佈到本機 Verdaccio 套件登錄庫,再測試能否在 Node.js、Bun、Deno、Cloudflare Workers 與 Vite React 應用程式等多種環境中安裝與執行。這能找出只在程式碼庫內執行原始碼範例時難以發現的問題:第一層檢查「範例能否在程式碼庫中執行」,第二層則確認「套件經過發佈、安裝並整合到執行環境後,行為是否仍然正確」。
這些工作流程說明了結合技能、指令碼與模型判斷力的好處。指令碼讓測試能以相同方式重複執行,留下驗證所需的證據,也能涵蓋手動檢查起來很繁瑣的安裝方式。Codex 再利用這些證據仔細比對,比起只靠指令碼判定通過或失敗,能檢查得更深入。
加入發行檢查
這種做法也適用於發行準備。
兩個程式碼庫的發行審查流程都會先找出上一個發行版本的標籤,與最新的 main 比對,再請 Codex 檢查差異中是否有以下問題:
- 公開 API 或使用者可觀察到的 SDK 行為出現回溯相容性問題
- 既有功能退化,包括預期行為的細微變化
- 需要說明的變更缺少遷移注意事項,或尚未更新發行說明
技能會根據檢查結果,綜合判斷是否可以發行。
具體例子可見 openai/openai-agents-python#2480。這次審查的整體結論是可以發行,同時也指出新版將停止支援 Python 3.9,以及發行說明必須補充哪些內容:
Release readiness review (excerpt)
Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.
Scope summary:
- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
`src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
`pyproject.toml`, `uv.lock`.
Python 3.9 support removed
- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
packaging metadata remains `>=3.10`.
技能也定義了如何決定是否放行。審查以「可安全發行」為起點,只有當差異中出現具體證據,顯示確實存在問題時,才會判定暫緩發行。每次暫緩發行,都必須列出解除阻礙所需的具體事項。這讓維護者更容易依結果行動:綠燈表示差異中未發現足以阻礙發行的問題,暫緩發行則表示確實有問題,而且下一步很明確。
這比籠統地要求「請審查這次發行」更有用。模型必須根據具體差異推理,並說明結果對發行有何影響。可以安全發行,就明確說明。如果不能,就指出確切證據,以及接下來必須完成的事項。
在 CI 中執行工作流程
一項技能在本機用起來有效之後,就能透過 Codex GitHub Action 在 CI 中自動執行相同工作流程。最好等本機工作流程穩定後再這麼做,因為手動使用的過程正好能幫助你找出指示中的問題、改進指令碼,並發現實際會遇到的邊界情況。
對公開程式碼庫而言,觸發條件的設計和技能本身同樣重要。GitHub Action 安全檢查清單建議限制能啟動工作流程的人員,優先採用受信任的事件或明確核准機制,清理來自 PR、提交、議題或留言的提示詞輸入。為保護 OPENAI_API_KEY,請使用 drop-sudo 或以無特權使用者身分執行,並將執行 Codex 排在作業的最後一步。
如果工作流程具有寫入權限,又接受不受信任的公開輸入,風險通常來自技能周邊的觸發條件設計、輸入處理方式,以及執行時的權限。
在 PR 審查中使用 Codex
技能是我們提高這些程式碼庫開發效率的一種方式,另一種則是 Codex GitHub PR 自動審查。
自從 Codex GitHub PR 自動審查推出以來,這些程式碼庫中大多數的程式碼變更都有 Codex 協助審查。我們將它納入例行審查,而非只在特殊情況下使用。
對於單純的程式錯誤、功能退化和遺漏的測試,實務經驗顯示,現在已能放心將 Codex 審查設為必要流程。它能反覆依相同準則檢查常見的正確性問題,消除了小幅修正和例行改進的一大瓶頸。
同儕審查仍然重要,尤其是在處理另一類變更時。
當主要問題從「這段程式碼是否正確」變成「幾種可行方案中應選哪一種,又該如何推出」時,人工審查仍然不可或缺。這類情況包括:
- API 或架構變更有多種合理設計,需要維護者明確選擇
- 行為變更會影響使用者對產品的預期、回溯相容性承諾或推出政策
- 需要決定命名、遷移方式或如何傳達發行資訊,而難處在於判斷怎麼做才能讓使用者與貢獻者最容易理解
- 需要維護者或團隊協調的變更,例如界定工作範圍、安排先後順序,或決定哪些內容現在推出、哪些留待之後
Codex 在這些情況下都能提供協助,但仍需要有人直接討論並做決定。
AGENTS.md 也可以記錄這樣的分工:程式碼庫可以指明審查正確性時應注意哪些重點,讓 Codex 一致地套用這些指引。
這項分工也顯著提高了開發吞吐量。每次低風險變更所需的例行審查與驗證,不必再等審查者騰出時間。維護者則能專注在需要掌握更多背景、也更仰賴自身判斷的審查工作上。這讓我們能更快修正積壓的錯誤,並完成小幅功能改進。
結語
在 OpenAI Agents SDK 程式碼庫中,將技能納入日常開發流程最能發揮其作用。
AGENTS.md 告訴 Codex 哪些工作流程必須執行,description 說明何時該選用這些流程。scripts/ 負責步驟固定的部分,模型則負責需要依上下文判斷的部分。等工作流程在本機穩定運作後,就能透過 Codex GitHub Action 在 CI 中執行相同流程。
這些做法讓程式碼庫的日常工程工作更明確,也更可靠。驗證、發行審查與 PR 交接如今都有可重複執行的一致流程,因此我們也更容易快速推出小幅改進。