ツール

ツールを使用すると、エージェントはデータの取得、コードの実行、外部 API の呼び出し、さらにはコンピュータ操作などのアクションを実行できます。SDK は 5 つのカテゴリーをサポートしています。

• OpenAIがホストするツール: OpenAIサーバー上でモデルのために実行されます。
• ローカル／ランタイム実行ツール: ComputerTool と ApplyPatchTool は常にお使いの環境で実行され、ShellTool はローカルまたはホストされたコンテナで実行できます。
• FunctionTool インスタンス: 任意の Python 関数をツールとしてラップします。
• Agents as tools: 完全なハンドオフを行わずに、エージェントを呼び出し可能なツールとして公開します。
• 実験的機能: Codex ツール: ツール呼び出しから、ワークスペースにスコープされた Codex タスクを実行します。

ツールタイプの選択

このページをカタログとして使用し、制御するランタイムに該当するセクションに進んでください。

目的	参照先
OpenAIが管理するツール（Web 検索、ファイル検索、Code Interpreter、ホスト型 MCP、画像生成）の使用	ホスト型ツール
ツール検索を使用して、大規模なツール群の読み込みをランタイムまで延期	ホスト型ツール検索
生成された JavaScript から複数のツール呼び出しを調整	プログラムによるツール呼び出し
独自のプロセスまたは環境でツールを実行	ローカルランタイムツール
Python 関数をツールとしてラップ	関数ツール
ハンドオフせずに、あるエージェントから別のエージェントを呼び出し	Agents as tools
エージェントからワークスペースにスコープされた Codex タスクを実行	実験的機能: Codex ツール

ホスト型ツール

OpenAIは、OpenAIResponsesModel を使用する際に、いくつかの組み込みツールを提供しています。

• WebSearchTool を使用すると、エージェントは Web を検索できます。
• FileSearchTool を使用すると、OpenAIベクトルストアから情報を取得できます。
• CodeInterpreterTool を使用すると、LLMはサンドボックス環境でコードを実行できます。
• HostedMCPTool は、リモート MCPサーバーのツールをモデルに公開します。
• ImageGenerationTool は、プロンプトから画像を生成します。
• ToolSearchTool を使用すると、モデルは延期されたツール、名前空間、またはホスト型 MCPサーバーをオンデマンドで読み込めます。
• ProgrammaticToolCallingTool を使用すると、モデルは生成された JavaScript から対象ツールを調整できます。

高度なホスト型検索オプション:

• FileSearchTool は、vector_store_ids と max_num_results に加えて、filters、ranking_options、include_search_results をサポートしています。max_num_results には 1～50 の整数を設定します。None または 0 を指定すると、プロバイダーのデフォルトが使用されます。
• WebSearchTool は、filters、user_location、search_context_size、external_web_access、search_content_types、image_settings をサポートしています。

from agents import Agent, FileSearchTool, Runner, WebSearchTool

agent = Agent(
    name="Assistant",
    tools=[
        WebSearchTool(
            search_content_types=["image", "text"],
            image_settings={"max_results": 3, "caption": True},
        ),
        FileSearchTool(
            max_num_results=3,
            vector_store_ids=["VECTOR_STORE_ID"],
        ),
    ],
)

async def main():
    result = await Runner.run(agent, "Find recent images and supporting text about the Golden Gate Bridge at sunset.")
    print(result.final_output)

Web 検索で画像を返す場合は、search_content_types に "image" を含めます。モデルが裏付けとなるテキスト結果も必要とする場合は、"text" も含めます。image_settings.max_results には正の数の画像結果を指定し、image_settings.caption には、利用可能な場合に短い説明を要求します。"image" が存在する場合、SDK は自動的に web_search_call.results を要求します。これらの raw の結果は、アシスタントメッセージとは別に、RunResult.raw_responses 内の web_search_call 項目に保存され、image_url、source_website_url、thumbnail_url、caption を含む場合があります。OpenAIの画像検索結果ガイドを参照してください。

ホスト型ツール検索

ツール検索を使用すると、OpenAI Responses モデルは大規模なツール群の読み込みをランタイムまで延期できるため、モデルは現在のターンで必要なサブセットのみを読み込みます。これは、多数の関数ツール、名前空間グループ、またはホスト型 MCPサーバーがあり、すべてのツールを最初から公開せずにツールスキーマのトークンを削減したい場合に便利です。

エージェントを構築する時点で候補ツールがすでに判明している場合は、ホスト型ツール検索から始めます。アプリケーションで読み込む対象を動的に決定する必要がある場合、Responses API はクライアント実行型ツール検索もサポートしていますが、標準の Runner はこのモードを自動実行しません。

from typing import Annotated

from agents import Agent, Runner, ToolSearchTool, tool_namespace
from agents.decorators import tool


@tool(defer_loading=True)
def get_customer_profile(
    customer_id: Annotated[str, "The customer ID to look up."],
) -> str:
    """Fetch a CRM customer profile."""
    return f"profile for {customer_id}"


@tool(defer_loading=True)
def list_open_orders(
    customer_id: Annotated[str, "The customer ID to look up."],
) -> str:
    """List open orders for a customer."""
    return f"open orders for {customer_id}"


crm_tools = tool_namespace(
    name="crm",
    description="CRM tools for customer lookups.",
    tools=[get_customer_profile, list_open_orders],
)


agent = Agent(
    name="Operations assistant",
    model="gpt-5.6-sol",
    instructions="Load the crm namespace before using CRM tools.",
    tools=[*crm_tools, ToolSearchTool()],
)

result = await Runner.run(agent, "Look up customer_42 and list their open orders.")
print(result.final_output)

確認事項:

• ホスト型ツール検索は、OpenAI Responses モデルでのみ使用できます。現在の Python SDK のサポートは openai>=2.25.0 に依存します。
• エージェントで遅延読み込み対象を設定する場合は、ToolSearchTool() を必ず 1 つだけ追加します。
• 検索可能な対象には、@function_tool(defer_loading=True)、tool_namespace(name=..., description=..., tools=[...])、HostedMCPTool(tool_config={..., "defer_loading": True}) があります。
• 遅延読み込みされる関数ツールは、ToolSearchTool() と組み合わせる必要があります。名前空間のみの構成では、モデルがオンデマンドで適切なグループを読み込めるように、ToolSearchTool() も使用できます。
• tool_namespace() は、FunctionTool インスタンスを共有の名前空間名と説明の下にまとめます。これは通常、crm、billing、shipping など、関連するツールが多数ある場合に最適です。
• OpenAIの公式ベストプラクティスは、可能な限り名前空間を使用することです。
• 可能な場合は、個別に遅延される多数の関数よりも、名前空間またはホスト型 MCPサーバーを優先してください。通常、これらによってモデルには高水準でより優れた検索対象が提供され、トークンもより多く節約できます。
• 名前空間では、即時ツールと遅延ツールを混在させることができます。defer_loading=True がないツールは引き続き即座に呼び出せますが、同じ名前空間内の遅延ツールはツール検索を通じて読み込まれます。
• 経験則として、各名前空間は比較的小さく保ち、理想的には関数を 10 個未満にします。
• 名前付きの tool_choice では、単独の名前空間名や遅延専用ツールを対象にできません。auto、required、または実際に呼び出し可能なトップレベルツール名を優先してください。
• ToolSearchTool(execution="client") は、Responses の手動オーケストレーション用です。モデルがクライアント実行型の tool_search_call を出力すると、標準の Runner は代わりに実行することなく例外を発生させます。
• ツール検索のアクティビティは、専用の項目タイプおよびイベントタイプとともに、RunResult.new_items および RunItemStreamEvent に表示されます。
• 名前空間による読み込みとトップレベルの遅延ツールの両方を扱う、完全に実行可能なコード例については、examples/tools/tool_search.py を参照してください。
• 公式プラットフォームガイド: ツール検索。

プログラムによるツール呼び出し

プログラムによるツール呼び出しを使用すると、対応する OpenAI Responses モデルは、対象ツールを呼び出してその出力を結合し、1 つの結果をモデルに返す JavaScript を生成できます。これは、ツール呼び出しのたびにモデルとのラウンドトリップを行わず、ループ、分岐、並列呼び出し、または中間計算を活用できる、範囲が限定されたワークフローに役立ちます。

生成されたプログラムは、新しいホスト型 V8 環境で実行されます。Node.js API、ファイルシステムやネットワークへのアクセス、永続プロセスは利用できません。プログラムが操作できるのは、明示的に許可したツールだけです。

from pydantic import BaseModel

from agents import (
    Agent,
    ModelSettings,
    ProgrammaticToolCallingTool,
    Runner,
)
from agents.decorators import tool


class InventoryOutput(BaseModel):
    sku: str
    available_units: int


@tool(allowed_callers=["programmatic"])
def get_inventory(sku: str) -> InventoryOutput:
    return InventoryOutput(sku=sku, available_units=42)


agent = Agent(
    name="Inventory planner",
    model="gpt-5.6",
    model_settings=ModelSettings(tool_choice="programmatic_tool_calling"),
    tools=[get_inventory, ProgrammaticToolCallingTool()],
)

result = Runner.run_sync(agent, "Check inventory for desk-lamp and summarize it.")
print(result.final_output)

確認事項:

• プログラムによるツール呼び出しは、対応する OpenAI Responses モデルでのみ使用できます。ProgrammaticToolCallingTool() と tool_choice="programmatic_tool_calling" は、Chat Completionsモデルおよび Responses 以外のバックエンドでは拒否されます。
• エージェントに追加できる ProgrammaticToolCallingTool() は最大 1 つです。また、そのエージェントは、プログラムから呼び出し可能なツールを少なくとも 1 つ、名前空間、遅延関数、遅延ホスト型 MCPサーバーのいずれかに基づく ToolSearchTool()、またはプロンプトで管理される不透明なツール群を公開する必要があります。検索可能な対象がない単独の ToolSearchTool() は拒否されます。
• allowed_callers は、ツールをどのように呼び出せるかを制御します。省略した場合、モデルからの直接呼び出しのみが許可されます。プログラムからのみアクセス可能にするには ["programmatic"]、両方を許可するには ["direct", "programmatic"] を使用します。
• オプトインできる SDK ツールタイプは、FunctionTool、CustomTool、ShellTool、ApplyPatchTool、HostedMCPTool、CodeInterpreterTool です。関数、カスタム、シェル、apply-patch ツールは、allowed_callers を直接公開します。ホスト型 MCP および Code Interpreter の場合は、tool_config 内で allowed_callers を設定します。
• @function_tool(allowed_callers=[...]) では、Pydantic モデル、TypedDict、dataclass などの構造化された戻り値アノテーションは、自動的に厳密なオブジェクト出力スキーマになります。また、戻り値はプログラムに返される前に、そのスキーマに照らして検証されます。関数に使用可能なアノテーションがない場合は output_type=... を使用し、厳密なオブジェクトスキーマをすでに用意している場合は、より低水準のエスケープハッチである output_json_schema={...} を使用します。output_type と output_json_schema は相互に排他的です。str、Any、None の戻り値アノテーションからは、出力スキーマは作成されません。スキーマに基づきプログラムが所有する呼び出しでは、自由形式のテキストが出力スキーマを満たさないため、デフォルトの失敗フォーマッターは無効になります。そのため、スキーマに準拠した JSON を返すカスタムの failure_error_function を指定しない限り、ハンドラー例外が伝播します。
• プログラムが所有する SDK ツールでも、通常の Runner ライフサイクルが使用されます。ツール入力および出力ガードレール、フック、タイムアウト、同時実行数の制限、承認、セッション、RunState の一時停止／再開動作は引き続き適用され、SDK は各子呼び出しとプログラム呼び出し元との関係を保持します。
• ProgrammaticToolCallingTool() が存在する場合、プログラムの実行前であっても、モデルリクエストの再試行にはより厳格なリプレイ安全性の境界が適用されます。SDK は、これらのリクエストに対して、プロバイダー管理の再試行と WebSocket のイベント前再試行を無効にします。Runner の再試行ポリシーが再試行するのは、プロバイダーからの指示によってリプレイが安全であると明示された場合だけです。retry_policies.network_error() だけでは、この境界は上書きされません。
• 承認が必要なツールや影響の大きいツールは、通常、直接呼び出しのままにする方が適しています。これにより、それぞれのアクションが大規模なプログラムの一部になる前に、人が確認できます。プログラムが所有する呼び出しが承認のために一時停止した場合は、RunState を通じて中断を解決し、通常どおり元の実行を再開します。
• プログラムによるツール呼び出しは、ホスト型ツール検索と組み合わせられます。生成されたプログラムから遅延ツールを呼び出すには、モデルが事前にそのツールを読み込む必要があります。
• program 項目と、プログラムが所有する通常の子ツール呼び出しは、ToolCallItem エントリとして表示されます。対応する program_output は、ToolCallOutputItem として表示されます。ホスト型 MCP の承認リクエストおよびツールカタログでは、代わりに専用の MCP 項目とストリームイベントが使用されます。確認方法の詳細については、実行結果およびストリーミングを参照してください。
• 同時実行型の在庫計画に関する完全なコード例については、examples/tools/programmatic_tool_calling.py を参照してください。
• 公式プラットフォームガイド: プログラムによるツール呼び出し。

ホスト型コンテナシェルとスキル

ShellTool は、OpenAIがホストするコンテナでの実行もサポートしています。モデルにローカルランタイムではなく、管理されたコンテナ内でシェルコマンドを実行させたい場合は、このモードを使用します。

from agents import Agent, Runner, ShellTool, ShellToolSkillReference

csv_skill: ShellToolSkillReference = {
    "type": "skill_reference",
    "skill_id": "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377",
    "version": "1",
}

agent = Agent(
    name="Container shell agent",
    model="gpt-5.6-sol",
    instructions="Use the mounted skill when helpful.",
    tools=[
        ShellTool(
            environment={
                "type": "container_auto",
                "network_policy": {"type": "disabled"},
                "skills": [csv_skill],
            }
        )
    ],
)

result = await Runner.run(
    agent,
    "Use the configured skill to analyze CSV files in /mnt/data and summarize totals by region.",
)
print(result.final_output)

既存のコンテナを後続の実行で再利用するには、environment={"type": "container_reference", "container_id": "cntr_..."} を設定します。

確認事項:

• ホスト型シェルは、Responses API のシェルツールを通じて利用できます。
• container_auto はリクエスト用のコンテナをプロビジョニングし、container_reference は既存のコンテナを再利用します。
• container_auto には、file_ids と memory_limit も含められます。
• environment.skills は、スキル参照およびインラインスキルバンドルを受け付けます。
• ホスト型環境では、ShellTool に executor、needs_approval、on_approval を設定しないでください。
• network_policy は、disabled モードと allowlist モードをサポートしています。
• 許可リストモードでは、network_policy.domain_secrets によってドメインにスコープされたシークレットを名前で注入できます。
• 完全なコード例については、examples/tools/container_shell_skill_reference.py と examples/tools/container_shell_inline_skill.py を参照してください。
• OpenAIプラットフォームガイド: シェルおよびスキル。

ローカルランタイムツール

ローカルランタイムツールは、モデルレスポンス自体の外部で実行されます。モデルが呼び出すタイミングを引き続き決定しますが、実際の処理はアプリケーションまたは設定された実行環境が行います。

ComputerTool と ApplyPatchTool には、常に利用者が提供するローカル実装が必要です。ShellTool は両方のモードにまたがります。管理された実行が必要な場合は上記のホスト型コンテナ設定を使用し、独自プロセスでコマンドを実行する場合は以下のローカルランタイム設定を使用します。

ローカルランタイムツールには、実装を提供する必要があります。

• ComputerTool: GUI／ブラウザ自動化を有効にするには、Computer または AsyncComputer インターフェースを実装します。
• ShellTool: ローカル実行とホスト型コンテナ実行の両方に対応する最新のシェルツールです。
• LocalShellTool: 従来のローカルシェル統合です。
• ApplyPatchTool: ローカルで diff を適用するには、ApplyPatchEditor を実装します。
• ローカルシェルスキルは、ShellTool(environment={"type": "local", "skills": [...]}) で利用できます。

シェルアクションのタイムアウトでは、有限のタイムアウトとして正の整数のミリ秒を使用します。SDK は、ローカルの ShellTool エグゼキューターを呼び出す前に、0 と None の両方を明示的なタイムアウトなしとして扱います。これは、エグゼキューター実装間で 0 に共通の意味がないためです。その他の値は、エグゼキューターの呼び出し前に拒否されます。これはタイムアウトフィールドに固有の動作です。max_output_length=0 は、空のキャプチャ出力を要求する方法として引き続きサポートされています。

ComputerTool と Responses のコンピュータツール

ComputerTool は引き続きローカルハーネスです。利用者が Computer または AsyncComputer の実装を提供し、SDK がそのハーネスを OpenAI Responses API のコンピュータ機能にマッピングします。

Agent で model を設定していない場合は、通常の SDK モデル選択の優先順位が適用されます。現在の SDK 組み込みデフォルトである gpt-5.6-luna は、コンピュータ操作をサポートしています。OPENAI_DEFAULT_MODEL または RunConfig.model でそのデフォルトを上書きする場合は、コンピュータ操作をサポートするモデルを選択してください。コンピュータ操作のワークロードに対して異なる機能とコストのプロファイルを選択する場合は、エージェントで model を設定します。以下のコード例では、OpenAIが GPT-5.6 Sol にルーティングする gpt-5.6 エイリアスを使用しています。代わりに、GPT-5.6 Terra や GPT-5.6 Luna など、コンピュータ操作をサポートする別のモデルも選択できます。

gpt-5.6 など、GA の組み込みコンピュータツールをサポートするモデルを明示的にリクエストすると、SDK は {"type": "computer"} ペイロードを送信します。以前の computer-use-preview モデルへのリクエストでは、SDK は引き続きプレビューペイロード {"type": "computer_use_preview", "environment": ..., "display_width": ..., "display_height": ...} を送信します。これは、プラットフォームの computer-use-preview からの移行を反映しています。

• モデル: computer-use-preview -> gpt-5.6-sol
• ツールセレクター: computer_use_preview -> computer
• コンピュータ呼び出し形式: computer_call ごとに 1 つの action -> computer_call 上でバッチ化された actions[]
• 切り詰め: プレビュー経路では ModelSettings(truncation="auto") が必須 -> GA 経路では不要

SDK は、実際の Responses リクエストにおける有効なモデルから、その通信形式を選択します。プロンプトテンプレートを使用し、プロンプト側で管理しているためリクエストで model を省略する場合、model="gpt-5.6" などの対応する GA モデルを明示するか、ModelSettings(tool_choice="computer") または ModelSettings(tool_choice="computer_use") で GA セレクターを強制しない限り、SDK はプレビュー互換のコンピュータペイロードを維持します。

ComputerTool が存在する場合、tool_choice="computer"、"computer_use"、"computer_use_preview" はすべて受け入れられ、有効なリクエストモデルに一致する組み込みセレクターに正規化されます。ComputerTool がない場合、これらの文字列は引き続き通常の関数名として動作します。

この違いは、ComputerTool が ComputerProvider ファクトリーに基づく場合に重要です。GA の computer ペイロードでは、シリアライズ時に environment や寸法が不要なため、ファクトリーが Computer または AsyncComputer インスタンスを生成する前にシリアライズできます。プレビュー互換のシリアライズでは、SDK が environment、display_width、display_height を送信できるよう、解決済みの Computer または AsyncComputer インスタンスが引き続き必要です。

ランタイムでは、どちらの経路も同じローカルハーネスを使用します。プレビューレスポンスは単一の action を持つ computer_call 項目を出力します。GA レスポンスはバッチ化された actions[] を出力でき、SDK は computer_call_output スクリーンショット項目を生成する前に、それらを順番に実行します。Playwright に基づく実行可能なハーネスについては、examples/tools/computer_use.py を参照してください。

from agents import Agent, ApplyPatchTool, ComputerTool, ShellTool
from agents.computer import AsyncComputer
from agents.editor import ApplyPatchResult, ApplyPatchOperation, ApplyPatchEditor


class NoopComputer(AsyncComputer):
    environment = "browser"
    dimensions = (1024, 768)
    async def screenshot(self): return ""
    async def click(self, x, y, button): ...
    async def double_click(self, x, y): ...
    async def scroll(self, x, y, scroll_x, scroll_y): ...
    async def type(self, text): ...
    async def wait(self): ...
    async def move(self, x, y): ...
    async def keypress(self, keys): ...
    async def drag(self, path): ...


class NoopEditor(ApplyPatchEditor):
    async def create_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")
    async def update_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")
    async def delete_file(self, op: ApplyPatchOperation): return ApplyPatchResult(status="completed")


async def run_shell(request):
    return "shell output"


agent = Agent(
    name="Local tools agent",
    tools=[
        ShellTool(executor=run_shell),
        ApplyPatchTool(editor=NoopEditor()),
        ComputerTool(computer=NoopComputer()),
    ],
    # Optional: omit this argument to use the configured or built-in default model.
    model="gpt-5.6",
)

関数ツール

任意の Python 関数をツールとして使用できます。Agents SDKがツールを自動的に設定します。

• ツール名には Python 関数の名前が使用されます（名前を指定することもできます）
• ツールの説明は関数の docstring から取得されます（説明を指定することもできます）
• 関数入力のスキーマは、関数の引数から自動的に作成されます
• 無効にしていない限り、各入力の説明は関数の docstring から取得されます

@tool で作成されたツールは、読み取り専用の __wrapped__ 属性を通じて元の Python callable を公開します。これは確認やテストに役立ちますが、直接呼び出すと、スキーマ検証、コンテキスト注入、ガードレール、タイムアウト、失敗処理、トレーシングなどのツールランタイムパイプラインがバイパスされます。手動で構築した FunctionTool インスタンスは、__wrapped__ を公開しません。

関数シグネチャの抽出には Python の inspect モジュールを使用し、docstring の解析には griffe、スキーマ作成には pydantic を使用します。

OpenAI Responses モデルを使用している場合、ToolSearchTool() によって読み込まれるまで、@function_tool(defer_loading=True) は関数ツールを非表示にします。関連する関数ツールは、tool_namespace() でグループ化することもできます。完全な設定方法と制約については、ホスト型ツール検索を参照してください。

import json

from typing_extensions import TypedDict, Any

from agents import Agent, FunctionTool, RunContextWrapper
from agents.decorators import tool


class Location(TypedDict):
    lat: float
    long: float

@tool  # (1)!
async def fetch_weather(location: Location) -> str:
    # (2)!
    """Fetch the weather for a given location.

    Args:
        location: The location to fetch the weather for.
    """
    # In real life, we'd fetch the weather from a weather API
    return "sunny"


@tool(name_override="fetch_data")  # (3)!
def read_file(ctx: RunContextWrapper[Any], path: str, directory: str | None = None) -> str:
    """Read the contents of a file.

    Args:
        path: The path to the file to read.
        directory: The directory to read the file from.
    """
    # In real life, we'd read the file from the file system
    return "<file contents>"


agent = Agent(
    name="Assistant",
    tools=[fetch_weather, read_file],  # (4)!
)

for tool in agent.tools:
    if isinstance(tool, FunctionTool):
        print(tool.name)
        print(tool.description)
        print(json.dumps(tool.params_json_schema, indent=2))
        print()

1. 関数の引数には任意の Python 型を使用でき、関数は同期または非同期にできます。
2. docstring が存在する場合は、説明と引数の説明を取得するために使用されます
3. 関数は、必要に応じて実行コンテキストを最初の引数として受け取れます。ツール名、説明、使用する docstring スタイルなどを上書き設定することもできます。
4. デコレートされた関数をツールのリストに渡せます。

出力の表示

fetch_weather
Fetch the weather for a given location.
{
"$defs": {
  "Location": {
    "properties": {
      "lat": {
        "title": "Lat",
        "type": "number"
      },
      "long": {
        "title": "Long",
        "type": "number"
      }
    },
    "required": [
      "lat",
      "long"
    ],
    "title": "Location",
    "type": "object"
  }
},
"properties": {
  "location": {
    "$ref": "#/$defs/Location",
    "description": "The location to fetch the weather for."
  }
},
"required": [
  "location"
],
"title": "fetch_weather_args",
"type": "object"
}

fetch_data
Read the contents of a file.
{
"properties": {
  "path": {
    "description": "The path to the file to read.",
    "title": "Path",
    "type": "string"
  },
  "directory": {
    "anyOf": [
      {
        "type": "string"
      },
      {
        "type": "null"
      }
    ],
    "default": null,
    "description": "The directory to read the file from.",
    "title": "Directory"
  }
},
"required": [
  "path"
],
"title": "fetch_data_args",
"type": "object"
}

関数ツールからの画像またはファイルの返却

テキスト出力に加えて、1 つまたは複数の画像やファイルを関数ツールの出力として返すことができます。そのためには、次のいずれかを返します。

• 画像: ToolOutputImage（または TypedDict 版の ToolOutputImageDict）
• ファイル: ToolOutputFileContent（または TypedDict 版の ToolOutputFileContentDict）
• テキスト: 文字列、文字列化可能なオブジェクト、または ToolOutputText（または TypedDict 版の ToolOutputTextDict）

カスタム関数ツール

Python 関数をツールとして使用したくない場合もあります。必要に応じて、FunctionTool を直接作成できます。次の項目を指定する必要があります。

• name
• description
• 引数の JSON スキーマである params_json_schema
• ToolContext と JSON 文字列形式の引数を受け取り、ツール出力（テキスト、構造化されたツール出力オブジェクト、出力のリストなど）を返す非同期関数である on_invoke_tool

from typing import Any

from pydantic import BaseModel

from agents import RunContextWrapper, FunctionTool



def do_some_work(data: str) -> str:
    return "done"


class FunctionArgs(BaseModel):
    username: str
    age: int


async def run_function(ctx: RunContextWrapper[Any], args: str) -> str:
    parsed = FunctionArgs.model_validate_json(args)
    return do_some_work(data=f"{parsed.username} is {parsed.age} years old")


tool = FunctionTool(
    name="process_user",
    description="Processes extracted user data",
    params_json_schema=FunctionArgs.model_json_schema(),
    on_invoke_tool=run_function,
)

引数と docstring の自動解析

前述のとおり、ツールのスキーマを抽出するために関数シグネチャを自動的に解析し、ツールおよび個々の引数の説明を抽出するために docstring を解析します。これについて、いくつか注意事項があります。

1. シグネチャの解析は、inspect モジュールを通じて行われます。型アノテーションを使用して引数の型を把握し、スキーマ全体を表す Pydantic モデルを動的に構築します。Python の基本型、Pydantic モデル、TypedDict など、ほとんどの型をサポートしています。
2. docstring の解析には griffe を使用します。サポートされている docstring 形式は、google、sphinx、numpy です。docstring 形式の自動検出を試みますが、これはベストエフォートです。function_tool を呼び出す際に明示的に設定することもできます。use_docstring_info を False に設定すると、docstring の解析を無効にできます。Google スタイルの docstring では、パーサーは、概要テキストの直後に空行を挟まずに置かれた Args:、Arguments:、Params:、Parameters: セクションも受け付けます。

スキーマ抽出のコードは、agents.function_schema にあります。

Pydantic Field による引数の制約と説明

Pydantic の Field を使用して、ツール引数に制約（数値の最小値／最大値、文字列の長さやパターンなど）と説明を追加できます。Pydantic と同様に、デフォルト値に基づく形式（arg: int = Field(..., ge=1)）と Annotated（arg: Annotated[int, Field(..., ge=1)]）の両方がサポートされています。生成される JSON スキーマと検証には、これらの制約が含まれます。

可変長パラメーターの場合、アノテーションは収集される各値を表します。そのため、SDK は *args または **kwargs を通じて指定された各値に Annotated[..., Field(...)] の制約を適用します。一方、省略された可変長パラメーターは、有効な空のコレクションのままです。スカラーの位置引数には、*args: T のようにアノテーションを付けます。各位置引数の値自体が同種要素のタプルである場合は、*args: tuple[T, ...] を使用します。固定された 1 つのタプル形式では位置引数の可変長シーケンスを表現できないため、SDK は *args: tuple[int, str] のような固定長タプルのアノテーションを拒否します。

from typing import Annotated
from pydantic import Field
from agents.decorators import tool

# Default-based form
@tool
def score_a(score: int = Field(..., ge=0, le=100, description="Score from 0 to 100")) -> str:
    return f"Score recorded: {score}"

# Annotated form
@tool
def score_b(score: Annotated[int, Field(..., ge=0, le=100, description="Score from 0 to 100")]) -> str:
    return f"Score recorded: {score}"

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

@function_tool(timeout=...) を使用して、非同期関数ツールの呼び出しごとにタイムアウトを設定できます。

import asyncio
from agents import Agent
from agents.decorators import tool


@tool(timeout=2.0)
async def slow_lookup(query: str) -> str:
    await asyncio.sleep(10)
    return f"Result for {query}"


agent = Agent(
    name="Timeout demo",
    instructions="Use tools when helpful.",
    tools=[slow_lookup],
)

タイムアウトに達した場合のデフォルト動作は timeout_behavior="error_as_result" で、モデルから見えるタイムアウトメッセージ（Tool 'slow_lookup' timed out after 2 seconds. など）を送信します。

タイムアウト処理は次のように制御できます。

• timeout_behavior="error_as_result"（デフォルト）: モデルが復旧できるように、タイムアウトメッセージをモデルに返します。
• timeout_behavior="raise_exception": ToolTimeoutError を発生させ、実行を失敗させます。
• error_as_result を使用する場合、timeout_error_function=... でタイムアウトメッセージをカスタマイズします。

import asyncio
from agents import Agent, Runner, ToolTimeoutError
from agents.decorators import tool


@tool(timeout=1.5, timeout_behavior="raise_exception")
async def slow_tool() -> str:
    await asyncio.sleep(5)
    return "done"


agent = Agent(name="Timeout hard-fail", tools=[slow_tool])

try:
    await Runner.run(agent, "Run the tool")
except ToolTimeoutError as e:
    print(f"{e.tool_name} timed out in {e.timeout_seconds} seconds")

Note

タイムアウト設定は、非同期の @function_tool ハンドラーでのみサポートされています。

関数ツールのエラー処理

@function_tool を使用して関数ツールを作成する場合、failure_error_function を渡せます。これは、ツール呼び出しがクラッシュした場合に LLMへエラーレスポンスを提供する関数です。

• デフォルトでは（何も渡さない場合）、エラーが発生したことを LLMに通知する default_tool_error_function が実行されます。
• 独自のエラー関数を渡すと、代わりにその関数が実行され、レスポンスが LLMに送信されます。
• None を明示的に渡すと、ツール呼び出しのエラーが再度送出され、利用者側で処理できるようになります。たとえば、モデルが無効な JSON を生成した場合は ModelBehaviorError、コードがクラッシュした場合は UserError などが発生する可能性があります。

from agents import RunContextWrapper
from agents.decorators import tool
from typing import Any

def my_custom_error_function(context: RunContextWrapper[Any], error: Exception) -> str:
    """A custom function to provide a user-friendly error message."""
    print(f"A tool call failed with the following error: {error}")
    return "An internal server error occurred. Please try again later."

@tool(failure_error_function=my_custom_error_function)
def get_user_profile(user_id: str) -> str:
    """Fetches a user profile from a mock API.
     This function demonstrates a 'flaky' or failing API call.
    """
    if user_id == "user_123":
        return "User profile for user_123 successfully retrieved."
    else:
        raise ValueError(f"Could not retrieve profile for user_id: {user_id}. API returned an error.")

FunctionTool オブジェクトを手動で作成する場合は、on_invoke_tool 関数内でエラーを処理する必要があります。

Agents as tools

一部のワークフローでは、制御をハンドオフする代わりに、中央のエージェントで特化したエージェントのネットワークをオーケストレーションしたい場合があります。これは、エージェントをツールとしてモデル化することで実現できます。

import asyncio

from agents import Agent, Runner

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You translate the user's message to Spanish",
)

french_agent = Agent(
    name="French agent",
    instructions="You translate the user's message to French",
)

orchestrator_agent = Agent(
    name="orchestrator_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate. "
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
    ],
)

async def main():
    result = await Runner.run(orchestrator_agent, input="Say 'Hello, how are you?' in Spanish.")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

ツールエージェントのカスタマイズ

agent.as_tool は、エージェントをツールに変換するための便利なメソッドです。max_turns、run_config、hooks、previous_response_id、conversation_id、session、needs_approval など、一般的なランタイムオプションをサポートしています。また、parameters、input_builder、include_input_schema を使用した構造化入力もサポートしています。

状態オプションは、ツール呼び出しによって開始されるネストされたエージェント実行を設定します。親実行の会話状態は自動的には継承されません。親実行とネストされた実行の間でクライアント管理の履歴を共有するには、両方に同じ session を明示的に渡します。Runner.run と同様に、ネストされた実行では、クライアント管理の session、または previous_response_id か conversation_id を通じたサーバー管理の継続のいずれか 1 つの状態戦略を選択します。

from agents.decorators import tool


@tool
async def run_my_agent() -> str:
    """A tool that runs the agent with custom configs"""

    agent = Agent(name="My agent", instructions="...")

    result = await Runner.run(
        agent,
        input="...",
        max_turns=5,
        run_config=...
    )

    return str(result.final_output)

ツールエージェントの構造化入力

デフォルトでは、Agent.as_tool() は、文字列フィールド input（{"input": "..."}）を 1 つ持つオブジェクトを想定します。ただし、parameters（Pydantic モデル型または dataclass 型）を渡すことで、構造化スキーマを公開できます。

追加オプション:

• include_input_schema=True は、生成されるネスト入力に完全な JSON Schema を含めます。
• input_builder=... を使用すると、構造化されたツール引数をネストされたエージェント入力へ変換する方法を完全にカスタマイズできます。
• RunContextWrapper.tool_input には、ネストされた実行コンテキスト内で解析済みの構造化ペイロードが含まれます。

from pydantic import BaseModel, Field


class TranslationInput(BaseModel):
    text: str = Field(description="Text to translate.")
    source: str = Field(description="Source language.")
    target: str = Field(description="Target language.")


translator_tool = translator_agent.as_tool(
    tool_name="translate_text",
    tool_description="Translate text between languages.",
    parameters=TranslationInput,
    include_input_schema=True,
)

完全に実行可能なコード例については、examples/agent_patterns/agents_as_tools_structured.py を参照してください。

ツールエージェントの承認ゲート

Agent.as_tool(..., needs_approval=...) は、function_tool と同じ承認フローを使用します。承認が必要な場合、実行は一時停止し、保留中の項目が result.interruptions に表示されます。その後、result.to_state() を使用し、state.approve(...) または state.reject(...) を呼び出した後に再開します。完全な一時停止／再開パターンについては、Human-in-the-loop ガイドを参照してください。

カスタム出力の抽出

特定のケースでは、ツールエージェントの出力を中央のエージェントに返す前に変更したい場合があります。これは、次のような場合に役立ちます。

• サブエージェントのチャット履歴から特定の情報（JSON ペイロードなど）を抽出する。
• エージェントの最終回答を変換または再フォーマットする（Markdown をプレーンテキストや CSV に変換するなど）。
• 出力を検証する、またはエージェントのレスポンスが欠落しているか不正な形式の場合にフォールバック値を提供する。

これは、as_tool メソッドに custom_output_extractor 引数を指定することで実現できます。

async def extract_json_payload(run_result: RunResult) -> str:
    # Scan the agent’s outputs in reverse order until we find a JSON-like message from a tool call.
    for item in reversed(run_result.new_items):
        if isinstance(item, ToolCallOutputItem) and item.output.strip().startswith("{"):
            return item.output.strip()
    # Fallback to an empty JSON object if nothing was found
    return "{}"


json_tool = data_agent.as_tool(
    tool_name="get_data_json",
    tool_description="Run the data agent and return only its JSON payload",
    custom_output_extractor=extract_json_payload,
)

カスタムエクストラクター内では、ネストされた RunResult から agent_tool_invocation にもアクセスできます。これは、ネストされた実行結果を後処理する際に、外側のツール名、呼び出し ID、または raw 引数が必要な場合に役立ちます。実行結果ガイドを参照してください。

ネストされたエージェント実行のストリーミング

as_tool に on_stream コールバックを渡すと、ネストされたエージェントが出力するストリーミングイベントをリッスンしながら、ストリーム完了後に最終出力を返すことができます。

from agents import AgentToolStreamEvent


async def handle_stream(event: AgentToolStreamEvent) -> None:
    # Inspect the underlying StreamEvent along with agent metadata.
    print(f"[stream] {event['agent'].name} :: {event['event'].type}")


billing_agent_tool = billing_agent.as_tool(
    tool_name="billing_helper",
    tool_description="Answer billing questions.",
    on_stream=handle_stream,  # Can be sync or async.
)

想定される動作:

• イベントタイプは StreamEvent["type"] と同様です: raw_response_event、run_item_stream_event、agent_updated_stream_event。
• on_stream を指定すると、ネストされたエージェントは自動的にストリーミングモードで実行され、最終出力を返す前にストリームが最後まで処理されます。
• ハンドラーは同期でも非同期でも構いません。各イベントは到着順に配信されます。
• モデルのツール呼び出しを介してツールが呼び出された場合は、tool_call が存在します。直接呼び出した場合は、None のままになることがあります。
• 完全に実行可能なコード例については、examples/agent_patterns/agents_as_tools_streaming.py を参照してください。

条件付きツール有効化

is_enabled パラメーターを使用すると、ランタイムでエージェントツールを条件付きで有効または無効にできます。これにより、コンテキスト、ユーザー設定、ランタイム条件に基づいて、LLMが使用できるツールを動的に絞り込めます。

import asyncio
from agents import Agent, AgentBase, Runner, RunContextWrapper
from pydantic import BaseModel

class LanguageContext(BaseModel):
    language_preference: str = "french_spanish"

def french_enabled(ctx: RunContextWrapper[LanguageContext], agent: AgentBase) -> bool:
    """Enable French for French+Spanish preference."""
    return ctx.context.language_preference == "french_spanish"

# Create specialized agents
spanish_agent = Agent(
    name="spanish_agent",
    instructions="You respond in Spanish. Always reply to the user's question in Spanish.",
)

french_agent = Agent(
    name="french_agent",
    instructions="You respond in French. Always reply to the user's question in French.",
)

# Create orchestrator with conditional tools
orchestrator = Agent(
    name="orchestrator",
    instructions=(
        "You are a multilingual assistant. You use the tools given to you to respond to users. "
        "You must call ALL available tools to provide responses in different languages. "
        "You never respond in languages yourself, you always use the provided tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="respond_spanish",
            tool_description="Respond to the user's question in Spanish",
            is_enabled=True,  # Always enabled
        ),
        french_agent.as_tool(
            tool_name="respond_french",
            tool_description="Respond to the user's question in French",
            is_enabled=french_enabled,
        ),
    ],
)

async def main():
    context = LanguageContext(language_preference="french_spanish")
    result = await Runner.run(orchestrator, "How are you?", context=context)
    print(result.final_output)

asyncio.run(main())

is_enabled パラメーターは、次を受け付けます。

• ブール値: True（常に有効）または False（常に無効）
• 呼び出し可能な関数: (context, agent) を受け取り、ブール値を返す関数
• 非同期関数: 複雑な条件ロジックに使用する非同期関数

無効化されたツールは、ランタイムで LLMから完全に非表示になります。そのため、次の用途に役立ちます。

• リクエストにスコープされた機能の可視性
• 環境固有のツール可用性（開発環境と本番環境）
• 異なるツール設定の A/B テスト
• ランタイム状態に基づく動的なツールの絞り込み

ローカルで設定された関数ツールの場合、Runner は呼び出し前にも is_enabled を再評価します。ただし、is_enabled は可視性とディスパッチを制御するものであり、ツール引数やアクセス対象のリソースに依存する認可の代わりにはなりません。これらのチェックはツール実装内で適用するか、必要に応じてツール入力ガードレールおよび承認を使用してください。MCPサーバーは、保護対象の操作を自身で認可する必要があります。

関数ツール、MCP ツール、ハンドオフ全体に 1 つのアプリケーションポリシーを適用するパターンについては、コンテキスト管理を参照してください。

実験的機能: Codex ツール

codex_tool は Codex CLI をラップし、エージェントがツール呼び出し中にワークスペースにスコープされたタスク（シェル、ファイル編集、MCP ツール）を実行できるようにします。この機能は実験的であり、変更される可能性があります。

メインエージェントが現在の実行を離れずに、範囲が限定されたワークスペースタスクを Codex に委任する場合に使用します。デフォルトのツール名は codex です。カスタム名を設定する場合は、codex であるか、codex_ で始まる必要があります。エージェントに複数の Codex ツールを含める場合、それぞれに一意の名前を使用する必要があります。

from agents import Agent
from agents.extensions.experimental.codex import ThreadOptions, TurnOptions, codex_tool

agent = Agent(
    name="Codex Agent",
    instructions="Use the codex tool to inspect the workspace and answer the question.",
    tools=[
        codex_tool(
            sandbox_mode="workspace-write",
            working_directory="/path/to/repo",
            default_thread_options=ThreadOptions(
                model="gpt-5.5",
                model_reasoning_effort="low",
                network_access_enabled=True,
                web_search_mode="disabled",
                approval_policy="never",
            ),
            default_turn_options=TurnOptions(
                idle_timeout_seconds=60,
            ),
            persist_session=True,
        )
    ],
)

まず、次のオプショングループを確認してください。

• 実行対象: sandbox_mode と working_directory は、Codex が操作できる場所を定義します。これらは組み合わせて使用し、作業ディレクトリが Git リポジトリ内にない場合は skip_git_repo_check=True を設定します。
• スレッドのデフォルト: default_thread_options=ThreadOptions(...) は、モデル、推論エフォート、承認ポリシー、追加ディレクトリ、ネットワークアクセス、Web 検索モードを設定します。従来の web_search_enabled よりも web_search_mode を優先してください。
• ターンのデフォルト: default_turn_options=TurnOptions(...) は、idle_timeout_seconds や任意指定のキャンセル用 signal など、ターンごとの動作を設定します。
• ツール I/O: ツール呼び出しには、{ "type": "text", "text": ... } または { "type": "local_image", "path": ... } を持つ inputs 項目を少なくとも 1 つ含める必要があります。output_schema を使用すると、構造化された Codex レスポンスを必須にできます。

スレッドの再利用と永続化は、別々の制御項目です。

• persist_session=True は、同じツールインスタンスへの繰り返し呼び出しで 1 つの Codex スレッドを再利用します。
• use_run_context_thread_id=True は、同じ変更可能なコンテキストオブジェクトを共有する複数の実行で、スレッド ID を実行コンテキストに保存して再利用します。
• スレッド ID の優先順位は、呼び出しごとの thread_id、実行コンテキストのスレッド ID（有効な場合）、設定済みの thread_id オプションの順です。
• デフォルトの実行コンテキストキーは、name="codex" では codex_thread_id、name="codex_<suffix>" では codex_thread_id_<suffix> です。run_context_thread_id_key で上書きできます。

ランタイム設定:

• 認証: CODEX_API_KEY（推奨）または OPENAI_API_KEY を設定するか、codex_options={"api_key": "..."} を渡します。
• ランタイム: codex_options.base_url は CLI のベース URL を上書きします。
• バイナリ解決: CLI のパスを固定するには、codex_options.codex_path_override（または CODEX_PATH）を設定します。それ以外の場合、SDK は PATH から codex を解決し、その後、同梱のベンダーバイナリにフォールバックします。
• 環境: codex_options.env は、サブプロセス環境を完全に制御します。これを指定した場合、サブプロセスは os.environ を継承しません。
• ストリーム制限: codex_options.codex_subprocess_stream_limit_bytes（または OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES）は、stdout／stderr リーダーの制限を制御します。有効範囲は 65536～67108864 で、デフォルトは 8388608 です。
• ストリーミング: on_stream は、スレッド／ターンのライフサイクルイベントと項目イベント（reasoning、command_execution、mcp_tool_call、file_change、web_search、todo_list、error の項目更新）を受け取ります。
• 出力: 実行結果には response、usage、thread_id が含まれます。使用量は RunContextWrapper.usage に追加されます。

リファレンス:

• Codex ツール API リファレンス
• ThreadOptions リファレンス
• TurnOptions リファレンス
• 完全に実行可能なコード例については、examples/tools/codex.py と examples/tools/codex_same_thread.py を参照してください。