Client tools: Cho phép trợ lý của bạn kích hoạt các thao tác phía client trong ElevenAgents

Client tools cho phép trợ lý của bạn thực thi các hàm phía client. Khác với những công cụ webhook, các công cụ này cho phép trợ lý thực hiện những hành động như kích hoạt sự kiện trình duyệt, chạy hàm phía client hoặc gửi thông báo đến giao diện người dùng.

Tổng quan

Các ứng dụng có thể yêu cầu trợ lý tương tác trực tiếp với môi trường của người dùng. Các công cụ phía client cung cấp cho trợ lý của bạn khả năng thực hiện những thao tác ngay tại phía client.

Dưới đây là một vài ví dụ về trường hợp các công cụ phía client tỏ ra hữu ích:

• Kích hoạt các sự kiện giao diện người dùng (UI): Cho phép trợ lý kích hoạt các sự kiện trình duyệt, chẳng hạn như thông báo (alert), hộp thoại (modal) hoặc thông báo đẩy (notification).
• Tương tác với DOM: Cho phép trợ lý thao tác với Document Object Model (DOM) để cập nhật nội dung động hoặc hướng dẫn người dùng thao tác trên các giao diện phức tạp.

Hướng dẫn

Điều kiện tiên quyết

• Một tài khoản ElevenLabs
• Một ElevenLabs Conversational Agent đã được cấu hình

1. Tạo một công cụ phía client mới

Cấu hình một công cụ phía client có tên là logMessage với một tham số bắt buộc kiểu chuỗi (string) là message (“Thông điệp cần ghi lại trong console”).

Truy cập vào agent dashboard của bạn. Trong mục Tools, nhấp vào Add Tool. Đảm bảo rằng Tool Type được đặt là Client. Sau đó, thực hiện cấu hình như sau:

Sau đó, tạo một tham số message mới với cấu hình sau:

2. Đăng ký công cụ client trong code của bạn

Không giống như các công cụ webhook, những công cụ client cần được đăng ký trong code của bạn.

Sử dụng code sau để đăng ký công cụ client:

Python

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

Tên công cụ và tham số trong cấu hình agent phân biệt chữ hoa chữ thường và phải khớp với những tên đã đăng ký trong code của bạn.

3. Kiểm thử

Bắt đầu một cuộc trò chuyện với agent của bạn và nói điều gì đó như:

Log a message to the console that says Hello World

Ghi một thông báo vào console có nội dung "Hello World"

Bạn sẽ thấy nhật ký Hello World xuất hiện trong console của mình.

4. Các bước tiếp theo

Bây giờ, bạn đã thiết lập một sự kiện phía client cơ bản, bạn có thể:

• Khám phá các công cụ phía client phức tạp hơn như mở cửa sổ modal, điều hướng đến các trang hoặc tương tác với DOM.
• Kết hợp các công cụ phía client với webhook phía server để tương tác toàn diện.
• Sử dụng các công cụ phía client để tăng cường sự tương tác của người dùng và cung cấp phản hồi theo thời gian thực trong những cuộc trò chuyện.

Truyền kết quả công cụ phía client vào ngữ cảnh cuộc trò chuyện

Khi bạn muốn agent của mình nhận dữ liệu từ một công cụ phía client, hãy đảm bảo rằng bạn đã chọn tùy chọn Wait for response (Chờ phản hồi) trong cấu hình công cụ.

Sau khi công cụ phía client được thêm vào, khi hàm được gọi, agent sẽ đợi phản hồi của nó và thêm phản hồi vào ngữ cảnh cuộc trò chuyện.

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,
    # ...
)

Trong ví dụ này, khi agent gọi hàm getCustomerDetails, hàm sẽ thực thi ở phía client và agent sẽ nhận được dữ liệu trả về; dữ liệu này sau đó được sử dụng như một phần của ngữ cảnh cuộc trò chuyện. Các giá trị từ phản hồi cũng có thể được gán cho những biến động nếu muốn, tương tự như cách hoạt động của các công cụ webhook. Lưu ý rằng các công cụ hệ thống không thể cập nhật các biến động.

Khắc phục sự cố

Công cụ không được kích hoạt

• Đảm bảo tên công cụ và tên tham số trong cấu hình agent khớp với những gì đã được khai báo trong code của bạn.
• Xem lại nhật ký cuộc trò chuyện trong dashboard của agent để xác nhận rằng công cụ đang được thực thi.

Lỗi trên console

• Mở console trình duyệt để kiểm tra xem có lỗi nào xảy ra không.
• Đảm bảo code của bạn có cơ chế xử lý lỗi cần thiết cho các tham số không xác định hoặc không mong đợi.

Các phương pháp hay nhất

Đặt tên công cụ một cách trực quan, kèm theo mô tả chi tiết

Nếu bạn thấy trợ lý không gọi đúng công cụ, có thể bạn cần cập nhật tên và mô tả công cụ để trợ lý hiểu rõ hơn khi nào nên chọn công cụ đó. Tránh sử dụng các từ viết tắt hoặc từ ghép viết tắt để rút ngắn tên công cụ và tên tham số.

Bạn cũng có thể cung cấp mô tả chi tiết về thời điểm nên gọi một công cụ. Đối với các công cụ phức tạp, hãy đưa vào mô tả cho từng tham số để giúp trợ lý biết cần hỏi người dùng thông tin gì nhằm thu thập tham số đó.

Đặt tên tham số công cụ một cách trực quan, kèm theo mô tả chi tiết

Sử dụng tên rõ ràng và mang tính mô tả cho các tham số công cụ. Nếu có thể, hãy chỉ rõ định dạng mong đợi cho tham số trong phần mô tả (ví dụ: YYYY-mm-dd hoặc dd/mm/yy cho ngày tháng).

Cân nhắc cung cấp thêm thông tin về cách thức và thời điểm gọi công cụ trong câu lệnh hệ thống (system prompt) của trợ lý

Việc cung cấp hướng dẫn rõ ràng trong câu lệnh hệ thống có thể cải thiện đáng kể độ chính xác khi trợ lý gọi công cụ. Ví dụ, hướng dẫn trợ lý bằng các chỉ dẫn như sau:

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

Sử dụng check_order_status khi người dùng hỏi về trạng thái đơn hàng của họ, chẳng hạn như 'Đơn hàng của tôi đang ở đâu?' hoặc 'Đơn hàng của tôi đã được gửi đi chưa?'.

Cung cấp ngữ cảnh cho các tình huống phức tạp. Ví dụ:

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

Trước khi lên lịch cuộc họp bằng schedule_meeting, hãy kiểm tra lịch của người dùng để xem thời gian trống bằng check_availability nhằm tránh xung đột lịch trình.

Lựa chọn LLM

Cần lưu ý rằng việc lựa chọn LLM đóng vai trò quan trọng đối với sự thành công của các lệnh gọi hàm. Một số LLM có thể gặp khó khăn trong việc trích xuất các tham số phù hợp từ nội dung cuộc hội thoại.