客户端工具

客户端工具让助手能够执行客户端函数。与 webhook 工具不同，客户端工具可让助手执行触发浏览器事件、运行客户端函数或向 UI 发送通知等操作。

概述

应用可能需要助手直接与用户环境交互。客户端工具让助手能够执行客户端操作。

以下是一些适合使用客户端工具的示例：

• 触发 UI 事件：让助手触发浏览器事件，例如警报、模态框或通知。
• 与 DOM 交互：让助手操作文档对象模型（DOM），以动态更新内容或引导用户使用复杂界面。

指南

前提条件

• 一个 ElevenLabs 账户
• 已配置的 ElevenLabs 对话式 AI 智能体（在此创建）

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()

将客户端工具结果传递至对话上下文

如果希望智能体接收客户端工具返回的数据，请确保在工具配置中勾选 等待响应 选项。

添加客户端工具后，当调用该函数时，智能体会等待其响应，并将响应追加到对话上下文中。

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 选择

请注意，LLM 的选择会影响函数调用的成功率。某些 LLM 可能难以从对话中提取相关参数。