Narzędzia kodowe

Narzędzia kodowe pozwalają agentowi uruchamiać własny JavaScript w odizolowanym środowisku po stronie serwera, bez tworzenia i hostowania własnego endpointu webhooka. Napisz logikę raz we wbudowanym edytorze kodu, a ElevenLabs uruchomi ją za każdym razem, gdy agent wywoła narzędzie.

Omówienie

Narzędzie kodowe to funkcja JavaScript uruchamiana, gdy agent ją wywoła. Piszesz całą treść funkcji, więc narzędzie może robić tyle, ile wymaga zadanie:

• Własne obliczenia: stosuj reguły cenowe, przeliczaj jednostki, twórz logikę punktacji lub wykonuj obliczenia na datach, korzystając tylko z parametrów wywołania narzędzia. Dostęp do sieci nie jest wymagany.
• Wywoływanie zewnętrznych API: używaj fetch dla domen z listy dozwolonych, z sekretami workspace’u i połączeniami uwierzytelniania dodanymi do kontekstu funkcji.
• Łączenie wielu źródeł: wywołaj dwa lub trzy API i połącz, porównaj lub uzgodnij ich wyniki przed zwróceniem jednej odpowiedzi.
• Rozgałęzienia warunkowe: uruchamiaj inną logikę zależnie od parametrów wywołania narzędzia, bez tworzenia osobnego narzędzia dla każdej gałęzi.
• Przekształcanie danych: zwracaj dokładnie taką strukturę, jaką agent ma zobaczyć, zamiast surowej odpowiedzi źródłowej.

Jak to działa

Twój kod to moduł JavaScript, który eksportuje jedną domyślną funkcję asynchroniczną. Funkcja otrzymuje obiekt ctx i zwraca wynik narzędzia:

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}!` };
};

Zwrócona wartość staje się wynikiem narzędzia. Jest przekazywana agentowi, wyświetlana w transkrypcji rozmowy i może służyć do dynamicznego przypisywania zmiennych.

Obiekt ctx

ctx to punkt dostępu do wszystkiego, z czego narzędzie może skorzystać podczas wywołania. Parametry przekazane przez agenta zawsze trafiają do ctx.args; sekrety, wartości konfiguracji i połączenia uwierzytelniania są opcjonalne i pojawiają się tylko wtedy, gdy przypiszesz je w sekcji Context object narzędzia.

Konfiguracja parametrów

Parametry to wartości przekazywane przez agenta podczas wywołania narzędzia. Trafiają do ctx.args. Zdefiniuj je w sekcji Parameters formularza konfiguracji narzędzia lub w edytorze kodu na karcie Params, w podkarcie Define Params. Każdy parametr ma typ danych, identyfikator i opis, którego agent używa, aby określić poprawną wartość z rozmowy. Twój kod odczytuje tę wartość pod identyfikatorem, takim jak ctx.args.appointment_datetime poniżej.

Konfiguracja obiektu kontekstu

Dodaj sekrety, wartości konfiguracji i połączenia uwierzytelniania w sekcji Context object narzędzia. Każdy wpis ma typ i nazwę. Panel pokazuje dokładny accessor dla każdego wpisu, na przykład ctx.secrets.DEMO_KEY poniżej.

Dostęp do sieci

Kod uruchamiany w sandboxie może łączyć się tylko z domenami wyraźnie dozwolonymi w twoim workspace’ie. Dodaj domeny, z którymi ma łączyć się kod, w ElevenAgents Settings, w sekcji Code Tool Network Access. Żądanie do każdej innej domeny zakończy się błędem.

Limity wykonywania

• Limit czasu: każde uruchomienie musi zakończyć się w czasie odpowiedzi skonfigurowanym dla narzędzia — od 1 do 30 sekund.
• Bez zewnętrznych pakietów: narzędzia kodowe obecnie działają bez zależności npm.

Testowanie kodu

Przed zapisaniem użyj Run w edytorze kodu, aby uruchomić kod z przykładowymi wartościami parametrów:

• Params — ustaw wartości testowe dla każdego parametru zdefiniowanego przez narzędzie.
• Output — zobacz zwrócony wynik lub błąd, jeśli wykonanie się nie powiodło.
• Logs — zobacz wszystko, co zapisano za pomocą console.log, console.warn lub console.error, a także czas kompilacji i wykonania.

Przewodnik

W tym przewodniku utworzymy narzędzie kodowe, które przelicza temperaturę i zwraca przyjazny, sformatowany tekst:

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` };
};

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.

Przykłady uwierzytelniania

Wywoływanie API z sekretem

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

Przypisz EXAMPLE_API_KEY do sekretu workspace’u w sekcji Context object narzędzia, a następnie dodaj api.example.com do Code Tool Network Access, aby umożliwić wysłanie żądania. Wartość, do której się odwołujesz, jest placeholderem: prawdziwy sekret jest podstawiany do nagłówka przy wysyłaniu żądania i nigdy nie jest widoczny dla twojego kodu.

Wywoływanie API z połączeniem uwierzytelniania 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();
};

Przypisz EXAMPLE_CRM do skonfigurowanego połączenia uwierzytelniania w sekcji Context object narzędzia. Wartość, do której się odwołujesz, jest placeholderem: prawdziwe dane uwierzytelniające są podstawiane do nagłówka przy wysyłaniu żądania i nigdy nie są widoczne dla twojego kodu.

Dobre praktyki

Nazywaj narzędzia intuicyjnie i dodawaj szczegółowe opisy

Jeśli asystent nie wywołuje właściwych narzędzi, być może trzeba zaktualizować ich nazwy i opisy, aby lepiej rozumiał, kiedy wybrać każde z nich. Nie używaj skrótów ani akronimów, by skracać nazwy narzędzi i argumentów.

Możesz też dodać szczegółowe opisy, kiedy należy wywołać dane narzędzie. W przypadku złożonych narzędzi warto opisać każdy argument, aby asystent wiedział, o co musi zapytać użytkownika, by uzyskać dany argument.

Nazywaj parametry narzędzi intuicyjnie i dodawaj szczegółowe opisy

Używaj jasnych, opisowych nazw parametrów narzędzi. Jeśli ma to zastosowanie, określ w opisie oczekiwany format parametru (np. YYYY-mm-dd lub dd/mm/yy dla daty).

Rozważ dodanie informacji o tym, jak i kiedy wywoływać narzędzia, do promptu systemowego asystenta

Jasne instrukcje w prompcie systemowym mogą znacznie poprawić trafność wywoływania narzędzi przez asystenta. Na przykład poprowadź asystenta instrukcjami takimi jak poniżej:

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

Dodaj kontekst w złożonych sytuacjach. Na przykład:

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

Wybór LLM

Wybór LLM ma znaczenie dla skuteczności wywołań funkcji. Niektóre LLM mogą mieć trudności z wyciąganiem istotnych parametrów z rozmowy.