ツール

ツールはエージェントが 行動する ための手段です。データの取得、外部 API の呼び出し、コードの実行、さらにはコンピュータの使用までできます。JavaScript/TypeScript SDK は 6 つのカテゴリーをサポートします:

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

1. 組み込みツール（Hosted）（OpenAI Responses API）

OpenAIResponsesModel を使用する場合、次の組み込みツールを追加できます:

ツール	型文字列	目的
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. ローカル組み込みツール

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

コンピュータ操作 – Computer インターフェースを実装し、computerTool() に渡す
シェル – Shell インターフェースを実装し、shellTool() に渡す
パッチ適用 – 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. 関数ツール

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 \| unknown \| Promise<...>` – ビジネスロジック。文字列以外の出力はモデル向けにシリアライズ。2 番目の引数は任意で `RunContext`
`errorFunction`	いいえ	内部エラーをユーザー向けの文字列に変換するためのカスタムハンドラー `(context, error) => string`
`needsApproval`	いいえ	実行前に人間の承認を要求します。詳細は人間の介入（HITL）を参照
`isEnabled`	いいえ	実行ごとに条件付きでツールを公開。真偽値または述語を受け付けます
`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 はデフォルト設定で runner を作成し、関数実行内でそのエージェントを実行します。runConfig や runOptions のプロパティを指定したい場合は、asTool() に渡して runner の動作をカスタマイズできます。

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

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

エージェントツールは入れ子のすべての実行イベントをアプリにストリーミングできます。ツールの構築方法に合うフックスタイルを選びます:

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(...) ハンドラーを指定すると、自動的に streaming モードで agent-as-tool が実行されます。指定しない場合は非 streaming の経路のまま
ハンドラーは並行で呼び出され、遅い onStream コールバックが on(...) ハンドラーをブロックすることはありません（逆も同様）
モデルのツール呼び出し経由でツールが起動された場合は toolCallId が提供されます。invoke() の直接呼び出しやプロバイダーの仕様によっては省略されることがあります

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

6. 実験的: Codex ツール

@openai/agents-extensions/experimental/codex は codexTool() を提供します。これは関数ツールで、モデルのツール呼び出しを Codex SDK にルーティングし、エージェントがワークスペーススコープのタスク（シェル、ファイル編集、MCP ツール）を自律的に実行できるようにします。この機能は実験的で変更される可能性があります。

クイックスタート:

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,
      },
      persistSession: true,
    }),
  ],
});

知っておくべきこと:

認証: CODEX_API_KEY（推奨）または OPENAI_API_KEY を指定、もしくは codexOptions.apiKey を渡す
入力: 厳密なスキーマ — inputs には少なくとも 1 つの { type: 'text', text } または { type: 'local_image', path } が必要
セーフティ: sandboxMode と workingDirectory を組み合わせる。ディレクトリが Git リポジトリでない場合は skipGitRepoCheck を設定
振る舞い: persistSession: true は単一の Codex スレッドを再利用し、その threadId を返します。再開可能な作業のために公開できます
ストリーミング: onStream は Codex のイベント（推論、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映し、進捗のログやトレーシングに利用可能
出力: ツール結果には response、usage、threadId が含まれ、Codex のトークン使用量は RunContext に記録
構造: 型付き出力が必要な場合、outputSchema はターンごとの構造化された Codex 応答を強制

ツール使用の挙動

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

ベストプラクティス

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

次のステップ

エージェントの強制的なツール使用について学ぶ
ツールの入力や出力を検証するためにガードレールを追加
tool() と各種組み込みツール（Hosted）タイプの TypeDoc リファレンスを参照

ツール