クライアント関数ツール

クライアント コードからはアクセスできるものの、OpenAPI や MCP などのホスト型ツールからはアクセスできない場合は、クライアント関数ツールを使用できます。クライアント関数ツールは、エージェントではなく、常にクライアントサイドで実行されます。

仕組み

エージェントがクライアント関数ツールをトリガーすると:

  1. セッション ブロック: 会話セッションがサーバー側で事実上「ブロック」されます。
  2. クライアント実行: クライアント アプリケーションは、ツール呼び出しを特定し、ローカル環境で対応するロジックを実行する必要があります。
  3. レスポンスの提供: 実行が完了したら、クライアント アプリケーションは toolResponses フィールドを使用して、エージェントにレスポンスを返す必要があります。

エージェントは、このレスポンスを待ってから会話を進めます。

構成

クライアント関数ツールを作成するときに、エージェントがクライアントサイド コードを理解して操作する方法を定義します。

  • 名前: ツールの固有の識別子（例: open_settings）。
  • 説明: ツールの目的の簡単な説明。エージェント モデルは、この説明を使用して関数を呼び出すタイミングを決定します。
  • 入力/出力スキーマ: OpenAPI 形式で定義されます。これにより、エージェントが送信し、受信を想定するデータの構造が決まります。

ユースケース

クライアント関数ツールは、次のような場合に最適です。

  • UI/UX アクション: アプリケーションのインターフェースで変更をトリガーします（例: 「サポート画面に移動」）。
  • ローカル デバイスデータ: アプリのコンテキスト内でのみ利用可能な情報にアクセスします（例: 「現在のバッテリー残量を取得する」）。
  • プライベート API: クライアントサイド環境からのみアクセス可能なサービスとの統合。

例

次の例は、クライアント アプリケーションが関数を呼び出す必要があることを示すセッション レスポンスです。

"outputs": [
  {
    "toolCalls": {
      "toolCalls": [
        {
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "args": {
            "zip_code": "92031"
          },
          "displayName": "get_nearest_store"
        }
      ]
    },
    "turnCompleted": true,
  }
]

次の例は、ツール出力がリクエストに添付された後続のセッション実行です。クライアント アプリケーションは、これらのフィールドに入力し、前のメッセージと同じ id、tool、display_name の値を指定する必要があります。

"inputs": [
  {
    "toolResponses": {
      "toolResponses": [
        {
          "displayName": "get_nearest_store",
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "response": {
            "name": "Alibaba",
            "address": "43 Alpha Road, Mountain View, CA 92039, USA"
          },
        }
      ]
    }
  }
]