Code-Tools

Code-Tools ermöglichen Ihrem Agenten, benutzerdefiniertes JavaScript in einer isolierten serverseitigen Umgebung auszuführen, ohne dass Sie einen eigenen Webhook-Endpunkt bereitstellen und hosten müssen. Schreiben Sie die Logik einmal im integrierten Code-Editor, und ElevenLabs führt sie aus, sobald der Agent das Tool aufruft.

Übersicht

Ein Code-Tool ist eine JavaScript-Funktion, die ausgeführt wird, wenn der Agent sie aufruft. Sie schreiben den gesamten Funktionsrumpf, sodass das Tool je nach Aufgabe mehr oder weniger leisten kann:

• Benutzerdefinierte Berechnungen: Wenden Sie Preisregeln, Einheitenumrechnungen, Bewertungslogik oder Datumsberechnungen ausschließlich mit den Toolaufrufparametern an. Kein Netzwerkzugriff erforderlich.
• Externe APIs aufrufen: Nutzen Sie fetch für zugelassene Domains; Workspace-Secrets und Authentifizierungsverbindungen werden in den Kontext der Funktion eingefügt.
• Mehrere Quellen kombinieren: Rufen Sie zwei oder drei APIs auf und führen Sie deren Ergebnisse zusammen, vergleichen oder gleichen Sie sie ab, bevor Sie eine einzelne Antwort zurückgeben.
• Bedingte Verzweigungen: Führen Sie abhängig von den Toolaufrufparametern unterschiedliche Logik aus, ohne für jeden Zweig ein separates Tool zu benötigen.
• Daten umformen: Geben Sie genau die Struktur zurück, die der Agent sehen soll, statt einer unverarbeiteten Upstream-Antwort.

Funktionsweise

Ihr Code ist ein JavaScript-Modul, das eine einzelne asynchrone Standardfunktion exportiert. Die Funktion erhält ein ctx-Objekt und gibt das Ergebnis des Tools zurück:

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

Der zurückgegebene Wert wird zum Ergebnis des Tools. Er wird an den Agenten zurückgegeben, im Gesprächstranskript angezeigt und kann für die Zuweisung dynamischer Variablen verwendet werden.

Das ctx-Objekt

ctx ist Ihr Einstiegspunkt zu allem, worauf das Tool zum Zeitpunkt des Aufrufs zugreifen kann. Die vom Agenten bereitgestellten Parameter kommen immer in ctx.args an; Secrets, Konfigurationswerte und Authentifizierungsverbindungen sind optional und erscheinen nur, wenn Sie sie im Bereich Kontextobjekt des Tools zuordnen.

Parameter konfigurieren

Parameter sind die Werte, die der Agent beim Aufruf des Tools bereitstellt, und sie kommen in ctx.args an. Definieren Sie sie im Bereich Parameter des Tool-Konfigurationsformulars oder im Code-Editor auf dem Tab Params im Untertab Define Params. Jeder Parameter benötigt einen Datentyp, eine Kennung und eine Beschreibung, anhand derer der Agent den richtigen Wert aus dem Gespräch bestimmt. Ihr Code liest diesen Wert über die Kennung, beispielsweise ctx.args.appointment_datetime unten.

Kontextobjekt konfigurieren

Fügen Sie Secrets, Konfigurationswerte und Authentifizierungsverbindungen im Bereich Kontextobjekt des Tools hinzu. Jeder Eintrag benötigt einen Typ und einen Namen. Das Panel zeigt für jeden Eintrag den genauen Accessor, beispielsweise ctx.secrets.DEMO_KEY unten.

Netzwerkzugriff

Code, der in der Sandbox ausgeführt wird, kann nur Domains erreichen, die Ihr Workspace ausdrücklich zugelassen hat. Fügen Sie die Domains, die Ihr Code aufrufen muss, in den Allgemeinen Einstellungen Ihres Workspace unter Zugelassene Domains für Code-Tools hinzu. Eine Anfrage an jede andere Domain schlägt fehl.

Ausführungslimits

• Timeout: Jeder Durchlauf muss innerhalb des konfigurierten Antwort-Timeouts des Tools abgeschlossen sein, zwischen 1 und 30 Sekunden.
• Keine externen Pakete: Code-Tools werden derzeit ohne npm-Abhängigkeiten ausgeführt.

Code testen

Verwenden Sie vor dem Speichern im Code-Editor Run, um Ihren Code mit Beispielparameterwerten auszuführen:

• Params — Legen Sie Testwerte für jeden Parameter fest, den Ihr Tool definiert.
• Output — Sehen Sie das zurückgegebene Ergebnis oder den Fehler, falls die Ausführung fehlgeschlagen ist.
• Logs — Sehen Sie alles, was mit console.log, console.warn oder console.error geschrieben wurde, sowie Build- und Ausführungszeiten.

Anleitung

In dieser Anleitung erstellen wir ein Code-Tool, das eine Temperatur umrechnet und einen formatierten, verständlichen String zurückgibt:

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.

Authentifizierungsbeispiele

Eine API mit einem Secret aufrufen

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

Ordnen Sie EXAMPLE_API_KEY im Bereich Kontextobjekt des Tools einem Workspace-Secret zu und fügen Sie dann api.example.com unter Zugelassene Domains für Code-Tools hinzu, damit die Anfrage ausgehen darf. Der referenzierte Wert ist ein Platzhalter: Das tatsächliche Secret wird beim ausgehenden Aufruf in den Header eingefügt und ist für Ihren Code nie sichtbar.

Eine API mit einer OAuth-Authentifizierungsverbindung aufrufen

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

Ordnen Sie EXAMPLE_CRM im Bereich Kontextobjekt des Tools einer konfigurierten Authentifizierungsverbindung zu. Der referenzierte Wert ist ein Platzhalter: Die tatsächliche Berechtigung wird beim ausgehenden Aufruf in den Header eingefügt und ist für Ihren Code nie sichtbar.

Best Practices

Tools intuitiv benennen und detailliert beschreiben

Wenn der Assistent nicht die richtigen Tools aufruft, müssen Sie möglicherweise Tool-Namen und Beschreibungen anpassen, damit der Assistent besser versteht, wann er welches Tool auswählen soll. Vermeiden Sie Abkürzungen oder Akronyme, um Namen von Tools und Argumenten zu verkürzen.

Sie können auch detailliert beschreiben, wann ein Tool aufgerufen werden soll. Bei komplexen Tools sollten Sie jedes Argument beschreiben, damit der Assistent weiß, welche Informationen er vom Nutzer abfragen muss.

Tool-Parameter intuitiv benennen und detailliert beschreiben

Verwenden Sie klare und aussagekräftige Namen für Tool-Parameter. Geben Sie gegebenenfalls in der Beschreibung das erwartete Format eines Parameters an, zum Beispiel YYYY-mm-dd oder dd/mm/yy für ein Datum.

Erwägen Sie, im System-Prompt Ihres Assistenten zusätzliche Informationen dazu bereitzustellen, wie und wann Tools aufgerufen werden sollen

Klare Anweisungen in Ihrem System-Prompt können die Genauigkeit von Tool-Aufrufen deutlich verbessern. Leiten Sie den Assistenten beispielsweise mit Anweisungen wie den folgenden an:

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

Geben Sie bei komplexen Szenarien Kontext an. Zum Beispiel:

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

LLM-Auswahl

Die Wahl des LLM ist entscheidend für den Erfolg von Funktionsaufrufen. Einige LLMs haben Schwierigkeiten, die relevanten Parameter aus der Unterhaltung zu extrahieren.