ツール

ツールはエージェントに行動をとらせるためのものです。データ取得、外部 API 呼び出し、コード実行、さらにはコンピュータの使用まで可能にします。JavaScript/TypeScript SDK は次の 6 つのカテゴリーに対応しています:

OpenAI がホストするツール – モデルと同じ OpenAI のサーバー上で実行されます（Web 検索、ファイル検索、Code Interpreter、画像生成）
ローカル組み込みツール – あなたの環境で実行されます（コンピュータ操作、shell、apply_patch）
関数ツール – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします
Agents as tools – エージェント全体を呼び出し可能なツールとして公開します
MCP サーバー – Model context protocol のサーバー（ローカルまたはリモート）を接続します
実験的: Codex ツール – Codex SDK を関数ツールとしてラップし、ワークスペース対応タスクを実行します

1. Hosted tools (OpenAI Responses API)

OpenAIResponsesModel を使用すると、以下の組み込みツールを追加できます:

ツール	Type string	目的
Web search	`'web_search'`	インターネット検索
File / retrieval search	`'file_search'`	OpenAI がホストするベクトルストアへのクエリ
Code Interpreter	`'code_interpreter'`	サンドボックス環境でコードを実行
Image generation	`'image_generation'`	テキストに基づく画像生成

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

const agent = new Agent({
  name: 'Travel assistant',
  tools: [webSearchTool(), fileSearchTool('VS_ID')],
});

パラメーターの詳細は OpenAI Responses API と一致します。rankingOptions やセマンティックフィルタなどの高度なオプションは公式ドキュメントを参照してください。

2. Local built-in tools

ローカル組み込みツールはあなたの環境で実行され、実装の提供が必要です:

コンピュータ操作 – Computer インターフェースを実装して computerTool() に渡す
Shell – Shell インターフェースを実装して shellTool() に渡す
Apply patch – Editor インターフェースを実装して applyPatchTool() に渡す

これらのツールはローカルで実行され、OpenAI によってホストされるものではありません。ランタイムでファイル、ターミナル、GUI オートメーションに直接アクセスする必要がある場合に使用します。ツール呼び出しは OpenAI モデルのレスポンスによって要求されますが、実行はあなたのアプリケーションがローカルで行います。

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',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});

void agent;

3. Function tools

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 スキーマまたは元の JSON スキーマオブジェクトのいずれか。Zod のパラメーターは自動的に strict モードを有効化
`strict`	いいえ	`true`（デフォルト）の場合、引数がバリデーションに失敗すると SDK はモデルエラーを返します。あいまいなマッチングには `false` を設定
`execute`	はい	`(args, context) => string \| unknown \| Promise<...>` – ビジネスロジック。文字列以外の出力はモデル向けにシリアライズ。第 2 引数として任意で `RunContext` を受け取る
`errorFunction`	いいえ	内部エラーをユーザー向け文字列に変換するカスタムハンドラー `(context, error) => string`
`needsApproval`	いいえ	実行前に人間の承認を要求します。詳しくは人間の介入（HITL）を参照
`isEnabled`	いいえ	実行ごとに条件付きでツールを公開。boolean または述語を受け付ける
`inputGuardrails`	いいえ	ツール実行前に走るガードレール。拒否や例外が可能。詳しくはガードレールを参照
`outputGuardrails`	いいえ	ツール実行後に走るガードレール。拒否や例外が可能。詳しくはガードレールを参照

非 strict な JSON スキーマツール

無効または不完全な入力をモデルに推測させたい場合は、元の JSON スキーマ使用時に 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;
  },
});

4. Agents as tools

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

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 はデフォルト設定でランナーを作成し、関数の実行内でそのランナーを使ってエージェントを実行します。runConfig や runOptions のプロパティを指定したい場合は、asTool() に渡してランナーの動作をカスタマイズできます。

また、asTool() のオプションでエージェントツールに needsApproval と isEnabled を設定し、Human in the loop（人間の介入）フローや条件付き公開に統合できます。

agent.asTool() の構造化入力に関する高度なオプション:

inputBuilder: 構造化ツール引数をネストしたエージェント入力ペイロードにマッピング
includeInputSchema: 強力なスキーマ認識のために、ネストした実行に入力 JSON スキーマを含める
resumeState: ネストしたシリアライズ済み RunState を再開する際のコンテキスト再調整戦略を制御

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

エージェントツールはネストした実行のすべてのイベントをアプリにストリーミングできます。ツールの構築方法に合ったフックスタイルを選んでください:

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 servers

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

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

const server = new MCPServerStdio({
  fullCommand: 'npx -y @modelcontextprotocol/server-filesystem ./sample_files',
});

await server.connect();

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

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

6. Experimental: Codex tool

@openai/agents-extensions/experimental/codex は codexTool() を提供します。これはモデルのツールコールを Codex SDK にルーティングし、エージェントがワークスペーススコープのタスク（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.2-codex',
        networkAccessEnabled: true,
        webSearchEnabled: false,
      },
    }),
  ],
});

知っておくべきこと:

認証: CODEX_API_KEY（推奨）または OPENAI_API_KEY を指定、もしくは codexOptions.apiKey を渡す
入力: 厳密なスキーマ — inputs は少なくとも { type: 'text', text } または { type: 'local_image', path } を 1 つ含む必要がある
セーフティ: sandboxMode と workingDirectory を組み合わせて使用。ディレクトリが Git リポジトリでない場合は skipGitRepoCheck を設定
スレッディング: useRunContextThreadId: true は runContext.context に最新の thread id を読み書きし、アプリ状態でのターン間再利用に有用
Thread ID の優先順位: ツールコールの threadId（スキーマに含めている場合）が最優先、その次にランコンテキストの thread 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 必須

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

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.2-codex',
        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;

void threadId;

Tool use behavior

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

ベストプラクティス

短く明確な説明 – ツールが「何を」「いつ」行うかを記述
入力を検証 – 可能な限り Zod スキーマで厳密な JSON 検証を行う
エラーハンドラーで副作用を避ける – errorFunction は有用な文字列を返し、例外を投げない
ツールは単一責務に – 小さく合成しやすいツールはモデルの推論精度を高める

次のステップ

ツール使用の強制について学ぶ
ツールの入力や出力を検証するためにガードレールを追加
tool() と各種ホスト型ツールタイプの TypeDoc リファレンスを参照