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

OpenAI版 LLM・Agent Engineering Guide

基準日: 2026-09-05 対象: OpenAI API / Responses API / Agents SDK / MCP / Codexの設計境界 正本: このMarkdown。iPhone向けHTMLはこの原稿から生成する。

この資料の立場

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

章中のラベル:

• 公式仕様: 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・実行ポリシーで制御する。

1.4 Structured Outputs

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

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
  }
}

Part 1 Sources

• 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なデータとして扱う。人間に読める要約の完全な代用品とは限らない。重要な決定事項、テスト結果、証拠、未解決点、ユーザー承認をアプリケーション側の状態として保存する。

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 Retry、timeout、side effect

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

MAX_TURNS = 8

input_items = [{"role": "user", "content": user_text}]

for _ in range(MAX_TURNS):
    response = client.responses.create(
        model=MODEL_NAME,
        input=input_items,
        tools=TOOLS,
    )
    input_items += response.output

    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        return response.output_text

    for call in calls:
        args = parse_json(call.arguments)
        if not valid_schema(call.name, args):
            output = {"error": "invalid_arguments"}
        elif not allowed(call.name, args):
            output = {"error": "approval_required"}
        else:
            output = execute_with_timeout(call.name, args, seconds=20)
        input_items.append({
            "type": "function_call_output",
            "call_id": call.call_id,
            "output": json_encode(output),
        })

raise RuntimeError("max turns reached")

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を公開Internet上のMCP実装として説明する。

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設定を別々に読む。

Part 4 Sources

• 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とは別である。

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

8.2 Claudeとの違い

Claude CodeはCLAUDE.mdを読み、OpenAI CodexはAGENTS.mdを読み込む。プロジェクトが両方を使う場合、別ファイルを重複管理するか、一方から他方を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 / ClaudeのSkillとの対応

OpenAI APIのSkillsはHosted environmentへのupload・attachというAPI面を持つ。CodexやClaude CodeでのSkillは、各製品のlocal/project/plugin discovery、slash invocation、permission、Context loadingを持ち得る。同じSKILL.mdという名前でも、runtime、frontmatter fields、distribution、実行権限を現行Docsで確認する。

Part 9 Sources

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

Part 10 — Hooks

10.1 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.2 Deterministic処理の置き場所

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

Part 10 Sources

• 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を並列に起動し結果を一つに集約する仕組みとして説明する。各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はMain model前、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と同じ誤りを持つ場合、評価が高くても実際の品質は上がらない。

Part 13 Sources

• 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のいずれかを選ぶ。

def run_responses_agent(client, user_text, max_turns=8):
    input_items = [{"role": "user", "content": user_text}]

    for _ in range(max_turns):
        response = client.responses.create(
            model=MODEL_NAME,
            instructions=DEVELOPER_INSTRUCTIONS,
            input=input_items,
            tools=TOOLS,
        )
        input_items.extend(response.output)

        calls = [
            item for item in response.output
            if item.type == "function_call"
        ]
        if not calls:
            return response.output_text

        for call in calls:
            args = decode_json(call.arguments)
            if not schema_valid(call.name, args):
                result = {"error": "invalid_arguments"}
            elif not policy_allows(call.name, args):
                result = {"error": "approval_required"}
            else:
                result = execute(call.name, args, timeout=20)
            input_items.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": encode_json(result),
            })

    return {"status": "incomplete", "reason": "max_turns"}

実際の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を優先し、移行記事は移行理由と差分の説明に限定する。