Codetools

Codetools laten je agent aangepaste JavaScript uitvoeren in een gesandboxte serveromgeving, zonder dat je zelf een webhook-endpoint hoeft op te zetten en te hosten. Schrijf de logica één keer in de ingebouwde code-editor en ElevenLabs voert deze uit wanneer de agent de tool aanroept.

Overzicht

Een codetool is een JavaScript-functie die wordt uitgevoerd wanneer de agent deze aanroept. Je schrijft de volledige functiebody, dus de tool kan precies zoveel doen als de taak vereist:

• Aangepaste berekeningen: pas prijsregels, eenheidsconversies, scoringslogica of datumberekeningen toe met alleen de parameters van de toolaanroep. Geen netwerktoegang vereist.
• Externe API’s aanroepen: gebruik fetch vanaf domeinen op de allowlist, met workspacesecrets en auth connections die in de context van de functie worden geïnjecteerd.
• Meerdere bronnen combineren: roep twee of drie API’s aan en voeg de resultaten samen, vergelijk ze of stem ze op elkaar af voordat je één antwoord retourneert.
• Voorwaardelijke vertakkingen: voer verschillende logica uit afhankelijk van de parameters van de toolaanroep, zonder een aparte tool voor elke vertakking nodig te hebben.
• Gegevens herstructureren: retourneer precies de structuur die je de agent wilt laten zien, in plaats van een onbewerkte upstreamrespons.

Zo werkt het

Je code is een JavaScript-module die één standaard asynchrone functie exporteert. De functie ontvangt een ctx-object en retourneert het resultaat van de tool:

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

De waarde die je retourneert, wordt het resultaat van de tool. Deze wordt teruggestuurd naar de agent, weergegeven in het gesprekstranscript en kan worden gebruikt voor dynamische variabeletoewijzing.

Het ctx-object

ctx is je toegangspunt tot alles waartoe de tool op het moment van aanroepen toegang heeft. De parameters die de agent opgeeft, komen altijd binnen in ctx.args; secrets, configuratiewaarden en auth connections zijn optioneel en verschijnen alleen als je ze toewijst in de sectie Context object van de tool.

Parameters configureren

Parameters zijn de waarden die de agent opgeeft wanneer deze de tool aanroept; ze komen binnen in ctx.args. Definieer ze in de sectie Parameters van het configuratieformulier voor de tool, of in de code-editor op het tabblad Params, in het subtabblad Define Params. Elke parameter heeft een gegevenstype, een identifier en een beschrijving die de agent gebruikt om de juiste waarde uit het gesprek te bepalen. Je code leest die waarde via de identifier, zoals ctx.args.appointment_datetime hieronder.

Het contextobject configureren

Voeg secrets, configuratiewaarden en auth connections toe in de sectie Context object van de tool. Elke invoer heeft een type en een naam. Het paneel toont voor elke invoer de exacte accessor, zoals ctx.secrets.DEMO_KEY hieronder.

Netwerktoegang

Code die in de sandbox wordt uitgevoerd, kan alleen domeinen bereiken die je workspace expliciet heeft toegestaan. Voeg de domeinen die je code moet aanroepen toe in je ElevenAgents Settings, onder Code Tool Network Access. Een request naar elk ander domein mislukt.

Uitvoeringslimieten

• Time-out: elke uitvoering moet worden voltooid binnen de geconfigureerde responstime-out van de tool, van 1 tot 30 seconden.
• Geen externe packages: codetools worden momenteel uitgevoerd zonder npm-dependencies.

Je code testen

Gebruik vóór het opslaan Run in de code-editor om je code uit te voeren met voorbeeldwaarden voor parameters:

• Params — stel testwaarden in voor elke parameter die je tool definieert.
• Output — bekijk het geretourneerde resultaat, of de fout als de uitvoering is mislukt.
• Logs — bekijk alles wat is geschreven met console.log, console.warn of console.error, plus de tijd voor build en uitvoering.

Handleiding

In deze handleiding maken we een codetool die een temperatuur omzet en een vriendelijke, opgemaakte tekenreeks retourneert:

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.

Authenticatievoorbeelden

Een API aanroepen met een 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();
};

Wijs EXAMPLE_API_KEY toe aan een workspacesecret in de sectie Context object van de tool en voeg vervolgens api.example.com toe aan Code Tool Network Access zodat het request egress mag uitvoeren. De waarde waarnaar je verwijst is een placeholder: het echte secret wordt bij egress in de header vervangen en is nooit zichtbaar voor je code.

Een API aanroepen met een OAuth-auth connection

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

Wijs EXAMPLE_CRM toe aan een geconfigureerde auth connection in de sectie Context object van de tool. De waarde waarnaar je verwijst is een placeholder: de echte inloggegevens worden bij egress in de header vervangen en zijn nooit zichtbaar voor je code.

Best practices

Geef tools intuïtieve namen met gedetailleerde beschrijvingen

Als je merkt dat de assistent niet de juiste tools aanroept, moet je mogelijk de toolnamen en beschrijvingen bijwerken zodat de assistent duidelijker begrijpt wanneer elke tool moet worden geselecteerd. Gebruik geen afkortingen of acroniemen om tool- en argumentnamen in te korten.

Je kunt ook gedetailleerd beschrijven wanneer een tool moet worden aangeroepen. Bij complexe tools moet je beschrijvingen voor elk argument opnemen, zodat de assistent weet welke informatie hij aan de gebruiker moet vragen om dat argument te verzamelen.

Geef toolparameters intuïtieve namen met gedetailleerde beschrijvingen

Gebruik duidelijke en beschrijvende namen voor toolparameters. Geef indien van toepassing in de beschrijving de verwachte indeling voor een parameter op (bijvoorbeeld YYYY-mm-dd of dd/mm/yy voor een datum).

Overweeg om in de systeemprompt van je assistent aanvullende informatie te geven over hoe en wanneer tools moeten worden aangeroepen

Duidelijke instructies in je systeemprompt kunnen de nauwkeurigheid van toolaanroepen door de assistent aanzienlijk verbeteren. Geef de assistent bijvoorbeeld instructies zoals de volgende:

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

Geef context voor complexe scenario’s. Bijvoorbeeld:

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

LLM-selectie

Het is belangrijk om te weten dat de keuze van LLM bepalend is voor het succes van functieaanroepen. Sommige LLM’s kunnen moeite hebben met het extraheren van de relevante parameters uit het gesprek.