Kodverktyg

Kodverktyg låter din agent köra anpassad JavaScript i en isolerad servermiljö, utan att du behöver sätta upp och drifta en egen webhook-slutpunkt. Skriv logiken en gång i den inbyggda kոդredigeraren, så kör ElevenLabs den varje gång agenten anropar verktyget.

Översikt

Ett kodverktyg är en JavaScript-funktion som körs när agenten anropar den. Du skriver hela funktionskroppen, så verktyget kan göra så mycket eller lite som uppgiften kräver:

• Anpassade beräkningar: tillämpa prisregler, enhetsomvandlingar, poänglogik eller datumberäkningar med enbart parametrarna i verktygsanropet. Ingen nätverksåtkomst krävs.
• Anropa externa API:er: använd fetch från tillåtna domäner, med arbetsytehemligheter och autentiseringsanslutningar injicerade i funktionens kontext.
• Kombinera flera källor: anropa två eller tre API:er och slå ihop, jämför eller stäm av resultaten innan du returnerar ett enda svar.
• Villkorsstyrd förgrening: kör olika logik beroende på parametrarna i verktygsanropet, utan att behöva ett separat verktyg per gren.
• Omforma data: returnera exakt den struktur som du vill att agenten ska se, i stället för ett rått uppströmssvar.

Så fungerar det

Din kod är en JavaScript-modul som exporterar en enda asynkron standardfunktion. Funktionen tar emot ett ctx-objekt och returnerar verktygets resultat:

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

Värdet du returnerar blir verktygets resultat. Det skickas tillbaka till agenten, visas i samtalstranskriptet och kan användas för dynamisk variabeltilldelning.

Objektet ctx

ctx är din ingång till allt som verktyget kan komma åt vid anropstillfället. Parametrarna som agenten anger kommer alltid i ctx.args; hemligheter, konfigurationsvärden och autentiseringsanslutningar är valfria och visas endast om du mappar dem i verktygets avsnitt Kontextobjekt.

Konfigurera parametrar

Parametrar är de värden agenten tillhandahåller när den anropar verktyget, och de kommer i ctx.args. Definiera dem i avsnittet Parametrar i formuläret för verktygskonfigurationen eller i kodredigeraren på fliken Parametrar, under underfliken Definiera parametrar. Varje parameter har en datatyp, en identifierare och en beskrivning som agenten använder för att avgöra rätt värde utifrån samtalet. Din kod läser värdet via identifieraren, exempelvis ctx.args.appointment_datetime nedan.

Konfigurera kontextobjektet

Lägg till hemligheter, konfigurationsvärden och autentiseringsanslutningar i verktygets avsnitt Kontextobjekt. Varje post har en typ och ett namn. Panelen visar den exakta åtkomstmetoden för varje post, exempelvis ctx.secrets.DEMO_KEY nedan.

Nätverksåtkomst

Kod som körs i sandboxen kan endast nå domäner som din arbetsyta uttryckligen har tillåtit. Lägg till de domäner som din kod behöver anropa i dina ElevenAgents-inställningar, under Nätverksåtkomst för kodverktyg. En begäran till en annan domän misslyckas.

Körningsgränser

• Tidsgräns: varje körning måste slutföras inom verktygets konfigurerade svarstidsgräns, från 1 till 30 sekunder.
• Inga externa paket: kodverktyg körs för närvarande utan npm-beroenden.

Testa din kod

Innan du sparar kan du använda Kör i kodredigeraren för att köra koden med exempelvärden för parametrar:

• Parametrar — ange testvärden för varje parameter som verktyget definierar.
• Utdata — se det returnerade resultatet eller felet om körningen misslyckades.
• Loggar — se allt som skrivits med console.log, console.warn eller console.error, samt tider för bygge och körning.

Guide

I den här guiden skapar vi ett kodverktyg som omvandlar en temperatur och returnerar en vänlig, formaterad strä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` };
};

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.

Exempel på autentisering

Anropa ett API med en hemlighet

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

Mappa EXAMPLE_API_KEY till en arbetsytehemlighet i verktygets avsnitt Kontextobjekt och lägg sedan till api.example.com i Nätverksåtkomst för kodverktyg så att begäran tillåts gå ut. Värdet du refererar till är en platshållare: den verkliga hemligheten ersätts i huvudet vid utgående trafik och är aldrig synlig för din kod.

Anropa ett API med en OAuth-autentiseringsanslutning

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

Mappa EXAMPLE_CRM till en konfigurerad autentiseringsanslutning i verktygets avsnitt Kontextobjekt. Värdet du refererar till är en platshållare: den verkliga autentiseringsuppgiften ersätts i huvudet vid utgående trafik och är aldrig synlig för din kod.

Bästa praxis

Namnge verktyg intuitivt och med detaljerade beskrivningar

Om assistenten inte anropar rätt verktyg kan du behöva uppdatera verktygsnamnen och beskrivningarna så att assistenten tydligare förstår när varje verktyg ska väljas. Undvik att använda förkortningar eller akronymer för att förkorta namn på verktyg och argument.

Du kan också inkludera detaljerade beskrivningar av när ett verktyg ska anropas. För komplexa verktyg bör du inkludera beskrivningar för varje argument för att hjälpa assistenten förstå vad den behöver fråga användaren om för att samla in argumentet.

Namnge verktygsparametrar intuitivt och med detaljerade beskrivningar

Använd tydliga och beskrivande namn för verktygsparametrar. Ange vid behov det förväntade formatet för en parameter i beskrivningen (t.ex. YYYY-mm-dd eller dd/mm/yy för ett datum).

Överväg att ge ytterligare information om hur och när verktyg ska anropas i assistentens systemprompt

Tydliga instruktioner i systemprompten kan avsevärt förbättra assistentens precision vid verktygsanrop. Du kan till exempel vägleda assistenten med instruktioner som följande:

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

Ge kontext för komplexa scenarier. Till exempel:

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

Val av LLM

Det är viktigt att notera att valet av LLM påverkar hur väl funktionsanrop lyckas. Vissa LLM:er kan ha svårt att extrahera relevanta parametrar från konversationen.