## ツール呼び出し

• /v1/chat/completions（OpenAI形式のtoolsとtool_calls）
• /v1/responses（Responses 形式のfunction_call出力項目）
• /v1/messages（Anthropic形式のtool_useブロック）

​

リクエスト

curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "messages": [
      { "role": "user", "content": "What is the weather in London?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": {
      "type": "function",
      "function": { "name": "get_weather" }
    },
    "stream": false
  }'

​

レスポンス

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "finish_reason": "tool_calls",
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"London\"}"
            }
          }
        ]
      }
    }
  ]
}

​

組み込みサーバーツール

• gateway:datetime
• phaseo:web_search
• phaseo:web_fetch
• phaseo:advisor
• phaseo:image_generation
• phaseo:apply_patch

{
  "tools": [
    {
      "type": "gateway:datetime",
      "parameters": {
        "timezones": ["Europe/London", "UTC"]
      }
    }
  ]
}

• parameters.timezonesは省略可能で、1回の呼び出しで最大5つの有効なIANAタイムゾーンを指定できます。
• 結果にはtimezones配列が含まれます。各タイムゾーンについて、ISO形式の日時と解決済みのタイムゾーンが示されます。
• 使用量にはusage.server_tool_use.datetime_requestsが含まれます。
• モデルが呼び出すタイミングを判断できるよう、tool_choice: "auto"を使うことをおすすめします。

​

Web検索の例

{
  "tools": [
    {
      "type": "phaseo:web_search",
      "parameters": {
        "engine": "exa",
        "max_results": 5,
        "max_total_results": 15,
        "search_context_size": "medium",
        "max_characters": 2048,
        "allowed_domains": ["arxiv.org", "nature.com"],
        "include_highlights": true
      }
    }
  ]
}

• モデルはツールを呼び出す際に検索クエリを指定します。
• engine: "auto"は管理されたExa検索を選択します。対応するプロバイダーキーが設定されていれば、engine: "exa"、engine: "parallel"、engine: "firecrawl"、engine: "tinyfish"で管理されたGateway検索を実行できます。
• TinyFish Searchは多言語対応のページ分割されたランキング結果を提供し、公開プランでは無料です。必要に応じてツールのパラメーターでlanguageとpageを使ってください。
• phaseo:web_searchでengine: "native"を指定すると、リクエスト形式に応じたプロバイダーのネイティブWeb検索ツールに変換されます。たとえばOpenAIのweb_search_previewやAnthropicのweb_search_20250305です。
• max_resultsは各検索呼び出しの結果数を制限し、max_total_resultsはサーバーツールループ全体の累積結果数を制限します。
• 選択した検索エンジンが該当する設定に対応している場合、管理型検索ではallowed_domains / excluded_domains、search_context_size、max_charactersを使えます。
• 使用量にはusage.server_tool_use.web_search_requests、usage.server_tool_use.web_search_results、usage.server_tool_use.web_search_extra_resultsが含まれます。
• 管理型Exa検索はserver_tool_web_search_requestsとserver_tool_web_search_extra_resultsのメーターで課金できます。

​

Web Fetchの例

{
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "direct",
        "max_chars": 12000,
        "allowed_domains": ["docs.example.com"],
        "blocked_domains": ["internal.example.com"]
      }
    }
  ]
}

• モデルはツールの呼び出し時に取得対象のurlを指定します。
• 対応しているのはHTTP(S)のURLとテキスト系のコンテンツタイプのみです。
• engine: "auto"はAnthropic Messagesではネイティブ取得を使い、それ以外ではEXA_API_KEY設定時にExaを使います。どちらも使えない場合はGatewayの直接HTTP取得を使います。
• engine: "direct"はGatewayから直接HTTP取得します。engine: "exa"はEXA_API_KEY設定時にExaでコンテンツを抽出します。
• PARALLEL_API_KEY設定時、engine: "parallel"はParallel Extractを使います。FIRECRAWL_API_KEY設定時、engine: "firecrawl"はFirecrawl Scrapeを使います。
• Anthropic Messagesではengine: "native"をAnthropicネイティブのweb_fetch_20260209ツールに変換します。それ以外の形式ではengine: "direct"または管理型抽出エンジンを使ってください。
• max_charsを省略した場合、max_content_tokensをトークン数で上限を指定する取得サイズのエイリアスとして使えます。
• allowed_domainsとblocked_domainsで取得可能なURLを制限します。
• HTMLは、モデルの処理ループに戻す前に長さを制限したプレーンテキストに変換されます。
• 使用量にはusage.server_tool_use.web_fetch_requestsが含まれます。
• 管理対象のフェッチ機能はserver_tool_web_fetch_requestsメーターに基づいて課金されます。プロバイダー独自のフェッチと検索は、それぞれnative_web_fetch_requestsとnative_web_search_requestsに基づいて課金されます。モデルの価格カードから、プロバイダーに組み込まれた既定値を上書きできます。

{
  "tools": [
    {
      "type": "phaseo:web_fetch",
      "parameters": {
        "engine": "native",
        "max_content_tokens": 9000,
        "allowed_domains": ["docs.example.com"]
      }
    }
  ],
  "tool_choice": "phaseo:web_fetch"
}

​

Advisorの例

{
  "tools": [
    {
      "type": "phaseo:advisor",
      "parameters": {
        "name": "reviewer",
        "model": "claude-opus-5",
        "instructions": "Review plans for correctness, missing edge cases, and implementation risk.",
        "forward_transcript": true,
        "max_uses": 2,
        "max_completion_tokens": 1400,
        "temperature": 0.2
      }
    }
  ],
  "tool_choice": "phaseo:advisor"
}

• AdvisorはGatewayが管理し、対応するテキストモデルで利用できます。呼び出し元のモデルにはphaseo_advisorツール、またはphaseo_advisor_reviewerのような名前付きツールが渡され、GatewayがAdvisorリクエストを実行します。
• parameters.nameは省略可能です。複数のAdvisorを使う場合は一意の名前を付けます。名前には英字、数字、空白、アンダースコア、ハイフンを使用できます。
• parameters.modelでAdvisorモデルを固定します。省略した場合、ツール呼び出しでmodelを指定できます。それもなければ、Gatewayは外側のリクエストのモデルを使います。
• parameters.forward_transcriptのデフォルトはfalseです。Advisorに現在の会話履歴を渡すにはtrueにします。
• モデルは通常、ツール呼び出し時にAdvisorのpromptを指定します。forward_transcriptがtrueでpromptがない場合、Gatewayは会話履歴のみを使ってAdvisorを呼び出せます。max_tokensはmax_completion_tokensの旧エイリアスとして受け付けられます。
• 使用量にはusage.server_tool_use.advisor_requestsが含まれます。

​

画像生成の例

{
  "tools": [
    {
      "type": "phaseo:image_generation",
      "parameters": {
        "model": "openai/gpt-image-2",
        "quality": "high",
        "aspect_ratio": "16:9",
        "output_format": "png"
      }
    }
  ]
}

• ツールを呼び出す際、モデルは画像のpromptを指定します。descriptionもプロンプトのエイリアスとして使えます。
• parameters.modelで画像モデルを固定します。省略するとツール呼び出しでmodelを指定できます。どちらもなければPhaseoのデフォルト画像モデルを使います。
• プロバイダーの応答に応じて、ツール結果にはimageUrlまたはbase64形式の画像データが含まれます。
• 使用量にはusage.server_tool_use.image_generation_requestsが含まれます。画像モデルのトークン使用量は親リクエストに統合されます。

​

パッチ適用の例

{
  "tools": [
    {
      "type": "phaseo:apply_patch"
    }
  ],
  "tool_choice": "auto"
}

• Responses API で phaseo:apply_patch を使用できます。
• Phaseoはパッチ操作を検証してツール結果に返します。パッチを適用するか拒否するかはクライアント側で決めます。
• 対応する操作タイプはcreate_file、update_file、delete_fileです。
• 使用量にはusage.server_tool_use.apply_patch_requestsが含まれます。

​

ストリーミングの動作

• 上流のツール呼び出しターンを展開する
• サーバーツールを実行する
• モデルの処理ループを続ける
• クライアントに合成ストリームを再送する

​

次のガイド

1. ## ツール呼び出し Patterns
2. ## ツール呼び出し Safety and Validation
3. 構造化出力