ツール

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

OpenAI がホストするツール – モデルと同じ OpenAI サーバー上で実行します（Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成）
関数ツール – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにします
エージェントをツールとして – エージェント全体を呼び出し可能なツールとして公開します
ローカル MCP サーバー – ローカルで動作する Model Context Protocol サーバーを接続します

1. OpenAI がホストするツール

OpenAIResponsesModel を使う場合、以下の組み込みツールを追加できます。

ツール	Type string	目的
Web search	`'web_search'`	インターネット検索
File / retrieval search	`'file_search'`	OpenAI 上でホストするベクトルストアを検索
Computer use	`'computer'`	GUI 操作を自動化
Shell	`'shell'`	ホスト上でシェルコマンドを実行
Apply patch	`'apply_patch'`	ローカルファイルに V4A diff を適用
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. 関数ツール

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 parameters を使うと自動的に strict モードが有効になります
`strict`	いいえ	`true`（デフォルト）の場合、引数の検証に失敗すると SDK はモデルエラーを返します。あいまいなマッチングが必要な場合は `false` に設定
`execute`	はい	`(args, context) => string \| Promise<string>` – ビジネスロジック。2 つ目の引数は省略可能で、`RunContext` です
`errorFunction`	いいえ	内部エラーをユーザーに見える文字列に変換するためのカスタムハンドラー `(context, error) => string`

非 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;
  },
});

3. エージェントをツールとして

会話全体を完全にハンドオフせずに、あるエージェントに別のエージェントを 支援する 形で使いたい場合があります。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 はデフォルト設定の runner を作成し、その関数実行内でエージェントを実行します。runConfig や runOptions のプロパティを指定したい場合は、asTool() メソッドに渡して runner の動作をカスタマイズできます。

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

エージェントツールは、ネストされた実行イベントをすべてアプリにストリーミングできます。ツールの組み立て方に合うフックスタイルを選びます。

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() の直接呼び出しやプロバイダーの仕様により省略される場合があります

4. MCP サーバー

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 連携を参照してください。

ツール使用の挙動

モデルがいつどのようにツールを使用すべきか（tool_choice、toolUseBehavior など）については、エージェントを参照してください。

ベストプラクティス

短く明示的な説明 – ツールが 何をするか と いつ使うか を記述
入力の検証 – 可能な限り Zod スキーマで厳密な JSON 検証を行う
エラーハンドラーで副作用を避ける – errorFunction は有用な文字列を返し、throw しない
ツールは単一責任 – 小さく合成可能なツールはモデルの推論を向上

次のステップ

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