クライアントツール

クライアントツールを使うと、エージェントは接続中のアプリケーションでアクションをトリガーできます。たとえば、ページを開いたり、クライアント側の状態を読み取ったりできます。クライアントツールは WebSocket API 経由でのみ利用できます。モデルがクライアントツールを呼び出すと、サーバーは接続されたブラウザ、モバイルアプリ、またはサーバーに client_tool_call イベントを送信します。関数の実行後、応答が必要な場合は、その接続されたクライアントが client_tool_result をサーバーに送信します。

クライアントツールを定義する

{
  "type": "client",
  "name": "open_cart",
  "description": "Opens the shopping cart. Use it when the user wants to review or check out their cart.",
  "pre_tool_speech": "auto",
  "execution_mode": "async",
  "expects_response": false,
  "parameters": {
    "type": "object",
    "properties": {
      "cart_id": {
        "type": "string",
        "description": "Cart to open."
      }
    },
    "required": ["cart_id"]
  }
}

POST /v1/agents/tools でツールを作成し、その ID を config.tools でアタッチします。共有の実行設定についてはツールを参照してください。

パラメータ

parameters は JSON Schema のオブジェクトである必要があります。プロパティには string、integer、number、boolean、またはこれらのスカラー型のいずれかの配列を使用できます。string プロパティ内で enum を使用すると、許可される文字列値を列挙できます。モデルが必ず提供すべき値は required で指定します。

レスポンスの挙動

expects_response: true にすると、エージェントは同じ tool_call_id を持つ client_tool_result を待ちます。結果が会話に影響する場合に使用します。
expects_response: false にすると、ディスパッチ後にツールが完了します。エージェントが確認する必要のないクライアント側アクションに使用します。

expects_response が true の場合、Cartesia は最大 response_timeout_secs の間、結果を待ちます。結果が届かない場合、Cartesia は自動的に Tool call timed out を LLM に渡します。接続されたクライアントが自身の失敗を報告するには、is_error: true と、任意の error_type を含む結果を送信します。

ツール呼び出しを処理する

// ws は WebSocket API クイックスタートで作成した接続です。
async function runTool(name, parameters) {
  if (name === "open_cart") {
    // インターフェースでカートを開きます。
    return { opened: true, cart_id: parameters.cart_id };
  }
  throw new Error(`Unknown tool: ${name}`);
}

ws.onmessage = async (message) => {
  const event = JSON.parse(message.data);
  if (event.type !== "client_tool_call") return;

  let result;
  try {
    result = await runTool(event.tool_name, event.parameters);
  } catch (error) {
    console.error("Client tool failed:", error);
    if (event.expects_response) {
      ws.send(JSON.stringify({
        type: "client_tool_result",
        tool_call_id: event.tool_call_id,
        result: "The client tool failed.",
        is_error: true,
      }));
    }
    return;
  }

  if (event.expects_response) {
    ws.send(JSON.stringify({
      type: "client_tool_result",
      tool_call_id: event.tool_call_id,
      result: JSON.stringify(result),
      is_error: false,
    }));
  }
};

結果は最大 4096 バイトの文字列です。失敗時は、is_error: true と、LLM が対処できる短い result を送信してください。LLM が受け取るのは result です。任意の error_type には、timeout のような最大 256 UTF-8 バイトの自由形式の文字列を指定できます。これより長い値の場合も結果は破棄されます。完全なイベントスキーマについては WebSocket イベントリファレンスを参照してください。