ツール

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

どの agent にそのタスクを持たせるべきかが分かり、そこに機能を持たせたい段階になったら、このページを エージェント の後に読んでください。委譲パターンをまだ検討中であれば、エージェントオーケストレーション を参照してください。

1. OpenAI がホストするツール – OpenAI サーバー上でモデルと並行して実行されます。 (Web 検索、ファイル検索、Code Interpreter、画像生成、tool search)
2. 組み込み実行ツール – SDK が提供する、モデルの外側で実行されるツールです。 (computer use と apply_patch はローカルで実行され、shell はローカルまたは Hosted コンテナで実行できます)
3. 関数ツール – 任意のローカル関数を JSON schema でラップし、LLM が呼び出せるようにします。
4. Agents as tools – Agent 全体を呼び出し可能なツールとして公開します。
5. MCP サーバー – Model context protocol サーバー（ローカルまたはリモート）を接続します。
6. Experimental: Codex tool – Codex SDK を関数ツールとしてラップし、workspace を認識したタスクを実行します。

---

ツールカテゴリー

このガイドの残りでは、まず各ツールカテゴリーを説明し、その後でツール選択とプロンプト設計に関する横断的な指針をまとめます。

1. Hosted ツール（OpenAI Responses API）

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

Tool	Type string	Purpose
Web 検索	'web_search'	インターネット検索
ファイル / 検索	'file_search'	OpenAI 上でホストされるベクトルストアにクエリを実行します
Code Interpreter	'code_interpreter'	サンドボックス環境でコードを実行します
画像生成	'image_generation'	テキストに基づいて画像を生成します
Tool search	'tool_search'	遅延読み込みされた関数ツール、名前空間、または検索可能な MCP ツールを実行時に読み込みます

Hosted tools

import {
  Agent,
  codeInterpreterTool,
  fileSearchTool,
  imageGenerationTool,
  webSearchTool,
} from '@openai/agents';

const agent = new Agent({
  name: 'Travel assistant',
  tools: [
    webSearchTool({ searchContextSize: 'medium' }),
    fileSearchTool('VS_ID', { maxNumResults: 3 }),
    codeInterpreterTool(),
    imageGenerationTool({ size: '1024x1024' }),
  ],
});

SDK は Hosted ツール定義を返すヘルパー関数を提供しています。

Helper function	Notes
webSearchTool(options?)	searchContextSize、userLocation、filters.allowedDomains などの JS 向けオプション
fileSearchTool(ids, options?)	最初の引数として 1 つ以上のベクトルストア ID を受け取り、maxNumResults、includeSearchResults、rankingOptions、フィルターなどのオプションも指定できます
codeInterpreterTool(options?)	container が指定されていない場合は、自動管理されるコンテナをデフォルトで使用します
imageGenerationTool(options?)	model、size、quality、background、inputFidelity、inputImageMask、moderation、outputCompression、partialImages、出力形式などの画像生成設定をサポートします
toolSearchTool(options?)	組み込みの tool_search ヘルパーを追加します。deferLoading: true を設定した遅延関数ツールまたは Hosted MCP ツールと組み合わせて使います。デフォルトでは Hosted 実行をサポートし、execution: 'client' と execute を指定するとクライアント実行も可能です

これらのヘルパーは、JavaScript / TypeScript 向けのオプション名を、基盤となる OpenAI Responses API のツールペイロードにマッピングします。完全なツール schema や、ranking options や semantic filters といった高度なオプションについては、公式の OpenAI tools guide を参照してください。現在の組み込み tool-search フローと対応モデルについては、公式の Tool search guide を参照してください。

---

2. 組み込み実行ツール

これらのツールは SDK に組み込まれていますが、実行はモデルのレスポンス自体の外側で行われます。

• コンピュータ操作 – Computer インターフェースを実装し、それを computerTool() に渡します。これは常に、あなたが提供するローカルの Computer 実装に対して実行されます
• Shell – ローカルの Shell 実装を提供するか、shellTool({ environment }) で Hosted コンテナ環境を設定します
• Apply patch – Editor インターフェースを実装し、それを applyPatchTool() に渡します。これは常に、あなたが提供するローカルの Editor 実装に対して実行されます

ツール呼び出し自体は引き続きモデルによって要求されますが、実際の作業はあなたのアプリケーション、または設定済みの実行環境が行います。

Built-in execution tools

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',
  model: 'gpt-5.4',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});

Computer ツールの詳細

computerTool() は以下のいずれかを受け取ります。

• 具体的な Computer インスタンス
• 実行ごとに Computer を作成する initializer 関数
• 実行スコープのセットアップとクリーンアップが必要な場合の { create, dispose } を持つ provider オブジェクト

OpenAI の現在の computer-use パスを使うには、gpt-5.4 などの computer 対応モデルを設定してください。リクエストモデルが明示的な場合、SDK は GA の組み込み computer ツール形式を送信します。一方、有効なモデルが保存済みプロンプトや他の古い統合から来ている場合、明示的に modelSettings.toolChoice: 'computer' で GA パスを選ばない限り、SDK は互換性のために従来の computer_use_preview wire 形式を維持します。

GA の computer 呼び出しには、単一の computer_call 内にバッチ化された actions[] を含めることができます。SDK はそれらを順番に実行し、各アクションに対して needsApproval を評価し、最終的なスクリーンショットをツール出力として返します。interruption.rawItem から承認 UI を構築する場合は、存在すれば actions を読み、従来の preview 項目に対しては action にフォールバックしてください。

影響の大きい computer アクションをユーザー確認で一時停止したい場合は needsApproval を使い、computer 呼び出しに対して報告された保留中の safety checks を承認または拒否したい場合は onSafetyCheck を使います。モデル側のガイダンスと移行の詳細については、公式の OpenAI computer use guide と、その migration note を参照してください。

Shell ツールの詳細

shellTool() には 2 つのモードがあります。

• ローカルモード: shell を指定し、必要に応じて environment: { type: 'local', skills } に加えて、自動承認処理のための needsApproval と onApproval を指定します
• Hosted コンテナモード: type: 'container_auto' または type: 'container_reference' を持つ environment を指定します

ローカルモードでは、environment.skills によって、name、description、ファイルシステム上の path でローカル skill をマウントできます。

Hosted コンテナモードでは、以下のいずれかで shellTool({ environment }) を設定します。

• 実行用の管理コンテナを作成する type: 'container_auto'
• containerId で既存コンテナを再利用する type: 'container_reference'

Hosted の container_auto 環境は以下をサポートします。

• domainSecrets を含む allowlist を含めた networkPolicy
• アップロード済みファイルをマウントするための fileIds
• コンテナサイズ指定のための memoryLimit
• skill_reference またはインライン zip バンドルによる skills

Hosted shell 環境では、実行がローカルプロセスではなく Hosted コンテナ環境で行われるため、shell、needsApproval、onApproval は受け付けません。

エンドツーエンドの使用例は、examples/tools/local-shell.ts、examples/tools/container-shell-skill-ref.ts、examples/tools/container-shell-inline-skill.ts を参照してください。

Apply-patch ツールの詳細

applyPatchTool() は、shellTool() のローカル承認フローを踏襲しています。ファイル編集の前に一時停止したい場合は needsApproval を使い、アプリレベルのコールバックで自動承認または拒否したい場合は onApproval を使います。

---

3. 関数ツール

tool() ヘルパーを使うと、任意の 関数をツールに変換できます。

Function tool with Zod parameters

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

オプション一覧

Field	Required	Description
name	No	デフォルトでは関数名（例: get_weather）が使われます
description	Yes	LLM に表示される、明確で人が読める説明
parameters	Yes	Zod schema または生の JSON schema オブジェクト。Zod parameters では自動的に strict モードが有効になります
strict	No	true（デフォルト）の場合、引数の検証に失敗すると SDK はモデルエラーを返します。あいまい一致を許容するには false にします
execute	Yes	(args, context, details) => string | unknown | Promise<...> – あなたのビジネスロジック。文字列以外の出力はモデル向けにシリアライズされます。context は省略可能な RunContext で、details には toolCall、resumeState、signal などのメタデータが含まれます
errorFunction	No	内部エラーをユーザー向け文字列に変換するカスタムハンドラー (context, error) => string
timeoutMs	No	呼び出しごとのタイムアウト（ミリ秒）。0 より大きく、2147483647 以下である必要があります
timeoutBehavior	No	タイムアウトモード: error_as_result（デフォルト）はモデルに見えるタイムアウトメッセージを返し、raise_exception は ToolTimeoutError を投げます
timeoutErrorFunction	No	timeoutBehavior が error_as_result のときのタイムアウト出力用カスタムハンドラー (context, timeoutError) => string
needsApproval	No	実行前に人間の承認を要求します。人間の介入（HITL） を参照してください
isEnabled	No	実行ごとにツールを条件付きで公開します。真偽値または predicate を受け付けます
inputGuardrails	No	ツール実行前に動作するガードレール。拒否または例外送出が可能です。ガードレール を参照してください
outputGuardrails	No	ツール実行後に動作するガードレール。拒否または例外送出が可能です。ガードレール を参照してください

関数ツールのタイムアウト

各関数ツール呼び出しの上限時間を設定するには timeoutMs を使います。

• timeoutBehavior: 'error_as_result'（デフォルト）は、Tool '<name>' timed out after <timeoutMs>ms. をモデルに返します
• timeoutBehavior: 'raise_exception' は ToolTimeoutError を投げます。これは エージェントの実行 における実行例外の一部として捕捉できます
• timeoutErrorFunction を使うと、error_as_result モードでタイムアウト文言をカスタマイズできます
• タイムアウト時には details.signal が中断されるため、長時間実行するツールもキャンセルを監視していればすぐに停止できます

関数ツールを直接呼び出す場合は、通常の agent 実行と同じタイムアウト動作を適用するために invokeFunctionTool を使ってください。

Non‑strict JSON‑schema ツール

無効または部分的な入力をモデルに 推測 させたい場合は、生の JSON schema を使う際に strict モードを無効にできます。

Non-strict JSON schema tools

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

Tool search による遅延ツール読み込み

Tool search を使うと、すべての schema を最初から送信する代わりに、モデルは実行時に必要なツール定義だけを読み込めます。SDK では、これは遅延トップレベル関数ツール、toolNamespace() グループ、および deferLoading: true で設定された Hosted MCP ツールを扱う方法です。

Tool search は、Responses API で対応している GPT-5.4 以降のモデルリリースでのみ使用してください。

Deferred tool loading with tool search

import { Agent, tool, toolNamespace, toolSearchTool } from '@openai/agents';
import { z } from 'zod';

const customerIdParams = z.object({
  customerId: z.string().describe('The customer identifier to look up.'),
});

// Keep a standalone deferred tool at the top level when it represents a
// single searchable capability that does not need a shared namespace.
const shippingLookup = tool({
  name: 'get_shipping_eta',
  description: 'Look up a shipment ETA by customer identifier.',
  parameters: customerIdParams,
  deferLoading: true,
  async execute({ customerId }) {
    return {
      customerId,
      eta: '2026-03-07',
      carrier: 'Priority Express',
    };
  },
});

// Group related tools into a namespace when one domain description should
// cover several deferred tools and let tool search load them together.
const crmTools = toolNamespace({
  name: 'crm',
  description: 'CRM tools for customer profile lookups.',
  tools: [
    tool({
      name: 'get_customer_profile',
      description: 'Fetch a basic customer profile.',
      parameters: customerIdParams,
      deferLoading: true,
      async execute({ customerId }) {
        return {
          customerId,
          tier: 'enterprise',
        };
      },
    }),
  ],
});

const agent = new Agent({
  name: 'Operations assistant',
  model: 'gpt-5.4',
  // Mixing namespaced and top-level deferred tools in one request is supported.
  tools: [shippingLookup, ...crmTools, toolSearchTool()],
});

この例では意図的に両方のスタイルを混在させています。

• shippingLookup は、単独で検索可能な 1 つの機能であるためトップレベルのままです
• crmTools は、関連する CRM ツールが 1 つの上位ラベルと説明を共有するため toolNamespace() を使っています
• 同じリクエスト内で名前空間付きとトップレベルの遅延ツールを混在させることはサポートされています。tool search は crm のような名前空間パスと get_shipping_eta のようなトップレベルパスの両方を読み込めます

Tool search を使う場合は、以下に注意してください。

• 各遅延関数ツールに deferLoading: true を設定する
• 複数の関連ツールが 1 つのドメイン説明を共有し、グループとして読み込まれるべき場合は toolNamespace({ name, description, tools }) を使う
• 単独の独立した機能であり、ツール名自体が良い検索対象になる場合はトップレベルのままにする
• 遅延関数ツールまたは Hosted MCP ツールのいずれかが deferLoading: true を使う場合は、同じ tools 配列に toolSearchTool() を追加する
• modelSettings.toolChoice は 'auto' のままにする。SDK は組み込み tool_search ツールや、名前指定された遅延関数ツールの強制を拒否します
• Hosted 実行がデフォルトです。toolSearchTool({ execution: 'client', execute }) を設定した場合、標準の run() ループがサポートするのは組み込みの { paths: string[] } クライアントクエリ形式のみであり、カスタムのクライアント側 schema を使うには独自の Responses ループが必要です
• 名前空間には即時メンバーと遅延メンバーを混在させられます。即時メンバーは tool search なしでも呼び出し可能であり、同じ名前空間内の遅延メンバーは必要時に読み込まれます
• 遅延関数ツールと toolNamespace() は Responses 専用です。Chat Completions では拒否され、AI SDK アダプターも遅延 Responses ツール読み込みフローをサポートしていません

---

4. Agents as tools

会話を完全に handoff せずに、ある Agent に別の Agent を 補助 させたいことがあります。その場合は agent.asTool() を使います。

agent.asTool() と handoff() のどちらを使うべきかをまだ検討中なら、エージェント と エージェントオーケストレーション のパターン比較を参照してください。

Agents as tools

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 パラメーターを持つ関数ツールを作成する
• ツールが呼び出されたときに、その入力で sub‑agent を実行する
• 最後のメッセージ、または customOutputExtractor によって抽出された出力を返す

agent をツールとして実行すると、Agents SDK はデフォルト設定で runner を作成し、関数実行の中でその runner により agent を実行します。runConfig や runOptions のプロパティを渡したい場合は、それらを asTool() メソッドに渡して runner の動作をカスタマイズできます。

また、asTool() オプションで agent tool に needsApproval と isEnabled を設定することで、人間の介入フローや条件付きツール公開と統合することもできます。

customOutputExtractor の内部では、result.agentToolInvocation を使って現在の Agent.asTool() 呼び出しを確認できます。このコールバックでは結果は常に Agent.asTool() 由来なので、agentToolInvocation は常に定義されており、toolName、toolCallId、toolArguments を参照できます。通常のアプリコンテキストと toolInput には result.runContext を使ってください。このメタデータは現在のネストされた呼び出しスコープに限定されており、RunState にシリアライズされません。

Read agent tool invocation metadata

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Handle billing questions and subscription changes.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  customOutputExtractor(result) {
    console.log('tool', result.agentToolInvocation.toolName);
    // Direct invoke() calls may not have a model-generated tool call id.
    console.log('call', result.agentToolInvocation.toolCallId);
    console.log('args', result.agentToolInvocation.toolArguments);

    return String(result.finalOutput ?? '');
  },
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

agent.asTool() の高度な structured-input オプション:

• inputBuilder: 構造化されたツール引数を、ネストされた agent 入力ペイロードにマッピングします
• includeInputSchema: より強い schema 認識動作のために、ネストされた実行に入力 JSON schema を含めます
• resumeState: ネストされたシリアライズ済み RunState を再開する際のコンテキスト統合戦略を制御します。'merge'（デフォルト）は live の承認 / コンテキスト状態をシリアライズ済み状態にマージし、'replace' は代わりに現在の実行コンテキストを使い、'preferSerialized' はシリアライズ済みコンテキストを変更せずそのまま再開します

Agent ツールからのストリーミングイベント

Agent ツールは、ネストされた実行イベントをすべてアプリにストリーミングで返せます。ツールの構築方法に応じて、適したフックスタイルを選んでください。

Streaming agent tools

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

---

5. MCP サーバー

Model Context Protocol (MCP) サーバーを通じてツールを公開し、それを agent に接続できます。たとえば、MCPServerStdio を使って stdio MCP サーバーを起動し、接続できます。

Local MCP server

import { Agent, MCPServerStdio } from '@openai/agents';

const server = new MCPServerStdio({
  fullCommand: 'pnpm exec mcp-server-filesystem ./sample_files',
});

await server.connect();

const agent = new Agent({
  name: 'Assistant',
  mcpServers: [server],
});

完全な例は filesystem-example.ts を参照してください。また、MCP サーバーツール統合の包括的なガイドを探している場合は、詳細について MCP 連携 を参照してください。複数サーバーを管理する場合（または部分的な失敗がある場合）は、connectMcpServers と MCP 連携 のライフサイクル指針を使ってください。

---

6. Experimental: Codex tool

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

まず依存関係をインストールします。

npm install @openai/agents-extensions @openai/codex-sdk

クイックスタート:

Experimental Codex tool

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.4',
        networkAccessEnabled: true,
        webSearchEnabled: false,
      },
    }),
  ],
});

知っておくべきこと:

• 認証: CODEX_API_KEY（推奨）または OPENAI_API_KEY を指定するか、codexOptions.apiKey を渡します
• 入力: strict schema です。inputs には少なくとも 1 つの { type: 'text', text } または { type: 'local_image', path } を含める必要があります
• 安全性: sandboxMode と workingDirectory を組み合わせて使います。ディレクトリが Git リポジトリでない場合は skipGitRepoCheck を設定してください
• スレッド管理: useRunContextThreadId: true は最新の thread id を runContext.context に読み書きします。これはアプリ状態でのターン間再利用に便利です
• Thread ID の優先順位: ツール呼び出しの threadId（schema に含まれている場合）が最優先で、その次に run-context の thread id、最後に codexTool({ threadId }) です
• Run context キー: name: 'codex' の場合はデフォルトで codexThreadId、name: 'engineer' のような名前では codexThreadId_<suffix>（正規化後は codex_engineer）です
• 可変コンテキスト要件: useRunContextThreadId を有効にする場合、run(..., { context }) には可変オブジェクトまたは Map を渡してください
• 命名: ツール名は codex 名前空間に正規化されます（engineer は codex_engineer になります）。また、同一 agent 内で重複する Codex ツール名は拒否されます
• ストリーミング: onStream は Codex イベント（reasoning、コマンド実行、MCP ツール呼び出し、ファイル変更、Web 検索）を反映するため、進行状況のログ出力やトレースが可能です
• 出力: ツール結果には response、usage、threadId が含まれ、Codex のトークン使用量は RunContext に記録されます
• 構造: outputSchema には descriptor、JSON schema オブジェクト、または Zod オブジェクトを使えます。JSON object schema では additionalProperties は false である必要があります

run-context の thread 再利用例:

Codex run-context thread reuse

import { Agent, run } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

// Derived from codexTool({ name: 'engineer' }) when runContextThreadIdKey is omitted.
type ExampleContext = {
  codexThreadId_engineer?: string;
};

const agent = new Agent<ExampleContext>({
  name: 'Codex assistant',
  instructions: 'Use the codex tool for workspace tasks.',
  tools: [
    codexTool({
      // `name` is optional for a single Codex tool.
      // We set it so the run-context key is tool-specific and to avoid collisions when adding more Codex tools.
      name: 'engineer',
      // Reuse the same Codex thread across runs that share this context object.
      useRunContextThreadId: true,
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        approvalPolicy: 'never',
      },
    }),
  ],
});

// The default key for useRunContextThreadId with name=engineer is codexThreadId_engineer.
const context: ExampleContext = {};

// First turn creates (or resumes) a Codex thread and stores the thread ID in context.
await run(agent, 'Inspect src/tool.ts and summarize it.', { context });
// Second turn reuses the same thread because it shares the same context object.
await run(agent, 'Now list refactoring opportunities.', { context });

const threadId = context.codexThreadId_engineer;

---

ツール戦略とベストプラクティス

ツール利用の挙動

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

---

ベストプラクティス

• 短く明示的な説明 – ツールが 何をするか と いつ使うべきか を説明する
• 入力の検証 – 可能な限り Zod schema を使って厳密な JSON 検証を行う
• エラーハンドラーで副作用を避ける – errorFunction は例外を投げるのではなく、役立つ文字列を返すべきです
• ツールごとに単一責務 – 小さく組み合わせやすいツールの方が、モデルの推論がうまくいきます

---

関連ガイド

• ツールを持つ agent の定義と toolUseBehavior の制御については エージェント
• agents as tools と handoffs のどちらを使うべきかの判断については エージェントオーケストレーション
• 実行フロー、ストリーミング、会話状態については エージェントの実行
• Hosted OpenAI モデル設定と Responses の転送方式については モデル
• ツールの入力や出力の検証については ガードレール
• tool() と各種 Hosted ツール型の TypeDoc リファレンスも参照してください