設定ツール

クライアントツール

アシスタントがクライアント側の操作をトリガーできるようにします。

クライアントツールを使用すると、アシスタントはクライアント側の関数を実行できます。Webhookツールとは異なり、クライアントツールでは、ブラウザーイベントのトリガー、クライアント側の関数の実行、UIへの通知の送信などのアクションをアシスタントが実行できます。

概要

アプリケーションでは、アシスタントがユーザーの環境と直接やり取りする必要がある場合があります。クライアント側ツールにより、アシスタントはクライアント側の操作を実行できます。

クライアントツールが役立つ例をいくつか紹介します：

  • UIイベントのトリガー：アシスタントがアラート、モーダル、通知などのブラウザーイベントをトリガーできるようにします。
  • DOMとの操作：動的なコンテンツ更新や、複雑なインターフェースでのユーザー案内のために、アシスタントがDocument Object Model（DOM）を操作できるようにします。

サーバー側APIを呼び出すには、代わりにWebhook ツールを使用してください。

ガイド

前提条件

1

新しいクライアント側ツールを作成する

必須の文字列パラメーターmessage（「コンソールにログ出力するメッセージ」）を持つ、logMessageという名前のクライアントツールを設定します。

エージェントのダッシュボードに移動します。Toolsセクションで、Add Toolをクリックします。Tool TypeがClientに設定されていることを確認します。次のように設定してください：

設定パラメーター
名前logMessage
説明このクライアント側ツールを使用して、ユーザーのクライアントにメッセージをログ出力します。

次に、以下の設定で新しいパラメーターmessageを作成します：

設定パラメーター
データ型String
識別子message
必須true
説明コンソールにログ出力するメッセージ。メッセージが有益で関連性のあるものになるようにしてください。

logMessageクライアントツールの設定

2

コード内でクライアントツールを登録する

Webhookツールとは異なり、クライアントツールはコード内で登録する必要があります。

次のコードを使用してクライアントツールを登録します：

from elevenlabs import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
def log_message(parameters):
    message = parameters.get("message")
    print(message)
client_tools = ClientTools()
client_tools.register("logMessage", log_message)
conversation = Conversation(
    client=ElevenLabs(api_key="your-api-key"),
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    requires_auth=True,
    client_tools=client_tools,
    # ...
)
conversation.start_session()

エージェント設定内のツール名とパラメーター名は大文字と小文字が区別され、コード内で登録したものと必ず一致している必要があります。

3

テスト

エージェントとの会話を開始し、次のように話しかけます：

Hello Worldと書かれたメッセージをコンソールにログ出力して

コンソールにHello Worldのログが表示されます。

4

次のステップ

基本的なクライアント側イベントを設定したら、次のことができます：

  • モーダルを開く、ページに移動する、DOMとやり取りするなど、より複雑なクライアントツールを試す。
  • クライアントツールとサーバー側Webhookを組み合わせて、フルスタックのインタラクションを実現する。
  • クライアントツールを使用して、会話中のユーザーエンゲージメントを高め、リアルタイムのフィードバックを提供する。

クライアントツールの結果を会話コンテキストに渡す

エージェントがクライアントツールからデータを受け取るようにするには、ツール設定でWait for responseオプションにチェックを入れてください。

クライアントツール設定の「応答を待機」オプション

クライアントツールを追加すると、関数が呼び出された際にエージェントはその応答を待機し、応答を会話コンテキストに追加します。

def get_customer_details():
    # Fetch customer details (e.g., from an API or database)
    customer_data = {
        "id": 123,
        "name": "Alice",
        "subscription": "Pro"
    }
    # Return the customer data; it can also be a JSON string if needed.
    return customer_data
client_tools = ClientTools()
client_tools.register("getCustomerDetails", get_customer_details)
conversation = Conversation(
    client=ElevenLabs(api_key="your-api-key"),
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    requires_auth=True,
    client_tools=client_tools,
    # ...
)
conversation.start_session()

この例では、エージェントがgetCustomerDetailsを呼び出すと、関数がクライアント上で実行され、エージェントは返されたデータを受け取ります。このデータは会話コンテキストの一部として使用されます。応答の値は、Webhookツールと同様に、動的変数に任意で割り当てることもできます。なお、システムツールは動的変数を更新できません。

トラブルシューティング

  • エージェント設定内のツール名とパラメーター名が、コード内で登録したものと一致していることを確認してください。
  • エージェントのダッシュボードで会話の文字起こしを確認し、ツールが実行されていることを確認してください。
  • ブラウザーのコンソールを開き、エラーがないか確認してください。
  • 未定義または予期しないパラメーターに対して、コードに必要なエラー処理が実装されていることを確認してください。

ベストプラクティス

ツールには直感的な名前と詳しい説明を付ける

アシスタントが正しいツールを呼び出さない場合は、各ツールをいつ選択すべきかをより明確に理解できるよう、ツール名と説明を更新する必要があるかもしれません。ツール名や引数名を短縮するために、略語や頭字語を使用するのは避けてください。

ツールをいつ呼び出すべきかについて、詳しい説明を含めることもできます。複雑なツールでは、各引数の説明も含めることで、アシスタントがその引数を収集するためにユーザーへ何を尋ねる必要があるかを把握しやすくなります。

ツールパラメータには直感的な名前と詳しい説明を付ける

ツールパラメータには、明確でわかりやすい名前を使用してください。該当する場合は、説明内でパラメータに期待される形式を指定します（例：日付の場合はYYYY-mm-ddまたはdd/mm/yy）。

アシスタントの システムプロンプトに、ツールを呼び出す方法とタイミングに関する追加情報を含めることを検討する

システムプロンプトで明確な指示を与えると、アシスタントのツール呼び出し精度を大幅に改善できます。たとえば、次のような指示でアシスタントを導きます。

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?'.

複雑なシナリオにはコンテキストを提供してください。例：

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

LLMの選択

ツールを使用する場合は、GPT 5.2、Gemini-2.5-Flash、 Claude Sonnet 4.5などの高性能モデルを選び、Gemini-2.0-Flashは避けることをおすすめします。

LLMの選択は、関数呼び出しの成功に重要であることに注意してください。一部のLLMでは、会話から関連するパラメータを抽出するのが難しい場合があります。