> ## 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.
# ツール
> 通話中にエージェントが呼び出せるアクションを与えます。
ツールを使うと、エージェントは通話の終了、発信者の転送、データの取得、別のアクションのトリガーができます。LLM は、ツールの名前、説明、会話の内容からツールを選択します。
ツールには 3 つの種類があります：
* **システムツール**は、通話の終了など、エージェント上で直接設定する Cartesia 組み込みのアクションです。
* **Webhook ツール**は、お客様のサーバー上で公開する HTTPS エンドポイントを呼び出します。HTTP リクエストは Cartesia が送信します。
* **クライアントツール**は、WebSocket API 経由で Cartesia に接続されたブラウザ、モバイルアプリ、またはサーバー内の関数を実行します。
## ツールをエージェントにアタッチする
Webhook ツールとクライアントツールは共有リソースです。[`POST /v1/agents/tools`](/ja-jp/api-reference/agents/tools/create) で作成し、その ID を `config.tools` に追加します。1 つのエージェントは最大 32 個のツールを参照できます。
`config.tools` への更新は、リスト全体を置き換えます。参照されているツールは、すべての現行エージェント設定から削除されるまで削除できません。
[システムツール](/ja-jp/agents/system-tools)は、`config.system_tools` で別途設定します。
## ツールを説明する
LLM は、ツールの `name` と `description` を使って、いつ呼び出すかを判断します。ツールが何をするか、いつ使うべきかを記述してください。
```text theme={null}
Looks up an order by its number. Use it when the caller asks about an order's status or delivery date.
```
## 実行設定
Webhook ツールとクライアントツールは、以下の設定を使用します：
| フィールド | 対象 | 値とデフォルト | 挙動 |
| - | - | - | - |
| `pre_tool_speech` | Webhook ツールとクライアントツール | 必須。`auto` または `force` を選択します。デフォルトはありません。 | `auto` は、先に話すかどうかをエージェントに任せます。`force` は、ツールを呼び出す前に話すよう求めます。 |
| `execution_mode` | Webhook ツールとクライアントツール | 必須。`immediate` または `async` を選択します。デフォルトはありません。 | `immediate` は現在の会話ターン内で実行され、発信者による割り込みが可能です。`async` は、ターンを完了できる状態のまま別途実行されます。 |
| `response_timeout_secs` | Webhook ツール、および結果を返す必要があるクライアントツール | `1` から `120` 秒。デフォルトは `20` です。 | Webhook エンドポイント、または接続されたブラウザ、モバイルアプリ、サーバーが結果を返すのを Cartesia が待つ最大時間です。 |
## 結果
システムツールは Cartesia が実行し、その結果を処理します。
Webhook ツールでは、テキスト形式のボディを持つ成功した HTTPS レスポンスの場合、そのボディが結果として LLM に渡されます。Cartesia はボディを 4096 バイトに制限し、それより長い場合は `[cut off: the response was longer than this tool returns]` を追加します。エンドポイントが 2xx 以外のステータスを返した場合、タイムアウトした場合、または到達できなかった場合、LLM はエラー結果を受け取り、会話は継続します。
結果を返す必要があるクライアントツールでは、接続されたブラウザ、モバイルアプリ、またはサーバーが WebSocket 接続経由で `client_tool_result` メッセージを送信します。`response_timeout_secs` までに結果が届かない場合、Cartesia は LLM に `Tool call timed out` を渡します。結果が 4096 バイトを超える場合、Cartesia はそれを `error_type` が `result_too_large` のエラー結果に置き換えます。
エージェント上で直接設定する組み込みアクション。
Cartesia がお客様のサーバーに送信する HTTP リクエスト。
WebSocket API 経由で、接続されたブラウザ、モバイルアプリ、またはサーバーが実行する関数。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.