コンテンツにスキップ

ツール

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

  1. 組み込みツール(Hosted) – OpenAI の サーバー 上でモデルと並行して実行 (Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)
  2. 関数ツール – 任意のローカル関数を JSON スキーマでラップして LLM が呼び出せるようにする
  3. ツールとしてのエージェント – エージェント 全体を呼び出し可能なツールとして公開
  4. ローカル MCP サーバー – お使いのマシン上で動作する Model context protocol サーバーを接続

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

ツール型文字列目的
Web search'web_search'インターネット検索
File / retrieval search'file_search'OpenAI 上でホストされる ベクトルストア のクエリ
Computer use'computer'GUI 操作を自動化
Code Interpreter'code_interpreter'サンドボックス環境でコードを実行
Image generation'image_generation'テキストに基づいて画像を生成
組み込みツール(Hosted)
import { Agent, webSearchTool, fileSearchTool } from '@openai/agents';
const agent = new Agent({
name: 'Travel assistant',
tools: [webSearchTool(), fileSearchTool('VS_ID')],
});

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


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 スキーマまたは 元 の JSON スキーマオブジェクトのいずれか。Zod パラメーターは自動的に strict モードを有効化
strictいいえtrue(デフォルト)の場合、引数が検証に通らなければ SDK はモデルエラーを返す。あいまいなマッチングにするには false に設定
executeはい(args, context) => string | Promise<string>– ビジネスロジック本体。2 番目の引数は省略可能で、RunContext
errorFunctionいいえ内部エラーを ユーザー に見える文字列へ変換するためのカスタムハンドラー (context, error) => string

無効または部分的な入力をモデルに推測させたい場合は、元 の 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;
},
});

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 を作成し、関数の実行内でそのエージェントを実行します。runConfigrunOptions のプロパティを指定したい場合は、asTool() メソッドに渡して runner の動作をカスタマイズできます。


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

ローカル 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_choicetoolUseBehavior など)の制御については、エージェント を参照してください。


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