ツール
ツールは、エージェント が アクションを実行する ことを可能にします。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用までできます。JavaScript/TypeScript SDK は次の 4 つのカテゴリーをサポートします:
- 組み込みツール(Hosted) – OpenAI の サーバー 上でモデルと並行して実行 (Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)
- 関数ツール – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする
- ツールとしてのエージェント – エージェント 全体を呼び出し可能なツールとして公開
- ローカル MCP サーバー – お使いのマシン上で動作する Model context protocol サーバーを接続
1. 組み込みツール(Hosted)
Section titled “1. 組み込みツール(Hosted)”OpenAIResponsesModel を使う場合、以下の組み込みツールを追加できます:
| ツール | 型文字列 | 目的 |
|---|---|---|
| Web search | 'web_search' | インターネット検索 |
| File / retrieval search | 'file_search' | OpenAI 上でホストされる ベクトルストア のクエリ |
| Computer use | 'computer' | GUI 操作を自動化 |
| 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. 関数ツール
Section titled “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.`; },});オプションリファレンス
Section titled “オプションリファレンス”| 項目 | 必須 | 説明 |
|---|---|---|
name | いいえ | デフォルトは関数名(例: get_weather) |
description | はい | LLM に表示される、明確で人間に読みやすい説明 |
parameters | はい | Zod スキーマまたは 元 の JSON スキーマオブジェクトのいずれか。Zod パラメーターは自動的に strict モードを有効化 |
strict | いいえ | true(デフォルト)の場合、引数が検証に通らなければ SDK はモデルエラーを返す。あいまいなマッチングにするには false に設定 |
execute | はい | (args, context) => string | Promise<string>– ビジネスロジック本体。2 番目の引数は省略可能で、RunContext |
errorFunction | いいえ | 内部エラーを ユーザー に見える文字列へ変換するためのカスタムハンドラー (context, error) => string |
非 strict な JSON スキーマツール
Section titled “非 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. ツールとしてのエージェント
Section titled “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 の動作をカスタマイズできます。
4. MCP サーバー
Section titled “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 連携 を参照してください。
ツール使用時の挙動
Section titled “ツール使用時の挙動”モデルがツールをいつどのように使用するべきか(tool_choice、toolUseBehavior など)の制御については、エージェント を参照してください。
ベストプラクティス
Section titled “ベストプラクティス”- 短く明確な説明 – ツールが何をするか、いつ使うかを記述
- 入力を検証 – 可能な限り Zod スキーマで厳格な JSON 検証を実施
- エラーハンドラーで副作用を避ける –
errorFunctionは有用な文字列を返すべきで、throw しない - ツールは単一責務 – 小さく合成しやすいツールはモデルの推論を向上