Code tools: Chạy logic JavaScript tùy chỉnh trực tiếp trên cơ sở hạ tầng của ElevenLabs

Code tools cho phép agent của bạn chạy code JavaScript tùy chỉnh trong một môi trường sandbox, giúp bạn không cần phải tự thiết lập và lưu trữ webhook endpoint. Bạn chỉ cần viết logic một lần trong trình soạn thảo code tích hợp sẵn, và ElevenLabs sẽ thực thi code đó mỗi khi agent gọi công cụ này.

Tổng quan

Công cụ code là một hàm JavaScript được thực thi khi agent gọi đến nó. Bạn có thể tự viết toàn bộ nội dung hàm, cho phép công cụ thực hiện các tác vụ từ đơn giản đến phức tạp tùy theo yêu cầu:

• Tính toán tùy chỉnh: Áp dụng quy tắc định giá, chuyển đổi đơn vị, logic chấm điểm hoặc tính toán ngày tháng chỉ dựa trên các tham số của lệnh gọi công cụ. Không yêu cầu truy cập mạng.

• Gọi API bên ngoài: Truy xuất dữ liệu từ các domain trong danh sách cho phép (allowlist), với các thông tin bí mật (secret) của không gian làm việc và kết nối xác thực được nạp sẵn vào ngữ cảnh của hàm.

• Kết hợp nhiều nguồn dữ liệu: Gọi hai hoặc ba API rồi hợp nhất, so sánh hoặc đối chiếu kết quả trước khi trả về một câu trả lời duy nhất.

• Phân nhánh có điều kiện: Thực thi các logic khác nhau tùy thuộc vào tham số của lệnh gọi công cụ mà không cần tạo công cụ riêng cho từng nhánh.

• Định dạng lại dữ liệu: Trả về cấu trúc dữ liệu chính xác mà bạn muốn agent nhận được, thay vì dữ liệu thô từ phản hồi ban đầu của API.

Cách thức hoạt động

Code của bạn là một mô-đun JavaScript xuất ra một hàm bất đồng bộ (async function) mặc định duy nhất. Hàm này nhận vào một đối tượng `ctx` và trả về kết quả của công cụ:

export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;
  return { message: `Hello from ${city}!` };
};

Giá trị mà bạn trả về sẽ trở thành kết quả của công cụ. Giá trị này được chuyển ngược lại cho agent, hiển thị trong nhật ký hội thoại và có thể được sử dụng để gán biến động.

Đối tượng ctx

ctx là điểm truy cập vào mọi thông tin mà công cụ có thể sử dụng tại thời điểm được gọi. Các tham số do agent cung cấp luôn nằm trong ctx.args; còn những thông tin bảo mật (secret), giá trị cấu hình và kết nối xác thực là tùy chọn và chỉ xuất hiện nếu bạn đã ánh xạ chúng trong phần Context object của công cụ.

Chỉ ctx.args là hiển thị với agent khi nó gọi công cụ. Các thông tin bí mật (secret), giá trị cấu hình và kết nối xác thực sẽ không bao giờ bị lộ cho agent.

Cấu hình tham số

Tham số là các giá trị mà agent cung cấp khi gọi công cụ và chúng được truyền vào ctx.args. Hãy định nghĩa chúng trong phần Parameters của biểu mẫu cấu hình công cụ, hoặc trong trình soạn thảo code tại tab Params, mục con Define Params. Mỗi tham số bao gồm kiểu dữ liệu, code định danh (identifier) ​​và mô tả để agent xác định giá trị chính xác từ cuộc hội thoại. Code của bạn sẽ đọc giá trị đó thông qua code định danh, ví dụ như ctx.args.appointment_datetime dưới đây.

Cấu hình Context object

Thêm các thông tin bí mật, giá trị cấu hình và kết nối xác thực vào phần Context object của công cụ. Mỗi mục cần có kiểu dữ liệu và tên. Bảng điều khiển sẽ hiển thị chính xác cách truy cập cho từng mục, ví dụ như ctx.secrets.DEMO_KEY dưới đây.

Truy cập mạng

Code chạy trong môi trường sandbox chỉ có thể truy cập các domain mà workspace của bạn đã cho phép một cách rõ ràng. Hãy thêm các domain mà code của bạn cần gọi vào phần Code Tool Network Access trong mục Settings của ElevenAgents. Mọi yêu cầu gửi đến các domain khác sẽ thất bại.

Giới hạn thực thi

• Timeout: Mỗi lần chạy phải hoàn tất trong khoảng thời gian chờ phản hồi đã cấu hình cho công cụ, từ 1 đến 30 giây.

• Không hỗ trợ gói bên ngoài: Hiện tại các công cụ code chạy mà không có những dependency npm.

Kiểm thử code của bạn

Trước khi lưu, hãy sử dụng chức năng Run trong trình soạn thảo code để thực thi code với các giá trị tham số mẫu:

• Params - thiết lập giá trị kiểm thử cho từng tham số mà công cụ của bạn định nghĩa.

• Output - xem kết quả trả về hoặc thông báo lỗi nếu quá trình thực thi thất bại.

• Logs - xem các nội dung được ghi lại bằng console.log, console.warn hoặc console.error, cùng với thời gian biên dịch và thực thi.

Hướng dẫn

Trong hướng dẫn này, chúng ta sẽ tạo một công cụ code có chức năng chuyển đổi nhiệt độ và trả về một chuỗi văn bản được định dạng thân thiện:

1. Tạo công cụ code mới

Tại phần Agent trên trang cài đặt agent, chọn Add Tool. Chọn Tool Type là Code, sau đó đặt tên và mô tả:

2. Xác định các tham số

Thêm hai tham số để LLM biết cần cung cấp những gì:

3. Viết code

Mở trình soạn thảo code và thay thế code nguồn mặc định bằng:

export default async (ctx) => {
  const { value, from_unit } = ctx.args;
  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }
  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};

Hãy sử dụng chức năng Run với một vài giá trị mẫu (ví dụ: value: 100, from_unit: "C") để kiểm tra kết quả đầu ra trước khi lưu.

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

Cập nhật câu lệnh hệ thống (system prompt) của agent để nó biết khi nào cần sử dụng công cụ:

When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.

Khi người dùng yêu cầu chuyển đổi nhiệt độ, hãy gọi hàm convert_temperature với
giá trị và đơn vị tương ứng ("C" hoặc "F"), sau đó đọc lại kết quả một cách tự nhiên.

5. Kiểm thử

Bắt đầu một cuộc trò chuyện và thử hỏi: 100 độ C đổi sang độ F là bao nhiêu?

Agent sẽ gọi công cụ và đọc lại giá trị đã được chuyển đổi.

Ví dụ về xác thực

Gọi API sử dụng key bí mật (secret)

export default async (ctx) => {
  const { order_id } = ctx.args;
  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Ánh xạ EXAMPLE_API_KEY tới một secret của không gian làm việc trong phần Context object của công cụ, sau đó thêm api.example.com vào mục Code Tool Network Access để cho phép yêu cầu được gửi ra ngoài. Giá trị mà bạn tham chiếu chỉ là một giá trị giữ chỗ: Secret thực sự sẽ được thay thế vào phần header khi yêu cầu được gửi đi và code của bạn sẽ không bao giờ nhìn thấy giá trị này.

Gọi API sử dụng kết nối xác thực OAuth

export default async (ctx) => {
  const { customer_id } = ctx.args;
  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Ánh xạ EXAMPLE_CRM tới một kết nối xác thực đã được cấu hình trong phần Context object của công cụ. Giá trị mà bạn tham chiếu chỉ là một phần giữ chỗ (placeholder): Thông tin xác thực thực tế sẽ được chèn vào phần header khi gửi yêu cầu đi và code của bạn sẽ không bao giờ nhìn thấy thông tin này.

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 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 gọn tên công cụ và tên tham số.

Bạn cũng có thể thêm 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 thêm mô tả cho từng tham số để giúp trợ lý biết cần hỏi người dùng những 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ủa công cụ. Nếu có thể, hãy nêu 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 lời nhắc 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 giao 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 mô hình LLM

Khi sử dụng các công cụ, bạn nên chọn các mô hình có khả năng xử lý cao (thông minh) 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 ảnh hưởng quan trọng đến 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ừ cuộc hội thoại.