ツール

ツールを使用すると、エージェントは アクションを実行 できます。たとえば、データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用も可能です。JavaScript/TypeScript SDK は、次の 7 つのカテゴリーをサポートしています。

どのエージェントにタスクを担当させるかが決まり、そのエージェントに機能を与える場合は、エージェントの次にこのページをお読みください。委任パターンを検討中の場合は、エージェントオーケストレーションを参照してください。

1. OpenAI がホストするツール – OpenAI サーバー上でモデルとともに実行されます。(Web 検索、ファイル検索、code interpreter、画像生成、ツール検索)
2. 組み込み実行ツール – モデルの外部で実行される、SDK が提供するツールです。(コンピュータ操作と apply_patch はローカルで実行され、shell はローカルまたはホスト型コンテナで実行できます)
3. 関数ツール – 任意のローカル関数を JSON スキーマでラップし、LLM から呼び出せるようにします。
4. Agents as tools – エージェント全体を呼び出し可能なツールとして公開します。
5. MCP サーバー – Model Context Protocol サーバーをローカルまたはリモートで接続します。
6. サンドボックス機能 – ワークスペーススコープの shell、ファイルシステム、スキル、メモリ、またはコンパクションツールを SandboxAgent に接続します。
7. 実験的機能：Codex ツール – Codex SDK を関数ツールとしてラップし、ワークスペースを認識するタスクを実行します。

---

ツールのカテゴリー

このガイドでは、まず各ツールカテゴリーについて説明し、その後、カテゴリー横断のツール選択とプロンプト作成に関するガイダンスをまとめます。

1. 組み込みツール（Hosted）（OpenAI Responses API）

OpenAIResponsesModel を使用する場合、次の組み込みツールを追加できます。

ツール	型文字列	目的
Web 検索	'web_search'	インターネットを検索します。
ファイル／検索	'file_search'	OpenAI がホストするベクトルストアを検索します。
Code Interpreter	'code_interpreter'	サンドボックス環境でコードを実行します。
画像生成	'image_generation'	テキストに基づいて画像を生成します。
ツール検索	'tool_search'	遅延読み込みされる関数ツール、名前空間、または検索可能な MCP ツールを実行時に読み込みます。
プログラムによるツール呼び出し	'programmatic_tool_calling'	対象ツールを連携させる、モデル生成の JavaScript を実行します。

組み込みツール（Hosted）

import {
  Agent,
  codeInterpreterTool,
  fileSearchTool,
  imageGenerationTool,
  webSearchTool,
} from '@openai/agents';

const agent = new Agent({
  name: 'Travel assistant',
  tools: [
    webSearchTool({ searchContextSize: 'medium' }),
    fileSearchTool('VS_ID', { maxNumResults: 3 }),
    codeInterpreterTool(),
    imageGenerationTool({ size: '1024x1024' }),
  ],
});

SDK は、組み込みツールの定義を返すヘルパー関数を提供します。

ヘルパー関数	注記
webSearchTool(options?)	searchContextSize、userLocation、filters.allowedDomains などの JS 向けオプションです。
fileSearchTool(ids, options?)	最初の引数として 1 つ以上のベクトルストア ID を受け取り、さらに maxNumResults、includeSearchResults、rankingOptions、フィルターなどのオプションを指定できます。
codeInterpreterTool(options?)	container が指定されていない場合、デフォルトで自動管理コンテナを使用します。
imageGenerationTool(options?)	model、size、quality、background、inputFidelity、inputImageMask、moderation、outputCompression、partialImages、出力形式などの画像生成設定をサポートします。
toolSearchTool(options?)	組み込みの tool_search ヘルパーを追加します。deferLoading: true を設定した遅延読み込みの関数ツールまたはホスト型 MCP ツールと組み合わせて使用します。デフォルトではホスト型実行をサポートし、execution: 'client' と execute を指定すればクライアント実行もサポートします。
programmaticToolCallingTool()	プログラムによるツール呼び出しを有効にします。allowedCallers に 'programmatic' が含まれるツールと組み合わせて使用します。

これらのヘルパーは、JavaScript/TypeScript 向けのオプション名を、基盤となる OpenAI Responses API のツールペイロードにマッピングします。ツールスキーマの全体とランキングオプションやセマンティックフィルターなどの高度なオプションについては、公式の OpenAI ツールガイドを参照してください。現在の組み込みツール検索フローと利用可能なモデルについては、公式のツール検索ガイドを参照してください。モデルのサポート状況とワイヤレベルの動作については、公式のプログラムによるツール呼び出しガイドを参照してください。

---

2. 組み込み実行ツール

これらのツールは SDK に組み込まれていますが、実行はモデルのレスポンス自体の外部で行われます。

• コンピュータ操作 – Computer インターフェースを実装し、computerTool() に渡します。これは、提供したローカルの Computer 実装に対して常に実行されます。
• Shell – ローカルの Shell 実装を提供するか、shellTool({ environment }) でホスト型コンテナ環境を設定します。
• パッチの適用 – Editor インターフェースを実装し、applyPatchTool() に渡します。これは、提供したローカルの Editor 実装に対して常に実行されます。
• サンドボックスの shell およびファイルシステムツール – アクションをサンドボックスワークスペース内で実行する必要がある場合は、SandboxAgent で shell()、filesystem()、skills()、memory()、または compaction() を使用します。

ツール呼び出しは引き続きモデルによってリクエストされますが、実際の処理はアプリケーションまたは設定済みの実行環境が行います。

サンドボックス機能のツールは、プロセス全体で利用される組み込みツールとは異なります。これらは、現在の SandboxAgent の実行におけるアクティブなサンドボックスセッションに紐づきます。ツールをアプリケーションプロセスではなく、エージェントの分離されたワークスペースで動作させる場合は、クイックスタートを使用してください。

組み込み実行ツール

import {
  Agent,
  applyPatchTool,
  computerTool,
  shellTool,
  Computer,
  Editor,
  Shell,
} from '@openai/agents';

const computer: Computer = {
  environment: 'browser',
  dimensions: [1024, 768],
  screenshot: async () => '',
  click: async () => {},
  doubleClick: async () => {},
  scroll: async () => {},
  type: async () => {},
  wait: async () => {},
  move: async () => {},
  keypress: async () => {},
  drag: async () => {},
};

const shell: Shell = {
  run: async () => ({
    output: [
      {
        stdout: '',
        stderr: '',
        outcome: { type: 'exit', exitCode: 0 },
      },
    ],
  }),
};

const editor: Editor = {
  createFile: async () => ({ status: 'completed' }),
  updateFile: async () => ({ status: 'completed' }),
  deleteFile: async () => ({ status: 'completed' }),
};

const agent = new Agent({
  name: 'Local tools agent',
  model: 'gpt-5.4',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});

コンピュータツールの詳細

computerTool() は、次のいずれかを受け取ります。

• 具体的な Computer インスタンス
• 実行ごとに Computer を作成する初期化関数
• 実行スコープのセットアップと後処理が必要な場合に使用する { create, dispose } を持つプロバイダーオブジェクト

OpenAI の現在のコンピュータ操作パスを使用するには、gpt-5.4 などのコンピュータ操作対応モデルを設定します。リクエストモデルが明示されている場合、SDK は GA 版の組み込み computer ツール形式を送信します。有効なモデルが保存済みプロンプトや以前の別の連携から取得される場合、modelSettings.toolChoice: 'computer' で GA パスを明示的に選択しない限り、SDK は互換性のために従来の computer_use_preview ワイヤ形式を維持します。

GA のコンピュータ呼び出しでは、1 回の computer_call に一括された actions[] を含めることができます。SDK はそれらを順番に実行し、各アクションに対して needsApproval を評価し、最終的なスクリーンショットをツール出力として返します。interruption.rawItem から承認 UI を構築する場合、actions が存在すればそれを読み取り、従来のプレビュー項目では action にフォールバックしてください。

影響の大きいコンピュータ操作をユーザーの確認のために一時停止する場合は needsApproval を使用します。コンピュータ呼び出しについて報告された保留中の安全性チェックを承認または拒否する場合は、onSafetyCheck を使用します。モデル側のガイダンスと移行の詳細については、公式の OpenAI コンピュータ操作ガイドとその移行に関する注記を参照してください。

Shell ツールの詳細

shellTool() には 2 つのモードがあります。

• ローカルモード：shell を指定します。必要に応じて environment: { type: 'local', skills } を指定し、自動承認処理のために needsApproval と onApproval も指定できます。
• ホスト型コンテナモード：type: 'container_auto' または type: 'container_reference' を持つ environment を指定します。

ローカルモードでは、environment.skills を使用して、name、description、ファイルシステムの path によってローカルスキルをマウントできます。

ホスト型コンテナモードでは、次のいずれかを使用して shellTool({ environment }) を設定します。

• type: 'container_auto'：実行用の管理対象コンテナを作成します。
• type: 'container_reference'：containerId によって既存のコンテナを再利用します。

ホスト型の container_auto 環境は、次をサポートします。

• domainSecrets を含む許可リストなどの networkPolicy
• アップロード済みファイルをマウントするための fileIds
• コンテナサイズを設定するための memoryLimit
• skill_reference またはインラインの zip バンドルによる skills

ホスト型 shell 環境では、実行がローカルプロセスではなくホスト型コンテナ環境で行われるため、shell、needsApproval、onApproval は指定できません。

一連の使用方法については、examples/tools/local-shell.ts、examples/tools/container-shell-skill-ref.ts、examples/tools/container-shell-inline-skill.ts を参照してください。

パッチ適用ツールの詳細

applyPatchTool() は、shellTool() のローカル承認フローと同様に動作します。ファイル編集前に一時停止するには needsApproval を使用し、アプリケーションレベルのコールバックで自動承認または拒否するには onApproval を使用します。

---

3. 関数ツール

tool() ヘルパーを使用すると、任意の 関数をツールに変換できます。

Zod パラメーターを使用する関数ツール

import { tool } from '@openai/agents';
import { z } from 'zod';

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

オプションリファレンス

フィールド	必須	説明
name	いいえ	デフォルトは関数名です（例：get_weather）。
description	はい	LLM に表示される、明確で人間が読みやすい説明です。
parameters	はい	Zod スキーマ、サポート対象の Standard Schema 値、または元の JSON Schema オブジェクトです。検証スキーマでは strict モードが自動的に有効になります。
strict	いいえ	true（デフォルト）の場合、引数が検証に合格しなければ SDK はモデルエラーを返します。あいまい一致を許可するには false に設定します。
execute	はい	(args, context, details) => string | unknown | Promise<...> – ビジネスロジックです。文字列以外の出力はモデル向けにシリアライズされます。context はオプションの RunContext で、details には toolCall、resumeState、signal などのメタデータが含まれます。
allowedCallers	いいえ	ツールを直接、プログラムから、またはその両方から呼び出せるかを制御する、Responses 専用の空でないリストです。'direct'、'programmatic'、またはその両方を使用します。
outputSchema	いいえ	ツール実行結果に使用する Responses 専用のスキーマです。Zod スキーマは execute の戻り値の型を制約し、実行時の結果を検証および変換します。元の JSON スキーマはワイヤ契約のみを記述します。
errorFunction	いいえ	内部エラーをモデルから見える結果に変換するためのカスタムハンドラー (context, error, details) => result です。outputSchema が設定されている場合、結果はそのスキーマを満たす必要があります。デフォルトハンドラーは無効になっているため、元のエラーが再スローされます。
timeoutMs	いいえ	呼び出しごとのタイムアウト時間（ミリ秒）です。0 より大きく、2147483647 以下である必要があります。
timeoutBehavior	いいえ	タイムアウトモードです。error_as_result はモデルから見える結果を返し、raise_exception は ToolTimeoutError をスローします。デフォルトは、outputSchema がない場合は error_as_result、ある場合は raise_exception です。
timeoutErrorFunction	いいえ	error_as_result で使用するカスタムハンドラー (context, timeoutError, details) => result です。outputSchema が設定されている場合、このハンドラーは必須であり、その結果はスキーマを満たす必要があります。
customDataExtractor	いいえ	SDK 専用メタデータを、生成される RunToolCallOutputItem.customData に追加するためのコールバック (context) => Record<string, unknown> | null | undefined です。このデータはモデルには返されません。
needsApproval	いいえ	実行前に人間の承認を要求します。人間の介入（HITL）を参照してください。
isEnabled	いいえ	実行ごとにツールを条件付きで公開します。真偽値または述語を受け取ります。
inputGuardrails	いいえ	ツールの実行前に動作し、拒否または例外のスローが可能なガードレールです。ガードレールを参照してください。
outputGuardrails	いいえ	ツールの実行後に動作し、拒否または例外のスローが可能なガードレールです。ガードレールを参照してください。

条件付きのツール可用性

リクエストスコープでの機能の表示、環境固有の可用性、機能フラグ、実験には isEnabled を使用します。Runner は、現在のターンでモデルに表示するツールセットを準備するときに述語を評価します。

isEnabled は、ツール引数やアクセス対象のリソースに依存する認可の代わりにはなりません。述語はモデルがそれらの引数を生成する前に実行されるためです。引数およびリソースレベルの認可は execute 内で適用してください。必要に応じて、ガードレールや人間の介入（HITL）も追加してください。MCP サーバーは、保護対象の操作を自ら認可する必要があります。関数ツール、ローカル MCP ツール、ハンドオフに 1 つのアプリケーションポリシーを適用するパターンについては、コンテキスト管理を参照してください。

サポート対象の Standard Schema パラメーターは、モデル向けに JSON Schema に変換され、execute の実行前にローカルで検証されます。ライブラリによる変換やデフォルト値を含む検証出力型が、推論される execute 引数の型になります。Valibot のコード例と現在の制限については、スキーマ検証を参照してください。

SDK 専用カスタムデータ

ツール実行結果の隣に、レンダラー向けヒント、内部 ID、その他の JSON 互換メタデータが必要な場合は、customDataExtractor を使用します。コールバックは、実行コンテキスト、ツール定義、モデルのツール呼び出し、解析済み入力、出力、複製された元の出力項目を受け取ります。返されたデータは RunToolCallOutputItem.customData と RunState に保存されますが、history とモデルの再実行からは除外されます。

関数ツールのタイムアウト

各関数ツール呼び出しの実行時間を制限するには、timeoutMs を使用します。

• timeoutBehavior: 'error_as_result' は、Tool '<name>' timed out after <timeoutMs>ms. をモデルに返します。outputSchema が設定されていない場合のデフォルトです。
• timeoutBehavior: 'raise_exception' は ToolTimeoutError をスローします。これは、エージェントの実行における例外としてキャッチできます。
• timeoutErrorFunction を使用すると、error_as_result モードのタイムアウトテキストをカスタマイズできます。
• outputSchema が設定されている場合、デフォルトは raise_exception に変わります。error_as_result を使用するには、スキーマ互換の値を返す timeoutErrorFunction が必要です。
• タイムアウト時には details.signal が中断されるため、長時間実行されるツールがキャンセルを監視していれば、すぐに停止できます。

関数ツールを直接呼び出す場合、通常のエージェント実行と同じタイムアウト動作を適用するには、invokeFunctionTool を使用します。

非 strict の JSON スキーマツール

元の JSON スキーマを使用するときに、無効または不完全な入力をモデルに 推測 させる必要がある場合は、strict モードを無効にできます。

非 strict の JSON スキーマツール

import { tool } from '@openai/agents';

interface LooseToolInput {
  text: string;
}

const looseTool = tool({
  description: 'Echo input; be forgiving about typos',
  strict: false,
  parameters: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text'],
    additionalProperties: true,
  },
  execute: async (input) => {
    // because strict is false we need to do our own verification
    if (typeof input !== 'object' || input === null || !('text' in input)) {
      return 'Invalid input. Please try again';
    }
    return (input as LooseToolInput).text;
  },
});

ツール検索による遅延ツール読み込み

ツール検索を使用すると、すべてのスキーマを事前に送信する代わりに、モデルは実行時に必要なツール定義だけを読み込めます。SDK では、遅延読み込みされるトップレベルの関数ツール、toolNamespace() グループ、deferLoading: true が設定されたホスト型 MCP ツールをこの方法で扱います。

ツール検索は、Responses API でサポートされる GPT-5.4 以降のモデルリリースでのみ使用してください。

ツール検索による遅延ツール読み込み

import { Agent, tool, toolNamespace, toolSearchTool } from '@openai/agents';
import { z } from 'zod';

const customerIdParams = z.object({
  customerId: z.string().describe('The customer identifier to look up.'),
});

// Keep a standalone deferred tool at the top level when it represents a
// single searchable capability that does not need a shared namespace.
const shippingLookup = tool({
  name: 'get_shipping_eta',
  description: 'Look up a shipment ETA by customer identifier.',
  parameters: customerIdParams,
  deferLoading: true,
  async execute({ customerId }) {
    return {
      customerId,
      eta: '2026-03-07',
      carrier: 'Priority Express',
    };
  },
});

// Group related tools into a namespace when one domain description should
// cover several deferred tools and let tool search load them together.
const crmTools = toolNamespace({
  name: 'crm',
  description: 'CRM tools for customer profile lookups.',
  tools: [
    tool({
      name: 'get_customer_profile',
      description: 'Fetch a basic customer profile.',
      parameters: customerIdParams,
      deferLoading: true,
      async execute({ customerId }) {
        return {
          customerId,
          tier: 'enterprise',
        };
      },
    }),
  ],
});

const agent = new Agent({
  name: 'Operations assistant',
  model: 'gpt-5.4',
  // Mixing namespaced and top-level deferred tools in one request is supported.
  tools: [shippingLookup, ...crmTools, toolSearchTool()],
});

このコード例では、意図的に両方の形式を組み合わせています。

• shippingLookup は単独の検索可能な機能であるため、トップレベルのままです。
• crmTools は、関連する CRM ツールが 1 つの上位レベルのラベルと説明を共有するため、toolNamespace() を使用します。
• 同じリクエスト内で、名前空間付きツールとトップレベルの遅延ツールを組み合わせることができます。ツール検索では、crm などの名前空間パスと、get_shipping_eta などのトップレベルパスの両方を読み込めます。

ツール検索を使用する場合は、次の点に注意してください。

• 遅延読み込みする各関数ツールに deferLoading: true を設定します。
• 複数の関連ツールで 1 つのドメイン説明を共有し、グループとして読み込む場合は、toolNamespace({ name, description, tools }) を使用します。
• 単独の独立した機能で、ツール名自体が適切な検索対象になる場合は、ツールをトップレベルに配置します。
• 遅延読み込みの関数ツールまたはホスト型 MCP ツールで deferLoading: true を使用する場合は、同じ tools 配列に toolSearchTool() を追加します。
• modelSettings.toolChoice は 'auto' のままにします。SDK は、組み込みの tool_search ツールまたは遅延読み込みの関数ツールを名前で強制的に指定する設定を拒否します。
• デフォルトはホスト型実行です。toolSearchTool({ execution: 'client', execute }) を設定した場合、標準の run() ループがサポートするクライアントクエリ形式は、組み込みの { paths: string[] } のみです。カスタムのクライアント側スキーマには、独自の Responses ループが必要です。
• 名前空間には、即時読み込みと遅延読み込みのメンバーを混在させることができます。即時読み込みのメンバーはツール検索なしで呼び出せますが、同じ名前空間内の遅延読み込みメンバーは必要に応じて読み込まれます。
• 遅延読み込みの関数ツールと toolNamespace() は Responses 専用です。Chat Completions では拒否され、AI SDK アダプターは Responses の遅延ツール読み込みフローをサポートしません。

---

4. Agents as tools

会話を完全にハンドオフせずに、あるエージェントから別のエージェントに 支援 させたい場合があります。その場合は agent.asTool() を使用します。

agent.asTool() と handoff() のどちらを使用するか検討中の場合は、エージェントとエージェントオーケストレーションでパターンを比較してください。

Agents as tools

import { Agent } from '@openai/agents';

const summarizer = new Agent({
  name: 'Summarizer',
  instructions: 'Generate a concise summary of the supplied text.',
});

const summarizerTool = summarizer.asTool({
  toolName: 'summarize_text',
  toolDescription: 'Generate a concise summary of the supplied text.',
});

const mainAgent = new Agent({
  name: 'Research assistant',
  tools: [summarizerTool],
});

内部では、SDK が次の処理を行います。

• 単一の input パラメーターを持つ関数ツールを作成します。
• ツールが呼び出されたときに、その入力でサブエージェントを実行します。
• 最後のメッセージ、または customOutputExtractor で抽出された出力を返します。

エージェントがツールとして実行される場合、Agents SDK は Runner を作成し、その Runner を使用して関数ツール呼び出し内でエージェントを実行します。ネストされた Runner を設定するには runConfig を渡し、ネストされた実行を設定するには runOptions を渡します。

asTool() のオプションを使用して、エージェントツールに needsApproval と isEnabled を設定し、Human in the loop (人間の介入)フローや条件付きのツール可用性と連携することもできます。

customOutputExtractor 内では、result.agentToolInvocation を使用して現在の Agent.asTool() 呼び出しを確認します。このコールバックでは、実行結果は常に Agent.asTool() から取得されるため、agentToolInvocation は必ず定義され、toolName、toolCallId、toolArguments を公開します。アプリケーションコンテキストには result.runContext.context を使用します。デフォルトの単一 input スキーマでは、result.runContext.toolInput は未定義です。代わりに、呼び出し引数を読み取るには result.agentToolInvocation.toolArguments を使用します。カスタムの parameters または inputBuilder を設定すると、result.runContext.toolInput に取得された構造化引数が含まれます。agentToolInvocation のメタデータは現在のネストされた呼び出しに限定され、RunState にはシリアライズされません。

エージェントツール呼び出しのメタデータの読み取り

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Handle billing questions and subscription changes.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  customOutputExtractor(result) {
    console.log('tool', result.agentToolInvocation.toolName);
    // Direct invoke() calls may not have a model-generated tool call id.
    console.log('call', result.agentToolInvocation.toolCallId);
    console.log('args', result.agentToolInvocation.toolArguments);

    return String(result.finalOutput ?? '');
  },
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

agent.asTool() の高度な構造化入力オプションは次のとおりです。

• parameters：デフォルトの { input: string } 形式を、Zod スキーマ、サポート対象の Standard Schema 値、または元の JSON Schema に置き換えます。
• inputBuilder：構造化されたツール引数を、ネストされたエージェントの入力ペイロードにマッピングします。
• includeInputSchema：スキーマをより強く認識した動作のために、ネストされた実行に入力 JSON スキーマを含めます。
• resumeState：シリアライズ済みのネストされた RunState を再開するときのコンテキスト調整方法を制御します。'merge'（デフォルト）は現在の承認／コンテキスト状態をシリアライズ済み状態にマージし、'replace' は代わりに現在の実行コンテキストを使用し、'preferSerialized' はシリアライズ済みコンテキストを変更せずに再開します。

エージェントツールからのストリーミングイベント

エージェントツールは、ネストされた実行のすべてのイベントをアプリケーションにストリーミングできます。ツールの構築方法に合うフック形式を選択してください。

エージェントツールのストリーミング

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Answer billing questions and compute simple charges.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  // onStream: simplest catch-all when you define the tool inline.
  onStream: (event) => {
    console.log(`[onStream] ${event.event.type}`, event);
  },
});

// on(eventName) lets you subscribe selectively (or use '*' for all).
billingTool.on('run_item_stream_event', (event) => {
  console.log('[on run_item_stream_event]', event);
});
billingTool.on('raw_model_stream_event', (event) => {
  console.log('[on raw_model_stream_event]', event);
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

• イベントタイプは RunStreamEvent['type'] と一致します：raw_model_stream_event、run_item_stream_event、agent_updated_stream_event
• onStream は最もシンプルな「すべてを受け取る」方法であり、ツールをインラインで宣言する場合（tools: [agent.asTool({ onStream })]）に適しています。イベントごとのルーティングが不要な場合に使用します。
• on(eventName, handler) を使用すると、選択的に、または '*' ですべてのイベントを購読できます。より細かな処理が必要な場合や、作成後にリスナーを追加する場合に適しています。
• onStream またはいずれかの on(...) ハンドラーを指定すると、ツールとしてのエージェントは自動的にストリーミングモードで実行されます。どちらも指定しない場合は、非ストリーミングパスが使用されます。
• ハンドラーは並列で呼び出されるため、遅い onStream コールバックが on(...) ハンドラーをブロックすることはありません。その逆も同様です。
• モデルのツール呼び出しによってツールが呼び出された場合は、toolCallId が提供されます。直接の invoke() 呼び出しやプロバイダー固有の動作では、省略されることがあります。

---

5. MCP サーバー

Model Context Protocol (MCP) サーバーを介してツールを公開し、エージェントに接続できます。たとえば、MCPServerStdio を使用して stdio MCP サーバーを起動し、接続できます。

ローカル MCP サーバー

import { Agent, MCPServerStdio } from '@openai/agents';

const server = new MCPServerStdio({
  fullCommand: 'pnpm exec mcp-server-filesystem ./sample_files',
});

await server.connect();

const agent = new Agent({
  name: 'Assistant',
  mcpServers: [server],
});

完全なコード例については、filesystem-example.ts を参照してください。MCP サーバーツール連携の包括的なガイドを探している場合は、MCP 連携を参照してください。複数のサーバーや部分的な障害を管理する場合は、connectMcpServers と MCP 連携のライフサイクルガイダンスを使用してください。

---

6. 実験的機能：Codex ツール

@openai/agents-extensions/experimental/codex は、モデルのツール呼び出しを Codex SDK にルーティングする関数ツール codexTool() を提供します。これにより、エージェントはワークスペーススコープのタスク（shell、ファイル編集、MCP ツール）を自律的に実行できます。この機能は実験的であり、変更される可能性があります。

最初に依存関係をインストールします。

npm install @openai/agents-extensions @openai/codex-sdk

クイックスタート：

実験的な Codex ツール

import { Agent } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

export const codexAgent = new Agent({
  name: 'Codex Agent',
  instructions:
    'Use the codex tool to inspect the workspace and answer the question. When skill names, which usually start with `$`, are mentioned, you must rely on the codex tool to use the skill and answer the question.',
  tools: [
    codexTool({
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        networkAccessEnabled: true,
        webSearchEnabled: false,
      },
    }),
  ],
});

留意事項：

• 認証：CODEX_API_KEY（推奨）または OPENAI_API_KEY を指定するか、codexOptions.apiKey を渡します。
• 入力：strict スキーマです。inputs には、少なくとも 1 つの { type: 'text', text } または { type: 'local_image', path } を含める必要があります。
• 安全性：sandboxMode と workingDirectory を組み合わせて使用します。ディレクトリが Git リポジトリでない場合は、skipGitRepoCheck を設定します。
• スレッド処理：useRunContextThreadId: true は、runContext.context にある最新のスレッド ID を読み書きします。これは、アプリケーションの状態でターンをまたいで再利用する場合に便利です。
• スレッド ID の優先順位：ツール呼び出しの threadId（スキーマに含まれる場合）が最優先され、次に実行コンテキストのスレッド ID、最後に codexTool({ threadId }) が使用されます。
• 実行コンテキストキー：name: 'codex' の場合はデフォルトで codexThreadId、name: 'engineer' のような名前の場合は codexThreadId_<suffix> になります（正規化後は codex_engineer）。
• 可変コンテキストの要件：useRunContextThreadId が有効な場合、run(..., { context }) には可変オブジェクトまたは Map を渡します。
• 名前付け：ツール名は codex 名前空間に正規化されます（engineer は codex_engineer になります）。また、エージェント内で Codex ツール名が重複すると拒否されます。
• ストリーミング：onStream は Codex イベント（推論、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映するため、進捗をログまたはトレースできます。
• 出力：ツール実行結果には response、usage、threadId が含まれ、Codex のトークン使用量は RunContext に記録されます。
• 構造：outputSchema には、記述子、JSON スキーマオブジェクト、または Zod オブジェクトを指定できます。JSON オブジェクトスキーマでは、additionalProperties を false にする必要があります。

実行コンテキストのスレッド再利用のコード例：

Codex の実行コンテキストによるスレッド再利用

import { Agent, run } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

// Derived from codexTool({ name: 'engineer' }) when runContextThreadIdKey is omitted.
type ExampleContext = {
  codexThreadId_engineer?: string;
};

const agent = new Agent<ExampleContext>({
  name: 'Codex assistant',
  instructions: 'Use the codex tool for workspace tasks.',
  tools: [
    codexTool({
      // `name` is optional for a single Codex tool.
      // We set it so the run-context key is tool-specific and to avoid collisions when adding more Codex tools.
      name: 'engineer',
      // Reuse the same Codex thread across runs that share this context object.
      useRunContextThreadId: true,
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        approvalPolicy: 'never',
      },
    }),
  ],
});

// The default key for useRunContextThreadId with name=engineer is codexThreadId_engineer.
const context: ExampleContext = {};

// First turn creates (or resumes) a Codex thread and stores the thread ID in context.
await run(agent, 'Inspect src/tool.ts and summarize it.', { context });
// Second turn reuses the same thread because it shares the same context object.
await run(agent, 'Now list refactoring opportunities.', { context });

const threadId = context.codexThreadId_engineer;

---

プログラムによるツール呼び出し

プログラムによるツール呼び出しを使用すると、対応する Responses モデルが、ホスト型実行環境内で複数のツール呼び出しを連携させる JavaScript を生成できます。クライアント側で所有するツールは引き続きアプリケーションが実行するため、既存の検証、権限、承認、ガードレール、副作用はそのまま適用されます。

プログラムによるツール呼び出し

import { Agent, programmaticToolCallingTool, tool } from '@openai/agents';
import { z } from 'zod';

const getInventory = tool({
  name: 'get_inventory',
  description: 'Return inventory for a SKU.',
  parameters: z.object({ sku: z.string() }),
  allowedCallers: ['programmatic'],
  outputSchema: z.object({
    sku: z.string(),
    availableUnits: z.number(),
  }),
  async execute({ sku }) {
    return { sku, availableUnits: 42 };
  },
});

const getDemand = tool({
  name: 'get_demand',
  description: 'Return requested units for a SKU.',
  parameters: z.object({ sku: z.string() }),
  allowedCallers: ['programmatic'],
  outputSchema: z.object({
    sku: z.string(),
    requestedUnits: z.number(),
  }),
  async execute({ sku }) {
    return { sku, requestedUnits: 31 };
  },
});

const agent = new Agent({
  name: 'Inventory planner',
  model: 'gpt-5.6',
  instructions: `
Use Programmatic Tool Calling to fetch inventory and demand concurrently.
Return the source values and the calculated shortage in the final answer.
  `.trim(),
  tools: [getInventory, getDemand, programmaticToolCallingTool()],
});

セットアップは 2 つの部分で構成されます。

1. programmaticToolCallingTool() をエージェントに追加します。
2. 生成されたプログラムから呼び出せる各ツールに allowedCallers を設定します。

allowedCallers	動作
省略または ['direct']	モデルがツールを直接呼び出せます。
['programmatic']	生成されたプログラムだけがツールを呼び出せます。
['direct', 'programmatic']	モデルと生成されたプログラムのどちらからでもツールを呼び出せます。

SDK は、tool()、ローカルまたはホスト型の shellTool()、applyPatchTool()、hostedMcpTool()、codeInterpreterTool() で作成されたツールについて、プログラムからの呼び出しをサポートします。

SDK は、リクエストを送信する前に設定を検証します。プログラム専用ツールには programmaticToolCallingTool() が必要です。このヘルパーには、リクエストにツール検索または対象ツールを提供できる保存済みプロンプトが含まれていない限り、対象ツールが少なくとも 1 つ必要です。

関数ツールが構造化データを返す必要がある場合は、outputSchema を使用します。Zod スキーマは execute の戻り値の型を制約し、実行時の結果を検証および変換します。元の JSON スキーマはワイヤ契約を記述しますが、SDK 側での結果検証は追加しません。無効な Zod の結果は InvalidToolOutputError を発生させます。

Structured outputs により、エラー処理も変わります。

• デフォルトの errorFunction は無効になるため、実行エラーは再スローされます。カスタムハンドラーは、outputSchema と互換性のある値を返す必要があります。
• デフォルトのタイムアウト動作は 'raise_exception' になります。
• 'error_as_result' を使用するには、戻り値が outputSchema を満たす timeoutErrorFunction を指定します。
• 出力ガードレールによって置き換えられた値も、outputSchema を満たす必要があります。

プログラムによるツール呼び出しは Responses 専用です。Chat Completions、音声エージェント、AI SDK モデルアダプターでは、これらのオプションは拒否されます。対象ツールが遅延読み込みされる場合、後で生成されるプログラムから呼び出す前に、ツール検索でそのツールを読み込む必要があります。

完全なコード例については、examples/tools/programmatic-tool-calling.ts を参照してください。

---

ツール戦略とベストプラクティス

ツール使用時の動作

モデルがいつ、どのようにツールを使用する必要があるかを制御する方法（modelSettings.toolChoice、toolUseBehavior など）については、エージェントを参照してください。

---

ベストプラクティス

• 短く明示的な説明 – ツールが 何を行うか、いつ使用するか を説明します。
• 入力の検証 – 可能な限り、Zod またはサポート対象の Standard Schema 値を使用して厳格な JSON 検証を行います。
• エラーハンドラーでの副作用の回避 – errorFunction は例外をスローせず、有用な文字列を返すようにします。
• ツールごとに 1 つの役割 – 小さく組み合わせ可能なツールにすると、モデルの推論が向上します。

---

関連ガイド

• ツールを持つエージェントの定義と toolUseBehavior の制御については、エージェント
• Agents as tools とハンドオフのどちらを使用するかの判断については、エージェントオーケストレーション
• 実行フロー、ストリーミング、会話状態については、エージェントの実行
• OpenAI がホストするモデルの設定と Responses トランスポートの選択については、モデル
• ツールの入力または出力の検証については、ガードレール
• tool() と各種ホスト型ツールの型については、TypeDoc リファレンスを参照してください。