> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Webhookツール **ツール**を使うと、アシスタントを外部データやシステムに接続できます。アシスタントが利用できるツールのセットを定義でき、会話に応じて適切なツールを使用します。 ## 概要 多くのアプリケーションでは、リアルタイム情報を取得するために、アシスタントが外部APIを呼び出す必要があります。ツールを使うと、アシスタントはサードパーティ製アプリへの外部関数呼び出しを行い、リアルタイム情報を取得できます。 ツールが役立つ例をいくつか紹介します。 * **データの取得**：ユーザーに回答する前に、アシスタントがREST対応データベースやサードパーティのインテグレーションからリアルタイムデータを取得できるようにします。 * **アクションの実行**：会議のスケジュール設定や注文の返品開始など、会話に基づいてアシスタントが認証済みのアクションをトリガーできるようにします。 > **Info** > > アプリケーションUIを操作したり、クライアント側イベントをトリガーしたりするには、代わりに[クライアント ツール](/docs/ja/eleven-agents/customization/tools/client-tools)を使用してください。 ## ツール設定 ElevenLabsエージェントには、外部APIと連携するためのツールを設定できます。従来のリクエストとは異なり、アシスタントは、会話と指定したパラメータ説明に基づいて、クエリ、本文、パスの各パラメータを動的に生成します。 すべてのツール設定とパラメータ説明は、アシスタントがこれらのツールを**いつ**、**どのように**使うかを判断するのに役立ちます。ツール利用を効果的にオーケストレーションするには、これらの呼び出しの順序とロジックを指定するよう、アシスタントのシステムプロンプトを更新してください。これには次の内容が含まれます。 * 使用する**ツール**と、その使用条件。 * ツールが適切に機能するために必要な**パラメータ**。 * 応答の**処理方法**。 \ #### 設定 ツールの目的を説明するために、大まかな`名前`と`説明`を定義します。これにより、LLMがツールを理解し、いつ呼び出すべきかを判断できます。 > **Info** > > APIでパスパラメータが必要な場合は、URLパス内の変数を中括弧`{}`で囲んで指定します。例：`id`がパスパラメータである場合、`/api/resource/{id}`。 ![設定](/docs/_fern-img/fb6e6619e4e7a5f19c2a86f9c2a489f5cb33cfb0883c14a06f0eec3cb35d71d5.webp) #### 認証 カスタムヘッダーを追加するか、認証接続による標準の認証方式を使用して認証を設定します。 ![ツール認証](/docs/_fern-img/5ffae070945a86b74975cd9b56679c2bb76f0ce70d05fe7b10e8e5dff6ddd630.webp) #### ヘッダー リクエストに含める必要があるヘッダーを指定します。 ![ヘッダー](/docs/_fern-img/9c8c3f2d42f84a6e40922a4c777199e79646b174fa51b9e4d5b21695d7da3f66.webp) #### パスパラメータ URLパス内の変数を中括弧`{}`で囲んで指定します。 * **例**：`id`がパスパラメータである場合、`/api/resource/{id}`。 ![パスパラメータ](/docs/_fern-img/12dde95654a12f8fd5894eefe2bdbebb8b819072d3589ed32ddd578997f53c1d.webp) #### 本文パラメータ リクエストに含める本文パラメータを指定します。 ![本文パラメータ](/docs/_fern-img/17627460d24323cc40f461196625d34a5825dbe85d684618be0bc46b11ff9205.webp) ### コンテンツタイプ リクエスト本文のエンコード形式を設定します。 * **JSON**（デフォルト）：本文パラメータを`application/json`として送信します * **URLエンコード**：本文パラメータを`application/x-www-form-urlencoded`として送信します URLエンコード形式は、次のようにフォームデータの送信が必要なAPIとのインテグレーションで便利です。 * フォームエンコードされたリクエストのみを受け付けるレガシーシステム * OAuthトークンエンドポイント * 決済処理API * 特定のコンテンツタイプ要件があるサードパーティインテグレーション > **Info** > > コンテンツタイプの設定は、本文パラメータを含むPOST、PUT、PATCHリクエストにのみ適用されます。 #### クエリパラメータ リクエストに含めるクエリパラメータを指定します。 ![クエリパラメータ](/docs/_fern-img/4127f87fe066cdaa71df0e6f75caa24ec8174e7d156c74b3c62ea9df98b9712e.webp) #### 動的変数の割り当て 会話の後続で使用するために、ツールの応答から更新する動的変数を指定します。 ![クエリパラメータ](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) ## ガイド このガイドでは、任意の場所のリアルタイム天気情報を提供できる天気アシスタントを作成します。アシスタントは地理に関する知識を使って場所の名前を座標に変換し、正確な天気データを取得します。 #### 天気ツールを設定する 天気ツールは、LLMから提供されるパスパラメータ`latitude`と`longitude`を使用して、`https://api.open-meteo.com/v1/forecast`にGETリクエストを送信します。 #### ダッシュボードから追加 エージェント設定ページの**エージェント**セクションで、**ツールを追加**を選択します。ツールタイプとして**Webhook**を選択し、次の値で天気APIインテグレーションを設定します。 | フィールド | 値 | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 名前 | get_weather | | 説明 | 場所の現在の天気予報を取得する | | メソッド | GET | | URL | [https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m](https://api.open-meteo.com/v1/forecast?latitude=\{latitude}\&longitude=\{longitude}\¤t=temperature_2m,wind_speed_10m\&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m) | `LLM Prompt`の値タイプで、2つのパスパラメータを追加します。 | データ型 | 識別子 | 説明 | | ------ | --------- | --------------- | | string | latitude | リクエストされた場所の緯度座標 | | string | longitude | リクエストされた場所の経度座標 | #### CLIから追加 #### ツール設定ファイルを作成する 次の内容を`tool_configs/get_weather.json`として保存します。 ```json { "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location" }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location" } } } } ``` #### ツールを追加する ```bash elevenlabs tools add "get_weather" --type "webhook" --config-path ./tool_configs/get_weather.json ``` #### エージェントからツールを参照する `agent_configs/.json`を編集し、ツールのIDを`conversation_config.agent.prompt.tool_ids`に追加してから、プッシュします。 ```bash elevenlabs agents push --agent "" ``` #### APIから追加 ```python from elevenlabs import ElevenLabs, ToolRequestModel elevenlabs = ElevenLabs() tool = elevenlabs.conversational_ai.tools.create( request=ToolRequestModel( tool_config={ "type": "webhook", "name": "get_weather", "description": "Gets the current weather forecast for a location", "api_schema": { "url": "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", "method": "GET", "path_params_schema": { "latitude": { "type": "string", "description": "The latitude coordinate for the requested location", }, "longitude": { "type": "string", "description": "The longitude coordinate for the requested location", }, }, }, } ) ) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": {"prompt": {"tool_ids": [tool.id]}}, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); const tool = await elevenlabs.conversationalAi.tools.create({ toolConfig: { type: "webhook", name: "get_weather", description: "Gets the current weather forecast for a location", apiSchema: { url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,wind_speed_10m", method: "GET", pathParamsSchema: { latitude: { type: "string", description: "The latitude coordinate for the requested location", }, longitude: { type: "string", description: "The longitude coordinate for the requested location", }, }, }, }, }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { prompt: { toolIds: [tool.id] } }, }, }); ``` > **Warning** > > このツールにAPIキーは必要ありません。必要な場合は、ヘッダーで渡し、シークレットとして保存してください。 #### オーケストレーション このシステムプロンプトで、天気に関する質問をインテリジェントに処理するようアシスタントを設定します。 **`System prompt`** ```plaintext System prompt You are a helpful conversational agent with access to a weather tool. When users ask about weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires a latitude and longitude - use your geographic knowledge to convert location names to coordinates accurately. Never ask users for coordinates - you must determine these yourself. Always report weather information conversationally, referring to locations by name only. For weather requests: 1. Extract the location from the user's message 2. Convert the location to coordinates and call get_weather 3. Present the information naturally and helpfully For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be concise, accurate, and helpful. First message: "Hey, how can I help you today?" ``` > **Success** > > さまざまな場所の天気について質問して、アシスタントをテストしてください。アシスタントは、特定の場所（「東京の天気は？」）を処理し、一般的な質問（「今日の天気はどう？」）の後には詳細を確認する必要があります。 ## サポートされる認証方式 ElevenLabs Agentsは、ツールを外部APIに安全に接続するための複数の認証方式をサポートしています。認証方式はエージェント設定で構成し、必要に応じて個々のツールに接続します。 ![ワークスペース認証接続](/docs/_fern-img/131f7e017f01eaba444cddc672efdb77415db1a4c3a39f05b92a1678c5cd68f1.webp) 設定後、これらの認証方式をツールに接続し、ツール設定でカスタムヘッダーを管理できます。 ![ツール認証接続](/docs/_fern-img/c018c5bf11266512a6d6157e33274b1a12f8c20768e5ab18da0f20f933f8aea9.webp) #### OAuth2クライアント認証情報 OAuth2のクライアント認証情報フローを自動で処理します。クライアントID、クライアントシークレット、トークンURL（例：`https://api.example.com/oauth/token`）を設定します。必要に応じて、スコープをカンマ区切りの値として指定し、追加のJSONパラメータを設定できます。エージェント設定ページの**エージェント**セクションにある**ワークスペース認証接続**で、**認証を追加**をクリックして設定します。 #### OAuth2 JWT OAuth 2.0 JWT BearerフローにJSON Web Token認証を使用します。JWT署名シークレット、トークンURL、アルゴリズム（デフォルト：HS256）が必要です。発行者、オーディエンス、サブジェクトを含むJWTクレームを設定します。必要に応じて、キーID、有効期限（デフォルト：3600秒）、スコープ、追加パラメータを設定できます。エージェント設定ページの**エージェント**セクションにある**ワークスペース認証接続**で、**認証を追加**をクリックして設定します。 #### 基本認証 HTTP Basic AuthをサポートするAPI向けのシンプルなユーザー名とパスワードによる認証です。エージェント設定ページの**エージェント**セクションにある**ワークスペース認証接続**で、**認証を追加**をクリックして設定します。 #### Bearerトークン Bearerトークンの値をリクエストヘッダーに追加する、トークンベースの認証です。ツール設定にヘッダーを追加し、ヘッダータイプとして**シークレット**を選択して、**新しいシークレットを作成**をクリックして設定します。 #### カスタムヘッダー 独自の認証方式のために、任意の名前と値でカスタム認証ヘッダーを追加します。ツール設定にヘッダーを追加し、**名前**と**値**を指定して設定します。 ## ベストプラクティス #### ツールには直感的な名前を付け、詳しく説明する アシスタントが適切なツールを呼び出さない場合は、各ツールをいつ選択すべきかをアシスタントがより明確に理解できるよう、ツール名と説明を更新する必要があるかもしれません。ツール名や引数名を短くするために、略語や頭字語を使用しないでください。 ツールをいつ呼び出すべきかについて、詳しい説明を含めることもできます。複雑なツールでは、各引数についての説明も含めると、アシスタントがその引数を収集するためにユーザーへ何を尋ねる必要があるかを把握しやすくなります。 #### ツールパラメータには直感的な名前を付け、詳しく説明する ツールパラメータには、明確で説明的な名前を使用してください。該当する場合は、説明内でパラメータに期待される形式を指定します（例：日付の場合はYYYY-mm-ddまたはdd/mm/yy）。 #### アシスタントのシステムプロンプトに、ツールを呼び出す方法とタイミングに関する追加情報を含めることを検討する システムプロンプトで明確な指示を与えると、アシスタントのツール呼び出し精度を大幅に向上させることができます。たとえば、以下のような指示でアシスタントをガイドします。 ```plaintext Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'. ``` 複雑なシナリオにはコンテキストを提供します。例： ```plaintext Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts. ``` #### LLMの選択 > **Warning** > > ツールを使用する場合は、GPT 6やClaude Sonnet 5.5のような高知能モデルを選択することをおすすめします。 LLMの選択は、関数呼び出しの成功に重要な影響を与えます。一部のLLMは、会話から関連するパラメータを抽出するのが難しい場合があります。 ## ツール呼び出し音 ツール実行中に再生する環境音を設定して、ユーザー体験を向上できます。詳しくは[ツール呼び出し音](/docs/ja/eleven-agents/customization/tools/tool-configuration/tool-call-sounds)をご覧ください。