ツール

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

組み込みツール（Hosted） – OpenAI のサーバー上でモデルと一緒に動作
(Web 検索、ファイル検索、コンピュータ操作、Code Interpreter、画像生成)
関数ツール – 任意のローカル関数を JSON スキーマでラップし、LLM が呼び出せるようにする
エージェントをツールとして公開 – エージェント全体を呼び出し可能なツールとして公開

1. 組み込みツール（Hosted）

OpenAIResponsesModel を使用する際、以下のビルトインツールを追加できます。

ツール	type 文字列	目的
Web 検索	`'web_search'`	インターネット検索
ファイル / 検索	`'file_search'`	OpenAI がホストするベクトルストアの検索
コンピュータ操作	`'computer'`	GUI 操作を自動化
Code Interpreter	`'code_interpreter'`	サンドボックス環境でコードを実行
画像生成	`'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 を使うと自動的に strict モードが有効になります
`strict`	いいえ	`true`（デフォルト）で、引数が検証に失敗するとモデルエラーを返します。曖昧入力を許可する場合は `false` に設定
`execute`	はい	`(args, context) => string \| Promise<string>` – ビジネスロジック。第 2 引数は省略可能で `RunContext`
`errorFunction`	いいえ	内部エラーをユーザー可視の文字列へ変換するカスタムハンドラー `(context, error) => string`

非 strict JSON スキーマツール

無効または部分的な入力をモデルに推測させたい場合は、raw 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 パラメーター 1 つだけの関数ツールを作成
ツール呼び出し時にその入力でサブエージェントを実行
最後のメッセージ、または customOutputExtractor が抽出した出力を返却

ツール使用の挙動

モデルにツール使用を必須化する方法などはエージェントを参照してください (tool_choice、toolUseBehavior など)。

ベストプラクティス

短く明確な説明 – ツールが 何を行い、いつ使うか を具体的に記述
入力を検証 – 可能なら Zod スキーマで厳格な JSON 検証を実施
エラーハンドラーで副作用を避ける – errorFunction は有益な文字列を返すだけにし、例外を投げない
ツールは単一責務 – 小さく再利用可能なツールはモデルの推論を助けます

次のステップ

ツール使用の強制を学習
ガードレールを追加してツールの入力・出力を検証
tool() と各種組み込みツール型の TypeDoc リファレンスを掘り下げる