ツール

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

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

OpenAI がホストするツール – OpenAI サーバー上でモデルとともに実行されます。 (Web 検索、ファイル検索、Code Interpreter、画像生成、ツール検索)
組み込み実行ツール – SDK が提供し、モデルの外部で実行されるツールです。 (コンピュータ操作と apply_patch はローカルで実行され、shell はローカルまたはホストされたコンテナで実行できます)
関数ツール – 任意のローカル関数を JSON Schema でラップし、LLM から呼び出せるようにします。
Agents as tools – エージェント全体を呼び出し可能なツールとして公開します。
MCP サーバー – Model Context Protocol サーバーをローカルまたはリモートで接続します。
サンドボックス機能 – ワークスペース単位の shell、ファイルシステム、スキル、メモリ、圧縮ツールを SandboxAgent に接続します。
実験的機能：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 を実行します。

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`、`searchContentTypes`、`imageSettings` など、JS で扱いやすいオプションです。
`fileSearchTool(ids, options?)`	1 つ以上のベクトルストア ID を第 1 引数として受け取り、さらに `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 のツールペイロードに対応付けます。画像検索結果をリクエストするには、webSearchTool({ searchContentTypes }) に 'image' を含めます。正の数の画像をリクエストするには imageSettings.maxResults を使用し、利用可能な場合にキャプションをリクエストするには imageSettings.caption を使用します。searchContentTypes に 'image' が含まれている場合、SDK は元の Web 検索結果をリクエストし、返された画像 URL とメタデータを Web 検索呼び出し項目の providerData.results で公開します。

完全なツールスキーマと、ランキングオプションやセマンティックフィルターなどの高度なオプションについては、公式の OpenAI ツールガイドを参照してください。画像結果のフィールドについては、公式の Web 検索ガイドを参照してください。現在の組み込みツール検索フローと利用可能なモデルについては、公式のツール検索ガイドを参照してください。モデルのサポートとワイヤーレベルの動作については、公式のプログラムによるツール呼び出しガイドを参照してください。

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'
containerId により既存のコンテナを再利用する type: 'container_reference'

ホストされた 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() ヘルパーを使用すると、あらゆる 関数をツールに変換できます。

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 Schema はワイヤー契約のみを記述します。
`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 を使用します。ランナーは、現在のターンでモデルから参照できるツールセットを準備するときに、この述語を評価します。

isEnabled は、ツールの引数またはアクセス対象のリソースに依存する認可を置き換えるものではありません。述語は、モデルがそれらの引数を生成する前に実行されるためです。引数単位およびリソース単位の認可は execute 内で実施するか、必要に応じてツール入力ガードレールと承認を追加してください。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 Schema ツール

無効または部分的な入力をモデルに推測させる必要がある場合は、元の JSON Schema を使用するときに strict モードを無効にできます。

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 ループが必要です。
1 つの名前空間には、即時メンバーと遅延メンバーを混在させられます。即時メンバーはツール検索なしで引き続き呼び出せますが、同じ名前空間内の遅延メンバーはオンデマンドで読み込まれます。
ツールの検出結果は検索を実行したエージェントに属し、ハンドオフによって引き継がれません。実行グラフ内でエージェント名が一意である場合、SDK は history または Session の再生を通じて、同じ論理エージェントの検出結果を保持します。所有者が不明または曖昧な場合は再検索が必要になるため、永続化された検出結果を再構築後も維持する必要がある場合は、エージェントに一意の名前を付けてください。
遅延関数ツールと toolNamespace() は Responses 専用です。Chat Completions では拒否され、AI SDK アダプターも Responses の遅延ツール読み込みフローをサポートしていません。

4. Agents as tools

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

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

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 は次の処理を行います。

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

エージェントがツールとして実行される場合、Agents SDK は 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 Schema をネストされた実行に含めます。
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(...) ハンドラーを指定すると、Agents-as-tools は自動的にストリーミングモードで実行されます。どちらも指定しなければ、非ストリーミングフローのままです。
ハンドラーは並列に呼び出されるため、低速な onStream コールバックが on(...) ハンドラーをブロックすることはありません。その逆も同様です。
モデルのツール呼び出しによってツールが呼び出された場合は toolCallId が提供されます。直接の invoke() 呼び出しやプロバイダー固有の挙動によっては、省略される場合があります。

5. MCP サーバー

Model Context Protocol (MCP) サーバーを介してツールを公開し、エージェントに接続できます。たとえば、MCPServerStdio を使用して stdio 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

クイックスタート：

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 は、最新のスレッド ID を runContext.context から読み取り、そこへ保存します。これは、アプリケーション状態でターンをまたいで再利用する場合に役立ちます。
スレッド ID の優先順位：ツール呼び出しの threadId（スキーマに含まれる場合）が最優先で、次に実行コンテキストのスレッド ID、最後に codexTool({ threadId }) が使用されます。
実行コンテキストキー：name: 'codex' ではデフォルトで codexThreadId になり、name: 'engineer' のような名前では codexThreadId_<suffix> になります（正規化後は codex_engineer）。
可変コンテキストの要件：useRunContextThreadId を有効にする場合は、可変オブジェクトまたは Map を run(..., { context }) として渡します。
命名：ツール名は codex 名前空間に正規化されます（engineer は codex_engineer になります）。同じエージェント内で重複する Codex ツール名は拒否されます。
ストリーミング：onStream は Codex イベント（推論、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映するため、進行状況をログ記録またはトレースできます。
出力：ツールの実行結果には response、usage、threadId が含まれ、Codex のトークン使用量は RunContext に記録されます。
構造：outputSchema には、記述子、JSON Schema オブジェクト、または Zod オブジェクトを指定できます。JSON オブジェクトスキーマでは、additionalProperties を false にする必要があります。

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

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 つの手順があります。

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

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

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

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

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

structured outputs は、失敗時の処理も変更します。

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

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

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

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

ツール使用時の動作

モデルにツールを使用させるタイミングと方法（modelSettings.toolChoice、toolUseBehavior など）の制御については、エージェントを参照してください。

ベストプラクティス

短く明確な説明 – ツールが 何をするか、および いつ使用するか を説明します。
入力の検証 – 可能な限り、Zod またはサポートされる Standard Schema の値を使用して厳密な JSON 検証を行います。
エラーハンドラーでの副作用の回避 – errorFunction は例外をスローせず、役立つ文字列を返すようにします。
ツールごとに 1 つの責務 – 小さく構成可能なツールにより、モデルの推論が向上します。

ツールを持つエージェントの定義と toolUseBehavior の制御については、エージェント
Agents as tools とハンドオフの使い分けについては、エージェントオーケストレーション
実行フロー、ストリーミング、会話状態については、エージェントの実行
ホストされた OpenAI モデルの設定と Responses トランスポートの選択については、モデル
ツールの入力または出力の検証については、ガードレール
tool() と各種組み込みツール（Hosted）型の詳細については、TypeDoc リファレンスを参照してください。

ツール