> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# クライアントツール

> WebSocket API 経由でアプリケーション内の関数を実行します。

クライアントツールを使うと、エージェントは接続中のアプリケーションでアクションをトリガーできます。たとえば、ページを開いたり、クライアント側の状態を読み取ったりできます。クライアントツールは [WebSocket API](/ja-jp/line/integrations/websocket-api) 経由でのみ利用できます。

モデルがクライアントツールを呼び出すと、サーバーは接続されたブラウザ、モバイルアプリ、またはサーバーに `client_tool_call` イベントを送信します。関数の実行後、応答が必要な場合は、その接続されたクライアントが [`client_tool_result`](/ja-jp/api-reference/agents/agent-websocket) をサーバーに送信します。

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

```json theme={null}
{
  "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`](/ja-jp/api-reference/agents/tools/create) でツールを作成し、その ID を `config.tools` でアタッチします。共有の実行設定については[ツール](/ja-jp/agents/tools#execution-settings)を参照してください。

## パラメータ

`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` を含む結果を送信します。

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

```javascript theme={null}
// 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 イベントリファレンス](/ja-jp/api-reference/agents/agent-websocket)を参照してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.