> 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ツール](/docs/ja/eleven-agents/customization/tools/webhook-tools)とは異なり、クライアントツールでは、ブラウザーイベントのトリガー、クライアント側の関数の実行、UIへの通知の送信などのアクションをアシスタントが実行できます。

## 概要

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

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

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

> **Info**
>
> サーバー側APIを呼び出すには、代わりに[Webhook ツール](/docs/ja/eleven-agents/customization/tools/webhook-tools)を使用してください。

## ガイド

### 前提条件

* [ElevenLabsアカウント](https://elevenlabs.io)
* 設定済みのElevenLabs会話型エージェント（[こちらで作成](https://elevenlabs.io/app/agents)）

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

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

#### ダッシュボードから追加

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

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

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

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

![logMessageクライアントツールの設定](/docs/_fern-img/f7ed25d49a2a814b76112f3e385d471e0dc8444705e11f2f6fad0bd23f1eae12.webp)

#### CLIから追加

#### ツール設定ファイルを作成する

次の内容を`tool_configs/log_message.json`として保存します：

```json
{
  "type": "client",
  "name": "logMessage",
  "description": "Use this client-side tool to log a message to the user's client.",
  "expects_response": false,
  "parameters": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "The message to log in the console."
      }
    },
    "required": ["message"]
  }
}
```

#### ツールを追加する

```bash
elevenlabs tools add "logMessage" --type "client" --config-path ./tool_configs/log_message.json
```

#### エージェントからツールを参照する

`agent_configs/<agent-name>.json`を編集して`conversation_config.agent.prompt.tool_ids`にツールのIDを追加し、プッシュします：

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### APIから追加

```python
from elevenlabs import ElevenLabs, ToolRequestModel

elevenlabs = ElevenLabs()

tool = elevenlabs.conversational_ai.tools.create(
    request=ToolRequestModel(
        tool_config={
            "type": "client",
            "name": "logMessage",
            "description": "Use this client-side tool to log a message to the user's client.",
            "expects_response": False,
            "parameters": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "description": "The message to log in the console.",
                    }
                },
                "required": ["message"],
            },
        }
    )
)

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: "client",
    name: "logMessage",
    description: "Use this client-side tool to log a message to the user's client.",
    expectsResponse: false,
    parameters: {
      type: "object",
      properties: {
        message: {
          type: "string",
          description: "The message to log in the console.",
        },
      },
      required: ["message"],
    },
  },
});

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: { prompt: { toolIds: [tool.id] } },
  },
});
```

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

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

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

**`Python`**

```python title="Python" focus={4-16}
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()
```

**`JavaScript`**

```javascript title="JavaScript" focus={2-10}
// ...
const conversation = await Conversation.startSession({
  // ...
  clientTools: {
    logMessage: async ({message}) => {
      console.log(message);
    }
  },
  // ...
});
```

**`Swift`**

```swift title="Swift" focus={2-10}
// ...
var clientTools = ElevenLabsSDK.ClientTools()

clientTools.register("logMessage") { parameters async throws -> String? in
    guard let message = parameters["message"] as? String else {
        throw ElevenLabsSDK.ClientToolError.invalidParameters
    }
    print(message)
    return message
}
```

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

#### テスト

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

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

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

#### 次のステップ

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

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

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

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

![クライアントツール設定の「応答を待機」オプション](/docs/_fern-img/0ecc615fc9f25446b67369fd3e010e34b39549a22146a2483ea17251206caf1e.webp)

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

**`Python`**

```python title="Python"
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()
```

**`JavaScript`**

```javascript title="JavaScript"
const clientTools = {
  getCustomerDetails: async () => {
    // Fetch customer details (e.g., from an API)
    const customerData = {
      id: 123,
      name: "Alice",
      subscription: "Pro"
    };
    // Return data directly to the agent.
    return customerData;
  }
};

// Start the conversation with client tools configured.
const conversation = await Conversation.startSession({ clientTools });
```

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

### トラブルシューティング

#### ツールがトリガーされない

* エージェント設定内のツール名とパラメーター名が、コード内で登録したものと一致していることを確認してください。
* エージェントのダッシュボードで会話の文字起こしを確認し、ツールが実行されていることを確認してください。

#### コンソールエラー

* ブラウザーのコンソールを開き、エラーがないか確認してください。
* 未定義または予期しないパラメーターに対して、コードに必要なエラー処理が実装されていることを確認してください。

## ベストプラクティス

#### ツールには直感的な名前を付け、詳しく説明する

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

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

#### ツールパラメータには直感的な名前を付け、詳しく説明する

ツールパラメータには、明確で説明的な名前を使用してください。該当する場合は、説明内でパラメータに期待される形式を指定します（例：日付の場合は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は、会話から関連するパラメータを抽出するのが難しい場合があります。