正本: openai-llm-agent-engineering-guide.md / 基準日: 2026-09-05 / 84見出し

OpenAI版 LLM・Agent Engineering Guide

基準日: 2026-09-05（依頼時点） 再確認日: 2026-09-06。現行本文による改訂であり、更新日時がないページの9月5日時点の内容は保証しない。 対象: OpenAI API / Responses API / Agents SDK / MCP / Codexの設計境界 正本: このMarkdown。iPhone向けHTMLはこの原稿から生成する。

この資料の立場

OpenAIの公式情報は、API、Agents SDK、Codex、Academy、Cookbook、公式GitHubなど複数の面に分かれている。これらは同じ製品ではない。本資料では、モデルを呼ぶAPI、Agent loopを実行するSDK、開発作業を実行するCodexを分けて記述する。

以下、API名・フィールド・製品挙動の記述は章末Sourcesに対応する公式仕様、設計上の選択と擬似コードは実務上の解釈として読む。個別の監査根拠は OpenAIレビュー記録 に残す。

章中のラベル:

• 公式仕様: OpenAIまたはMCPのDocs本文が記述するAPI・SDK・製品挙動。
• 公式推奨: OpenAI Docs、Model Spec、Academy、Cookbookなどの推奨。
• 実務上の解釈: 仕様をアプリケーション設計へ翻訳した説明。
• 一般化した原則: OpenAI固有APIに依存しない設計原則。
• 要再確認: モデル、SDK、beta、preview、deprecated、製品面に依存する記述。

全体像

OpenAIでAgentを作るとき、Responses APIを直接使うならApplicationがloopを所有し、Agents SDKを使うならRunnerがloop、handoff、Tool、guardrailなどを管理する。どちらの場合も、実行を担うHostとモデルの判断を分ける。

Responses APIは「モデル応答」とTool callを扱う低レベル寄りの面、Agents SDKは「Agent run」と専門Agentの協調を扱う高レベル寄りの面、と捉えると、どこに制御コードを書くべきかが分かる。

Part 1 — LLMの基本制御

1.1 Instructions、input、Context

OpenAI APIのPromptは、単なるuser文字列ではない。Responses APIでは、ApplicationのInstructions、ユーザーのinput、過去のresponse item、Toolの定義と結果、取得したデータなどが、一回のモデル実行に見えるContextを作る。

Chat Completionsなどのmessage APIではroleが重要で、OpenAIのPrompt engineering guideはdeveloper messageをuser messageより優先されるアプリケーション開発者の指示として説明する。Model Specは指示の優先順位・権限・安全境界を定めるための基準であり、「developerなら必ず実行できる」という意味ではない。Hostの認可・Tool実行境界は別に必要である。

1.2 公式Prompt engineeringの要点

公式Prompt engineering guideの現在の方向性は、Promptを機能の近くに小さなmoduleとして管理し、動的値にはtyped argumentやschemaを使い、代表fixture・test・evalをPrompt変更前に用意し、必要ならfeature flagで段階展開することである。

効果的なPromptは、次を明示する。

• Goalと成功条件。
• 役割、制約、許可されたTool。
• 参照データと命令の境界。
• 欠損情報、不確実性、エラー時の扱い。
• 出力形式、必須フィールド、引用・証拠の要件。
• 曖昧な要求で質問するのか、安全なデフォルトで進めるのか。

1.3 Few-shot、構造化、Prompt injection

Few-shotは、出力の形式・トーン・分類境界を例で示す方法である。例は代表性、境界値、反例を含む。例の数を増やすほどよいのではなく、評価で必要な振る舞いをカバーする。

外部文書、Web検索、MCP、ユーザー入力に含まれる命令らしい文字列を、Developer instructionと同列に置かない。XML、JSON、セクション見出しなどで境界を示し、重要な操作はモデルの文面ではなく、Tool schema・guardrail・approval・実行ポリシーで制御する。

公式推奨（Academy）: 「Prompting」の task / context / ideal output を、上記の目的・参照情報・出力契約の分離に採用した。これはChatGPT利用教育の助言であり、APIのrole優先順位やJSON Schema保証の根拠には使わない。

1.4 Structured Outputs

Structured Outputsは、モデルのテキスト応答を指定したJSON Schemaへ適合させるOpenAI APIの機能である。Function callingのTool引数を構造化することとは目的が違う。

Responsesでは次のオブジェクトを text.format に指定する（Chat Completionsの response_format と配置が異なる）。拒否（refusal）や上限到達によるincompleteを先に判定し、Schema準拠だけで内容の真偽を保証しない。

Schemaは契約であり、認可ではない。たとえば action: "delete" がSchemaに適合しても、対象、ユーザー、承認、予算をHostが再検査する。

{
  "type": "json_schema",
  "name": "risk_report",
  "strict": true,
  "schema": {
    "type": "object",
    "properties": {
      "severity": {
        "type": "string",
        "enum": ["low", "medium", "high"]
      },
      "evidence": {
        "type": "array",
        "items": {"type": "string"}
      }
    },
    "required": ["severity", "evidence"],
    "additionalProperties": false
  }
}

1.5 Prompt cachingと継続指示

公式仕様: previous_response_id は前回の instructions を引き継がない。継続時も必要な指示を各リクエストへ渡す。Prompt cachingは再利用可能な入力prefixの計算を共有する仕組みで、会話Memoryや権限設定ではない。固定規約・Tool定義と変動データを分け、ヒットをusageで確認する。閾値・書き込み料金・明示的breakpointの有無はモデル世代で異なるため、共通の料金や最小token数を断定しない。

OpenAI ResponsesにClaudeのassistant prefillをそのまま移植する前提は置かない。出力契約にはInstructions、例、Structured Outputsを使う。

Part 1 Sources

• Prompt caching — prefix再利用とモデル差。
• Prompting — OpenAI Academy — task / context / ideal output。

• Prompt engineering — OpenAI API — role、Prompt module、typed arguments、eval。
• Model Spec — instruction hierarchyとbehavioral contract。
• Structured model outputs — JSON Schemaとstrict。

Part 2 — Context Engineering

2.1 OpenAIのConversation state

一回のtext generation request自体は、明示的に状態を渡さなければ独立している。OpenAIの現行Docsは、Responses APIとConversations APIを組み合わせて、messages、tool calls、tool outputsなどのitemを長期的なConversation objectへ保存できると説明する。別の方法として、previous_response_idを次回へ渡して応答を連鎖させる。

Conversation stateを使っても、Context設計が自動で終わるわけではない。保存状態、ユーザーが再利用してよい情報、保持期間、削除、Model migration、Tool resultの縮約を設計する。

2.2 Context windowと履歴

Modelへ渡すContextには、Developer instructions、User input、過去のoutput、Tool call、Tool result、画像、ファイル、検索結果、Function schemaが含まれる。履歴を増やすほど、関連性の低い観測、重複データ、古い指示がモデルの注意を奪う。

Prompt engineeringが「指示の書き方」なら、Context engineeringは「毎回どの状態を提示するか」である。全履歴を毎回送るか、Conversation APIに預けるか、previous_response_idでつなぐか、要約・検索・削除を行うかは、品質、コスト、監査、保持要件のトレードオフで決める。

2.3 Compaction

OpenAIのCompaction guideには二つの面がある。

• Server-side compaction: Responses createでcontext_managementとcompact_thresholdを設定し、閾値を超えたときにサーバーが圧縮itemを生成する。
• Standalone compact endpoint: 長いContextを明示的に /responses/compact へ送り、返された圧縮Contextを次のResponses callへ渡す。

圧縮itemは、後続の実行に必要な状態を少ないTokenで運ぶためのopaqueなデータとして扱う。人間に読める要約の完全な代用品とは限らない。重要な決定事項、テスト結果、証拠、未解決点、ユーザー承認をアプリケーション側の状態として保存する。

Standalone compactの返却値は圧縮item一つだけとは限らない。残存itemを含む返却window全体を次のinputへ渡し、独自に削らない。

2.4 StreamingとBackground mode

Streamingは、最終結果を待たずにイベントを受け取るUX・監視の仕組みである。Background modeは長いResponsesを非同期で開始し、Response objectの状態をpollするための仕組みである。どちらもAgent loopの内部状態をユーザーへ出す機能とは限らない。

Background taskでは、再試行、polling間隔、キャンセル、失敗状態、保持・削除、ユーザーへの通知を設計する。Streamingでは、部分テキストを確定値と誤解せず、最終イベントとTool side effectの状態を分ける。

2.5 Retrieval、Memory、Skills

Retrievalは外部Knowledgeから必要な断片を探してContextへ追加する。Memoryは、将来の会話で再利用する情報を選んで保存する。Skillsは、OpenAIの現行APIではSKILL.mdを含むversioned bundleとして、Hosted shellやlocal executionへ再利用可能な手順・資産を提供する。

「保存した」ことと「今回の推論へ入れた」ことは別である。MemoryやConversation itemを保存しても、毎回すべてをPromptに入れず、必要なときだけ取得する。

Part 2 Sources

• Conversation state — Conversations API、previous_response_id、item。
• Compaction — server-side / standalone compaction。
• Streaming API responses — event stream。
• Background mode — 非同期開始とpolling。
• Skills — versioned bundle、SKILL.md、local/hosted execution。

Part 3 — Tool Use

3.1 Function callingの役割

Function callingは、モデルがアプリケーションの関数を呼びたいとき、関数名と引数を構造化して返す仕組みである。OpenAIの現行Responses APIでは、モデルのoutputにfunction_call itemが含まれ、Applicationが関数を実行し、function_call_output itemを次のinputへ渡す。

{
  "type": "function",
  "name": "get_weather",
  "description": "都市の現在の天気を読み取り専用で取得する。",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string"}
    },
    "required": ["location"],
    "additionalProperties": false
  },
  "strict": true
}

Chat Completionsの tool_calls とResponsesの function_call は似ているが、itemの形や返し方が同一ではない。移植時は使用するEndpointの現行サンプルを参照する。

3.2 Function call lifecycle

1. ApplicationがTool定義とinputをResponses APIへ送る。
2. Modelが通常のmessage、または一つ以上のfunction_callを返す。
3. Applicationがcall_id、name、JSON argumentsをparseし、Schemaを検証する。
4. Permission、入力値、対象resource、side effect、approvalを確認する。
5. 関数を実行し、成功または構造化エラーを返す。
6. 同じcall_idに対応するfunction_call_outputをinputへ追加し、Responses APIを再度呼ぶ。
7. Modelが次のfunction_callを出すか、最終outputを返す。

モデルが関数を直接呼ぶわけではない。Hosted toolsでも、実行場所と結果の責任、データ共有、利用制限を公式Docsで確認する。

3.3 Hosted tools、Tool search、Programmatic Tool Calling

現行のOpenAI Tools guideは、Web search、File search、Function calling、Remote MCP、Tool search、Programmatic Tool Calling、Shell、Computer useなどを別のTool面として並べる。

• Hosted tool: OpenAIのインフラ側で実行されるTool。対応Model、料金、保持、結果形式を確認する。
• Function tool: Applicationが実装し、モデルは呼び出しを提案する。
• Tool search: 大量のTool definitionを遅延ロードし、必要なものだけContextへ入れる。
• Programmatic Tool Calling: Toolの組合せや反復をプログラム的にオーケストレーションする。
• Shell / Computer use: 実行環境や画面操作という大きな副作用面を持つ。Sandboxとapprovalを別途設計する。

Tool surfaceを増やすと能力だけでなく、選択肢・Schema・権限・Contextが増える。Tool名、description、input/output、エラー、side effect、認可を小さく保つ。

3.4 Tool choiceと並列性

公式仕様: tool_choice の auto は0件以上、required は1件以上、特定function指定はその関数を呼ぶ指定、none はToolを使わない指定である。parallel_tool_calls: false は0または1件に制限する。モデルが複数callを返しても、Hostが必ず並列実行するわけではない。依存関係がある処理は結果を返してから次を選ばせ、独立した読み取りだけを並列化する。

strict: true では各objectに additionalProperties: false、全propertiesにrequiredが必要で、任意値はnullableなどで表す。strict省略時の挙動はAPI間で異なるため、例では明示する。

3.5 Retry、timeout、side effect

一時的なネットワークエラーや429だけを限定的にretryする。書き込みをretryするならidempotency keyと重複検知を使う。Tool callの引数をschemaに適合させても、対象ユーザーが許可されているとは限らない。実行直前に権限を再評価する。

最小ループと承認・失敗分岐は Part 14 にまとめる。Toolごとの拒否と「承認待ち」を区別し、承認待ちを成功したTool結果として返してはならない。

Part 3 Sources

• Function calling — Tool schema、function_call、function_call_output、複数call。
• Structured model outputs — Schema制約。
• Using tools — Hosted tools、Tool search、Programmatic Tool Calling、実行面。

Part 4 — Model Context Protocol (MCP)

4.1 OpenAIにおけるMCP

OpenAI APIでは、remote MCP serverとconnectorをResponses APIのMCP built-in tool typeへ接続できる。OpenAIのDocsは、connectorをOpenAIが保守するMCP wrapper、remote MCP serverをAPIから到達できるMCP実装として扱う。通常のserver_url接続とSecure MCP Tunnelなどの接続手段は区別する。

MCPはOpenAI専用のTool formatではない。Serverの能力を発見し、Hostがモデルへ提示し、必要なTool callを実行するための外部プロトコルである。

4.2 Connector、remote server、OAuth

remote MCP serverにはserver_urlが必要で、ServerによりOAuth access tokenなどのauthorizationが必要になる。Connectorは対象サービスとOpenAI側の対応があるため、任意のMCP Serverと同じ運用ではない。

OpenAI MCP guideは、第三者MCP Serverが要求するデータを確認し、公式提供元のServerを優先し、送信データをログ・レビューし、Tool callをapproval制御することを勧めている。悪意あるServerが隠れたPrompt injectionや、後から変化するTool behaviorを含み得る点にも注意する。

4.3 MCPとFunction callingの対応

MCP Serverはユーザーの全会話を持つ前提ではない。MCP仕様のHost–Client–Server境界と、OpenAI APIのMCP connectorの実装・approval設定を別々に読む。

4.4 プロトコル版と製品対応の分離

公式仕様: MCP 2026-07-28では旧stateful initialization/session中心の説明が変更されている。2025-06-18のinitializeを現行必須手順として転記しない（版差分はAnthropic版Part 4）。一方、Responses DocsはStreamable HTTPと旧HTTP/SSE接続を説明しており、MCP最新版が全モデル・SDK・connectorへ対応済みとは確認できない。

Responses built-in MCPの本文で確認できるのは主にTool一覧・Tool呼び出し・承認である。MCP Resources / Promptsの存在からResponsesで自動取得・起動できるとは推論しない。必要なら個別SDK/Hostの対応確認とContextへの取り込み実装を行う。

Part 4 Sources

• MCP 2026-07-28 changes — 現行版への変更。

• MCP and Connectors — Remote MCP、connector、OAuth、approval、data review。
• MCP Architecture — Host、Client、Serverの責任分離。
• MCP Lifecycle — 旧版のsession、capability negotiation。
• MCP Tools — tools/list、model-controlled、human denial。

Part 5 — Agent

5.1 Responses APIとAgents SDK

OpenAIの現行Agents guideは、Responses APIを使う場合はApplicationがmodel interaction、output item、Tool、state、orchestration、custom loopを直接所有し、Agents SDKを使う場合はSDKがAgent loop、repeated Tool call、branching、handoff、session、tracing、guardrailなどを支援すると整理している。

これは「Responses APIにAgentは作れない」という意味ではない。Responses APIのfunction-calling round tripを自分で繰り返せばAgent loopになる。SDKはその共通構造を抽象化する。

5.2 Agent、Run、Runner

Agents SDKの最小モデルは、Agentへname、instructions、toolsなどを定義し、Runnerで入力を実行し、resultからfinal outputを読む形である。SDKを使うと、Agentの定義と一回のRunを分けて、Handoff、Agent as tool、Guardrail、State、Tracingを積み上げられる。

Part 5 Sources

• Agents SDK — Responses APIとAgents SDKの設計選択。
• Agents SDK Quickstart — Agent定義、Run、Tool追加の導入。
• OpenAI Agents SDK Python docs — Agent、Runner、Tools、Handoffs、Tracing。

Part 6 — Agentic Patterns

6.1 Handoffs

Handoffは、専門Agentがそのbranchの会話と次の応答を引き継ぐ構成である。TriageがBilling Agentへ渡した後、Billing Agentがユーザー向けの答えを所有する。

• 向く: 専門Agentがユーザーとの継続会話を所有する場合。
• 避ける: 親が最終出力と一貫したPolicyを一元管理したい場合。
• Failure mode: Context・権限・Guardrailが専門Agentへ正しく伝わらない、誤routing。

6.2 Agents as tools

Agents as toolsは、Manager Agentが専門Agentをbounded capabilityとして呼び出し、最終回答の所有権をManagerに残す構成である。OpenAIのOrchestration guideは、Handoffsはcontrolが専門Agentへ移り、Agents as toolsはmanagerがreplyの所有権を保つと説明する。

• 向く: 親が複数の調査結果を統合し、最終形式・承認を管理する場合。
• 避ける: 専門Agentが直接ユーザーと長い会話を続けるべき場合。
• Failure mode: 子Agentの出力が巨大、親が検証せず採用、無限の再委譲。

6.3 Prompt chaining、Routing、Parallelization

OpenAI固有のAPIを超えて、Prompt chaining、Routing、Parallelization、Evaluator-optimizer、Orchestrator-workerは一般的なAgentパターンとして利用できる。並列処理にはSDKの複数Agent、async Tool、アプリケーションのtask queueなど複数の実装がある。

6.4 Subagentとの関係

Handoff / Agents as toolsはSDKのOrchestration APIに近い。CodexのSubagent workflowは、開発作業の別thread・並列worker・Context分離に近い。名前が似ていても、会話所有権、Tool、state、filesystem、approvalを同じものとみなさない。

Part 6 Sources

• Orchestration and handoffs — HandoffとAgents as tools。
• OpenAI Agents SDK Handoffs — Handoff API。
• OpenAI Agents SDK Tools — Function tools、Hosted tools、MCP。

Part 7 — Codex Architecture

7.1 CodexはOpenAI APIと別の製品面

Codexはコードベースを探索し、ファイルを編集し、shellを実行し、テストやレビューを行うCoding Agentの製品面である。APIのResponses loopやAgents SDKと同じ設計原則を持ち得るが、CodexのCLI、IDE、Cloud、ChatGPT連携の設定・権限・SandboxはOpenAI APIの自作Hostへ自動移植されない。

Codexの最小Mental Modelは、Modelが「次の作業」を提案し、Codex harnessがworkspace、Tool、Permission、Sandbox、実行結果、ユーザーの承認を管理する、というものだ。

7.2 Explore、Plan、Implement、Verify

Coding Agentの作業は、要求を受けたらまずRepositoryと指示ファイルを探索し、計画を作り、編集・実行し、diffとテストで検証するループになる。探索ログを全部最終回答へ貼る必要はないが、決定に必要な証拠と検証結果は残す。

Git操作は段階的に扱う。ファイル編集、commit、branch、push、PR、merge、本番deployは同じ「コード変更」ではない。Sandboxやpermissionが許しても、外部反映の許可があるとは限らない。

7.3 AGENTS.md、Skills、MCP

AGENTS.mdはCodexのPersistent project instructionである。Skillsは再利用可能な知識・手順・資産、MCPは外部サービスへの接続、SubagentはContextや専門性を分ける仕組み、permission/sandboxは実行境界である。

Part 7 Sources

• Codex overview — Codexの製品入口。現在のページ移転先も確認する。
• Custom instructions with AGENTS.md — Codexのinstruction discoveryとmerge order。
• Codex official repository — CLI・実装・変更履歴の一次情報。
• Permissions — Codexのpermission / sandbox / approval。

Part 8 — AGENTS.md

8.1 Discovery hierarchy

現行のCodex Docsは、global scopeではCodex homeのAGENTS.override.mdがあればそれを使い、なければAGENTS.mdを使う。Project scopeではproject rootからcurrent working directoryまで各ディレクトリを調べ、各場所でoverride、AGENTS.md、設定されたfallback filenameを最大一つ読み、rootからcurrent directoryへ連結する。

下位のファイルが後に現れるため、より近いルールが広いルールを補足・具体化できる。ただし、これは自然言語のinstruction chainであり、権限設定のhard denyとは別である。

Discoveryはrun開始時に行う。project rootを発見できなければcurrent directoryだけを調べる。

現行Docsでは、combined instructionのbyte limitは32 KiB defaultと説明される。大きすぎるAGENTS.mdは切り分け、nested directoryやfallback設定を使う。

8.2 Claudeとの違い

Claude CodeはCLAUDE.mdを読み、OpenAI CodexはAGENTS.mdを読み込む。プロジェクトが両方を使う場合、別ファイルを重複管理するか、Claude側から参照するか、共有原稿から生成するかをチームで決める。Codex AGENTS.mdにClaudeと同じ @file import機構があるとは仮定しない。両者の指示が矛盾すると、どのモデルがどちらを優先するかを推測せず、共有規約と製品固有規約を分ける。

# AGENTS.md: project-level and verifiable
- Use pnpm for package management.
- Run pnpm test and pnpm lint after JavaScript changes.
- Keep API handlers under src/api/handlers/.
- Ask before pushing, deploying, or changing secrets.
- Report the exact verification command and result.

AGENTS.mdへ全API仕様や大量ログを貼るのは、Context costと更新負担を増やす。詳細な手順はSkill、path-specific rule、リポジトリ内のreferenceへ分ける。

Part 8 Sources

• Custom instructions with AGENTS.md — discovery、override、fallback、byte limit。
• Codex overview — Codexの公式入口。

Part 9 — Skills

9.1 OpenAI API Skills

OpenAIの現行Skills guideは、SkillをSKILL.md manifestと複数ファイルからなるversioned bundleと説明する。front matterにname、descriptionなどを置き、本文に手順・規約を置き、Python等のscriptやreferenceを同梱できる。Hosted container-based executionとlocal shell executionの両方がある。

SkillはToolそのものではない。Toolに実行させる知識・手順・資産を遅延ロードするpackageに近い。モデルがSkillを使っても、side effectの認可、scriptの隔離、入力検証は実行Hostの責任である。

9.2 Codexの発見・起動・配布

公式仕様（Codex）: repositoryではCWDからrepo rootまでの各 .agents/skills、userでは ~/.agents/skills、adminでは /etc/codex/skills、加えて同梱system skillsを探索する。同名Skillはマージされず、両方が選択候補になり得る。プラグイン配布と直接置くローカルSkillは別の導入面である。

最初はname、description、pathをContextへ提示し、選択時にSKILL.md本文、必要に応じてreferencesやscriptsを読む。初期一覧には予算があり、多数導入時はdescription短縮や候補省略が起こる。全文ロードの保証と、初期一覧へ全件載る保証は別である。

Codex CLI/IDEでは /skills や $skill-name による明示起動と、descriptionに合致する暗黙起動がある。agents/openai.yaml の policy.allow_implicit_invocation: false は暗黙起動を止めるが明示起動は残す。これはTool認可の設定ではない。

# SKILL.mdのfrontmatter例
---
name: review-api-contract
description: APIの入出力契約を変更するときにSchemaと互換性をレビューする。
---

本文には入力・手順・検証・出力を記述し、補助資料を references/、コードを scripts/、テンプレートを assets/ に分ける。Skillは独立Agentや実行Toolではなく、Hostが読み利用するpackageである。

9.3 権限と移植可能性

実務上の解釈: Skillの発見・読込みは、shellやnetworkの権限付与ではない。scriptsはHostのpermission、sandbox、approvalに従って実行する。Claude Codeの allowed-tools をCodexで同じ権限効果があるfieldとしてコピーしない。本文・資産は共有可能でも、探索path、起動UI、追加metadata、利用Tool名はHostごとに検証する。

公式仕様（API）: hosted shellはuploadした skill_reference をattachする。local shellはこれを受け付けず、Hostが管理するpath・name・descriptionを渡す。API Skillsのmetadata/本文はuser prompt inputとして扱われ、system instructionには昇格しない。Codexのローカル探索設定や agents/openai.yaml をAPIへ渡すだけでは同じ動作にならない。

Part 9 Sources

• Build skills — Codexのdiscovery、起動、metadata、plugin配布。

• Skills — OpenAI API — SKILL.md、versioned bundle、hosted/local。
• Claude Code Skills — Claude側のSkill discoveryとscope。
• Agent Skills standard — 共通形式を参照する場合の一次入口。

Part 10 — Hooks

10.1 Codex製品のHooks

公式仕様（2026-09-06本文確認）: Codexにはlifecycle Hooksがある。hooks.json または config.toml の [hooks]、およびpluginで設定する。project層のtrustと、非managed hook定義そのもののtrust reviewは別で、変更後の定義は再レビューまでskipされる。

対応handlerは command と mcp_tool。prompt と agent は解析されてもskipされるため、Claude CodeのLLM評価Hookをそのまま持ち込めない。Hookはイベント起動の機構であり、呼ばれるMCP ToolやscriptがLLMを使えば判定結果まで決定的とは限らない。

PreToolUse / PostToolUse はshell/unified execを Bash、patchを apply_patch（別名Edit/Write）、MCPとその他local functionをTool名で照合する。Hosted WebSearch等は対象外。write_stdin は既存実行への入力・pollなのでPreToolUseを再実行しない。これだけで全実行を隔離することはできない。

10.2 成否・拒否・非同期の契約

同期PreToolUseでは対応するJSONの permissionDecision: "deny"、またはexit 2とstderrで拒否できる。allow と updatedInput は書換え用。ask や continue: false は同イベントでは未対応で、Hook失敗を報告してToolを続行する。PermissionRequestは別schemaでallow/denyを返し、複数判断ではdenyが優先する。

MCP hookは接続済みServerを使い、Server不在・Tool不在・呼出エラーでは操作を阻止しない。async: true のcommand hookは情報提供用で、起動元操作の阻止・承認・書換えはできない。複数のmatching command hookは並行に起動するため、一つの拒否が他Hook自身の副作用を止めるとは限らない。

実務上の解釈: formatterやログはHookに向く。禁止事項の完全な強制にはsandbox・認可・CI gateを併用し、同期/非同期・対応Tool・失敗時継続を受入テストする。命令文で「必ずテストして」と頼むことと、実行境界でテストを起動することを区別する。

10.3 OpenAI APIのHook相当

OpenAI APIのResponses APIやFunction callingには、Claude Codeのlifecycle hookと同じ製品機能が必ず付くわけではない。自作Hostでは、middleware、Tool wrapper、guardrail、queue worker、CI、監査ログを組み合わせて、PreToolUse / PostToolUse相当の境界を作る。

Agents SDKにはInput guardrails、Output guardrails、Tool guardrails、Human reviewがある。これは「毎回決まったscriptをlifecycleで起動するHook」と同じではないが、Model判断とPolicy実行を分けるための主要な制御面である。

10.4 決定的処理の置き場所

「モデルに毎回テストを頼む」は、検証をモデルの判断へ置く。必ず行うテスト、秘密へのアクセス拒否、deploy前のApprovalは、deterministicな実行層へ置く。

Part 10 Sources

• Codex Hooks — イベント、Tool coverage、trust、output、MCP、async。
• Advanced configuration — config層とHooks設定。

• Guardrails and human review — automatic checks、human review、tool guardrail。
• Agents SDK — SDKが提供するAgent runと制御面。
• Claude Hooks reference — 製品固有Hookとの比較対象。

Part 11 — Subagents

11.1 CodexのSubagent workflow

Codex / ChatGPT Learnの現行Docsは、Subagent workflowを、複数の専門Agentを並列に起動し結果を一つに集約する仕組みとして説明する。現行local Codexではユーザーの直接依頼、または適用されるAGENTS.md/Skillの委譲指示が起動条件となる。各Subagentは自分のModelとTool作業を行うため、同じ作業を単一Agentで行うよりTokenを多く消費し得る。

Subagentを使う価値は、作業者を増やすことだけではない。親のContextから、探索ログ、stack trace、大量テスト結果を分離し、要約・証拠・未解決点だけ返せる。read-heavyな探索・triage・test reviewは向くが、複数Agentが同じファイルを同時編集するwrite-heavy作業は競合しやすい。

11.2 Agents SDKとの違い

Agents SDKのHandoffは、Agentが会話のcontrolを別Agentへ渡す。Agents as toolsはManagerが専門Agentの結果を使う。Codex Subagentは、開発作業を別thread・別Contextへ委譲し、親へ返す製品ワークフローである。いずれも「子の結果を親が検証する」境界を残す。

Part 11 Sources

• Subagents — ChatGPT Learn — parallel workflow、Context pollution、token cost、custom agents。
• Orchestration and handoffs — Handoff / Agents as tools。

Part 12 — Permissions / Security

12.1 GuardrailとHuman review

OpenAIのAgents guideは、Guardrailを自動検証、Human reviewを承認判断として区別する。Input guardrailはblocking設定ならMain model前（parallel設定では投機的に同時実行）、Output guardrailは最終出力、Tool guardrailは関数Toolの引数・結果周辺、Human reviewは取消、編集、shell、敏感なMCP操作などのside effect前に使う。

Agent-level guardrailの範囲には注意が必要で、現行DocsはInput guardrailがchainの最初のAgent、Output guardrailが最終出力Agent、Tool guardrailが付与されたFunction toolで実行されると説明する。すべてのTool callをチェックしたいなら、side effectを起こすToolの近くへ検査を置く。

12.2 CodexのPermission、Sandbox

Codexのpermission / sandboxは、Modelの指示ではなく、filesystem、shell、network、workspace、approvalの実行境界である。権限が広いほど、Prompt injection、悪意あるリポジトリ、誤ったshell引数、秘密の読み取り、外部サービスの副作用を評価する。

read source files         -> allow in scoped workspace
edit source               -> show diff and run checks
read secrets              -> deny unless explicitly required
shell in sandbox          -> allow bounded commands
network / external MCP    -> host allowlist + data review
delete / publish / send   -> human approval
push / merge / deploy     -> separate authorization

12.3 MCPのSecurity

MCP Serverが返すTool definition、Resource、Prompt、Tool resultは、すべてApplicationが信頼できるとは限らない。公式提供元のServerを優先し、送信するデータを確認し、approvalをデフォルトで要求し、Tool変更やPrompt injectionを監視する。OAuth tokenを静的サイトやPromptへ出さない。

Part 12 Sources

• Guardrails and human review — Guardrail範囲、HITL approval。
• MCP and Connectors — approval、data sharing、第三者Serverのリスク。
• Permissions — Codexのpermissions、sandbox。
• Model Spec — instructionとsafetyの考え方。

Part 13 — Verification / Evals

13.1 OpenAIのAgent eval surface

OpenAIのAgent eval guideは、Traces、Graders、Datasets、Eval runsを用いてAgent qualityを改善する流れを示す。Traceは一回のWorkflowについてModel call、Tool call、Guardrail、Handoffを含むend-to-end recordで、Trace graderはTool選択、handoff、Policy違反、Prompt変更の影響を評価する。

評価は最終回答の正しさだけでは足りない。

• 適切なToolを選んだか。
• 引数と対象が正しいか。
• 不要なToolを呼んでいないか。
• Approval前にside effectを起こしていないか。
• Handoffの所有権が正しいか。
• エラーから回復したか。
• Context compaction後も重要制約を保ったか。

13.2 Evaluation loop

Automated test、Schema validation、trace grading、Human reviewを使い分ける。EvaluatorがModelと同じ誤りを持つ場合、評価が高くても実際の品質は上がらない。

公式推奨（Cookbook）: evaluation flywheelの「代表データ作成→実行→失敗分析→Prompt改善→再評価」を本章の評価図に採用する。旧dashboardの画面操作や特定モデル例は現行API保証として転記しない。

Part 13 Sources

• Building resilient prompts using an evaluation flywheel — 反復評価の具体的教材。

• Evaluate agent workflows — Traces、Graders、Datasets、Eval runs。
• Guardrails and human review — workflowを止める自動検証とHITL。
• Function calling — Tool call round tripの観測対象。

Part 14 — OpenAI APIでAgentを自作する場合

14.1 Responses APIを直接使う

Applicationがloopを持つなら、Responses APIのTool callを受け、検証し、実行し、output itemを次のinputへ返す。Stateは明示的なinput array、previous_response_id、Conversation object、Application DBのいずれかを選ぶ。

# 構造説明用。runtimeは永続化・承認UI・認可・結果制限を実装するHost。
def run_responses_agent(client, user_text, runtime, max_turns=8):
    input_items = [{"role": "user", "content": user_text}]
    for turn in range(max_turns):
        response = client.responses.create(
            model=MODEL_NAME, instructions=DEVELOPER_INSTRUCTIONS,
            input=input_items, tools=TOOLS,
        )
        if response.status != "completed":
            return {"status": "incomplete", "response_id": response.id}
        input_items.extend(response.output)  # reasoning等も保持する
        calls = [x for x in response.output if x.type == "function_call"]
        if not calls:
            return runtime.verify_final(response)  # refusalもここで識別
        for index, call in enumerate(calls):
            try:
                args = runtime.parse_and_validate(call.name, call.arguments)
                decision = runtime.review(call.name, args)
                if decision == "pending":
                    # 未実行callと残りcallを永続化し、同じcallを後で再開する。
                    # 再開処理は承認対象のhash・権限・対象の現在状態を再検証する。
                    return runtime.pause(input_items, calls[index:], turn, max_turns)
                if decision == "denied":
                    result = {"error": "denied"}
                elif decision == "approved":
                    runtime.revalidate(call.name, args)
                    result = runtime.execute(
                        call.name, args, timeout=20,
                        idempotency_key=runtime.operation_key(call),
                    )
                else:
                    result = {"error": "unknown_review_state"}
            except ValueError:
                result = {"error": "invalid_arguments"}
            except PermissionError:
                result = {"error": "permission_changed"}
            except TimeoutError:
                result = {"error": "timeout", "outcome": "unknown"}
            except runtime.ToolExecutionError:
                result = {"error": "tool_failed"}
            input_items.append({
                "type": "function_call_output", "call_id": call.call_id,
                "output": runtime.encode_bounded(result),
            })
    return {"status": "incomplete", "reason": "max_turns"}

承認待ちからの再開は新規model callで代用せず、保存したpending callを取り出し、承認対象の一致・認可・変更された対象を再検査してから実行する。複数callの途中でpauseした場合も残り順序とturn budgetを維持する。timeoutは外部副作用の失敗を保証しないため、状態照会してからretryする。idempotency keyは新しいモデルcall IDだけに依存せず、同じ業務操作の再試行を識別する。

実際のSDKのmodel名、input item形、JSON schema、response statusは、使用する現行DocsとSDK versionに合わせる。この例は構造理解用で、API keyや実サービスの認証を含めない。

14.2 Agents SDKを使う

Agents SDKでは、Agent definitionへinstructions、tools、handoffs、guardrailsを登録し、Runnerで実行する。SDKがloopを持つ場合でも、Toolの実装、権限、実行時間、監査、データ保持、ApprovalのownerはApplicationである。

Part 14 Sources

• Agents SDK — APIとSDKの責任分担。
• Agents SDK Quickstart — 最小Agent run。
• Function calling — Responsesのfunction call cycle。
• Conversation state — Stateの保持方法。

Part 15 — Local LLMへ移植する際の考え方

15.1 一般化できる原則

OpenAIのAPI名ではなく、Hostの責任をローカルへ移植する。

15.2 OpenAI固有で移植できないもの

Responsesのitem schema、previous_response_id、Conversations API、server-side compaction、Hosted tools、OpenAIのMCP connector、Agents SDK Runner、CodexのAGENTS.md discovery、Codexのsandbox UIは、OpenAIの実装である。ローカルLLMが同じ名のfieldを返すとは限らない。

MCPを使えばTool接続の一部を共有できるが、MCP Client、Host、認証、UI、approval、Model Tool formatのadapterは必要である。

15.3 Local architecture

15.4 移植の順序

1. 一回の生成とStructured outputを固定する。
2. 読み取り専用Function toolを一つ追加し、call → execute → outputをテストする。
3. timeout、retry、max turns、エラー、ログを入れる。
4. permission、sandbox、HITLをside effectの前に追加する。
5. Conversation state、Retrieval、Compactionを追加する。
6. 必要な場合だけMCP、Skills、Subagents、background workerを足す。
7. Datasetとregression evalで、モデル・Prompt・Toolの変更を監視する。

一般化した結論: Responses API、Agents SDK、Codexはいずれも、Modelの出力を信頼して直接実行するのではなく、HostがContext、Tool、Policy、State、Verificationを編成することでAgentになる。

Part 15 Sources

• Compaction — 長時間会話のstate縮約。
• Using tools — Tool surfaceの分類。
• MCP and Connectors — MCP adapterとapproval。
• Evaluate agent workflows — Trace / Evalの一般化。

付録 — OpenAI版の更新チェック

1. API Docs index とモデル・Deprecationsを確認する。
2. Responses API、Conversation state、Compaction、Streaming、Background modeを確認する。
3. Function calling、Structured Outputs、Using tools、MCP、SkillsのSchemaと利用可能Modelを確認する。
4. Agents SDKのQuickstart、Orchestration、Guardrails、Results/state、Tracing、Evalsを確認する。
5. CodexのAGENTS.md、Skills、Subagents、Permissions、Sandboxの製品Docsとchangelogを確認する。
6. 公式Cookbook、公式GitHubの例が現行SDK import・API endpointと一致するか確認する。

過去のAssistants APIや古いAgent Builderの記述は、現行導線と混ぜない。新規設計ではResponses API / Agents SDKの現行Docsを優先し、移行記事は移行理由と差分の説明に限定する。