Webhook tools: Kết nối trợ lý của bạn với dữ liệu và hệ thống bên ngoài trong ElevenAgents

Các công cụ cho phép trợ lý của bạn kết nối với dữ liệu và hệ thống bên ngoài. Bạn có thể xác định một tập hợp các công cụ mà trợ lý được phép truy cập, và trợ lý sẽ sử dụng chúng vào những thời điểm thích hợp dựa trên nội dung cuộc trò chuyện.

Tổng quan

Nhiều ứng dụng yêu cầu trợ lý phải gọi các API bên ngoài để lấy thông tin theo thời gian thực. Các công cụ cung cấp cho trợ lý khả năng thực hiện những lệnh gọi hàm tới ứng dụng của bên thứ ba, giúp bạn thu thập thông tin cập nhật tức thì.

Dưới đây là một số ví dụ về tính hữu ích của các công cụ:

• Truy xuất dữ liệu: Cho phép trợ lý lấy dữ liệu thời gian thực từ bất kỳ cơ sở dữ liệu hỗ trợ REST hoặc hệ thống tích hợp của bên thứ ba nào trước khi phản hồi người dùng.

• Thực hiện hành động: Cho phép trợ lý kích hoạt các hành động đã được xác thực dựa trên nội dung cuộc trò chuyện, chẳng hạn như lên lịch họp hoặc bắt đầu quy trình trả hàng.

Cấu hình công cụ

Các agent của ElevenLabs có thể được trang bị công cụ để tương tác với những API bên ngoài. Khác với các yêu cầu truyền thống, trợ lý sẽ tự động tạo những tham số truy vấn (query), phần thân (body) và đường dẫn (path) một cách linh hoạt dựa trên nội dung cuộc trò chuyện và các mô tả tham số mà bạn cung cấp.

Mọi cấu hình công cụ và mô tả tham số đều giúp trợ lý xác định thời điểm và cách thức sử dụng chúng. Để điều phối việc sử dụng công cụ hiệu quả, hãy cập nhật câu lệnh hệ thống (system prompt) của trợ lý nhằm quy định trình tự và logic thực hiện các lệnh gọi này. Nội dung này bao gồm:

• Công cụ nào cần sử dụng và trong điều kiện nào.

• Các tham số cần thiết để công cụ hoạt động chính xác.

• Cách xử lý các phản hồi nhận được.

Hãy xác định Name và Description tổng quát để làm rõ mục đích của công cụ. Việc này giúp mô hình ngôn ngữ lớn (LLM) hiểu được công cụ và biết khi nào cần gọi nó.

Nếu API yêu cầu tham số đường dẫn, hãy đưa các biến vào đường dẫn URL bằng cách đặt chúng trong dấu ngoặc nhọn {}, ví dụ: /api/resource/{id}, trong đó id là tham số đường dẫn.

Hướng dẫn

Trong phần hướng dẫn này, chúng ta sẽ tạo một trợ lý thời tiết có khả năng cung cấp thông tin thời tiết theo thời gian thực cho bất kỳ địa điểm nào. Trợ lý sẽ sử dụng kiến ​​thức địa lý của mình để chuyển đổi tên địa điểm thành tọa độ và truy xuất dữ liệu thời tiết chính xác.

1. Cấu hình công cụ thời tiết

Công cụ thời tiết sẽ gửi các yêu cầu GET tới https://api.open-meteo.com/v1/forecast với latitude và longitude đóng vai trò là các tham số đường dẫn do LLM cung cấp. 

Tại mục Agent trên trang cài đặt agent của bạn, hãy chọn Add Tool. Chọn Webhook làm Tool Type, sau đó cấu hình tích hợp API thời tiết với các giá trị sau:

Thêm hai tham số đường dẫn với kiểu giá trị là LLM Prompt:

2. Điều phối (Orchestration)

Hãy cấu hình trợ lý của bạn để xử lý các truy vấn về thời tiết một cách thông minh bằng câu lệnh hệ thống (system prompt) sau:

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?"

Bạn là một tác nhân hội thoại hữu ích, có quyền truy cập vào công cụ tra cứu thời tiết. Khi người dùng hỏi về
tình hình thời tiết, hãy sử dụng công cụ `get_weather` để lấy dữ liệu chính xác theo thời gian thực. Công cụ này yêu cầu
thông tin về vĩ độ và kinh độ - hãy sử dụng kiến ​​thức địa lý của bạn để chuyển đổi tên địa điểm thành tọa độ
một cách chính xác.
Tuyệt đối không yêu cầu người dùng cung cấp tọa độ - bạn phải tự xác định các thông tin này. Luôn trình bày thông tin
thời tiết theo phong cách trò chuyện tự nhiên và chỉ đề cập đến địa điểm bằng tên gọi. Đối với các yêu cầu về thời tiết:
1. Trích xuất địa điểm từ tin nhắn của người dùng
2. Chuyển đổi địa điểm thành tọa độ và gọi hàm `get_weather`
3. Trình bày thông tin một cách tự nhiên và hữu ích
Đối với các truy vấn không liên quan đến thời tiết, hãy hỗ trợ một cách thân thiện trong phạm vi kiến ​​thức của bạn. Luôn đảm bảo
sự ngắn gọn, chính xác và hữu ích.
Tin nhắn đầu tiên: "Xin chào, hôm nay tôi có thể giúp gì cho bạn?"

Hãy kiểm thử trợ lý bằng cách hỏi về thời tiết tại các địa điểm khác nhau. Trợ lý cần xử lý được các địa điểm cụ thể (“Thời tiết ở Tokyo thế nào?”) và yêu cầu làm rõ thông tin sau các câu hỏi chung (“Hôm nay thời tiết ra sao?”).

Các phương thức xác thực được hỗ trợ

ElevenLabs Agents hỗ trợ nhiều phương thức xác thực để kết nối an toàn các công cụ của bạn với các API bên ngoài. Các phương thức xác thực được cấu hình trong phần cài đặt agent và sau đó được kết nối với từng công cụ cụ thể khi cần thiết.

Sau khi cấu hình, bạn có thể kết nối các phương thức xác thực này với công cụ của mình và quản lý những header tùy chỉnh trong phần cấu hình công cụ:

OAuth2 Client Credentials

Tự động xử lý quy trình xác thực OAuth2 Client Credentials. Cấu hình bằng cách nhập Client ID, Client Secret và URL lấy token (ví dụ: https://api.example.com/oauth/token). Bạn có thể tùy chọn chỉ định các phạm vi (scope) dưới dạng danh sách phân tách bằng dấu phẩy và thêm những tham số JSON bổ sung. Thiết lập bằng cách nhấp vào Add Auth trong mục Workspace Auth Connections tại phần Agent trên trang cài đặt agent.

OAuth2 JWT

Sử dụng xác thực JSON Web Token cho quy trình OAuth 2.0 JWT Bearer. Yêu cầu secret dùng để ký JWT, URL lấy token và thuật toán (mặc định: HS256). Cấu hình các JWT claim bao gồm: Bên phát hành (issuer), đối tượng nhận (audience) và chủ thể (subject). Bạn cũng có thể tùy chọn thiết lập key ID, thời gian hết hạn (mặc định: 3600 giây), phạm vi truy cập (scope) và các tham số bổ sung. Thiết lập bằng cách nhấp vào Add Auth trong mục Workspace Auth Connections thuộc phần Agent trên trang cài đặt agent của bạn.

Xác thực cơ bản 

Phương thức xác thực đơn giản bằng tên người dùng và mật khẩu dành cho các API hỗ trợ HTTP Basic Auth. Thiết lập bằng cách nhấp vào Add Auth trong mục Workspace Auth Connections thuộc phần Agent trên trang cài đặt agent của bạn.

Bearer Tokens

Phương thức xác thực dựa trên token, trong đó giá trị bearer token được thêm vào tiêu đề (header) của yêu cầu. Cấu hình bằng cách thêm một tiêu đề vào phần cấu hình công cụ, chọn loại tiêu đề là Secret và nhấp vào Create New Secret.

Tiêu đề tùy chỉnh (Custom Headers)

Thêm các tiêu đề xác thực tùy chỉnh với tên và giá trị bất kỳ để sử dụng cho những phương thức xác thực đặc thù. Cấu hình bằng cách thêm tiêu đề vào phần cấu hình công cụ và chỉ định tên cũng như giá trị của tiêu đề đó.

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ần thiết, hãy cập nhật tên và mô tả công cụ để trợ lý hiểu rõ hơn về thời điểm cần chọn từng công cụ. Tránh sử dụng các từ viết tắt để rút gọn tên công cụ hoặc tên tham số.

Bạn cũng có thể cung cấp mô tả chi tiết về các trường hợp cần gọi công cụ. Đối với các công cụ phức tạp, hãy mô tả cụ thể từng tham số để 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 tham số rõ ràng và mang tính gợi hình. Nếu cần, hãy ghi rõ định dạng mong muốn cho tham số trong phần mô tả (ví dụ: YYYY-mm-dd hoặc dd/mm/yy đối với 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ãy 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, 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 bối 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 họp bằng `schedule_meeting`, hãy kiểm tra lịch của người dùng để xác định thời gian trống (sử dụng `check_availability`) nhằm tránh xung đột lịch trình.

Lựa chọn LLM

Khi sử dụng các công cụ, bài viết khuyến nghị chọn các mô hình có khả năng xử lý cao như GPT-6 hoặc Claude Sonnet 5.5.

Cần lưu ý rằng việc lựa chọn mô hình 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ố mô hình 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 trò chuyện.

Âm thanh khi gọi công cụ

Bạn có thể cấu hình âm thanh nền phát ra trong quá trình thực thi công cụ để nâng cao trải nghiệm người dùng.