Code-Tools

Code-Tools ermöglichen Ihrem Agenten, eigenes JavaScript in einer isolierten serverseitigen Umgebung auszuführen, ohne dass Sie einen eigenen Webhook-Endpunkt einrichten und hosten müssen. Schreiben Sie die Logik einmal im integrierten Code-Editor, und ElevenLabs führt sie aus, wann immer 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 Funktionskörper, sodass das Tool je nach Aufgabe mehr oder weniger leisten kann:

• Eigene Berechnungen: Wenden Sie Preisregeln, Einheitenumrechnungen, Bewertungslogik oder Datumsberechnungen nur mit den Tool-Aufrufparametern an. Kein Netzwerkzugriff erforderlich.
• Externe APIs aufrufen: Verwenden Sie fetch für freigegebene Domains, wobei Workspace-Secrets und Auth-Verbindungen in den Kontext der Funktion eingefügt werden.
• 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 je nach Tool-Aufrufparametern 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.

So funktioniert es

Ihr Code ist ein JavaScript-Modul, das eine einzelne standardmäßige asynchrone Funktion 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 dynamische Zuweisung von Variablen verwendet werden.

Das ctx-Objekt

ctx ist Ihr Zugang zu allem, worauf das Tool zum Zeitpunkt des Aufrufs zugreifen kann. Die vom Agenten bereitgestellten Parameter treffen immer in ctx.args ein; Secrets, Konfigurationswerte und Auth-Verbindungen sind optional und erscheinen nur, wenn Sie sie im Abschnitt Context object des Tools zuordnen.

Parameter konfigurieren

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

Kontextobjekt konfigurieren

Fügen Sie Secrets, Konfigurationswerte und Auth-Verbindungen im Abschnitt Context object des Tools hinzu. Jeder Eintrag benötigt einen Typ und einen Namen. Das Bedienfeld zeigt für jeden Eintrag den exakten Accessor an, etwa ctx.secrets.DEMO_KEY unten.

Netzwerkzugriff

Code, der in der Sandbox ausgeführt wird, kann nur Domains erreichen, die Ihr Workspace ausdrücklich freigegeben hat. Fügen Sie die Domains, die Ihr Code aufrufen muss, in den ElevenAgents Settings unter Code Tool Network Access hinzu. Anfragen an andere Domains schlagen fehl.

Ausführungslimits

• Timeout: Jede Ausführung muss innerhalb des für das Tool konfigurierten Antwort-Timeouts von 1 bis 30 Sekunden abgeschlossen sein.
• 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

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 Abschnitt Context object des Tools einem Workspace-Secret zu und fügen Sie dann api.example.com zu Code Tool Network Access hinzu, damit die Anfrage ausgeleitet werden darf. Der referenzierte Wert ist ein Platzhalter: Das echte Secret wird beim Ausleiten in den Header eingefügt und ist für Ihren Code nie sichtbar.

API mit einer OAuth-Auth-Verbindung 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 Abschnitt Context object des Tools einer konfigurierten Auth-Verbindung zu. Der referenzierte Wert ist ein Platzhalter: Die echten Zugangsdaten werden beim Ausleiten in den Header eingefügt und sind 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 die Namen und Beschreibungen Ihrer Tools aktualisieren, damit der Assistent klarer versteht, wann er welches Tool auswählen soll. Vermeiden Sie Abkürzungen oder Akronyme, um Tool- und Argumentnamen 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 Angaben er vom Nutzer erfragen muss.

Tool-Parameter intuitiv benennen und detailliert beschreiben

Verwenden Sie klare und aussagekräftige Namen für Tool-Parameter. Geben Sie in der Beschreibung gegebenenfalls das erwartete Format eines Parameters an (z. B. 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 des Assistenten 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 Kontext für komplexe Szenarien. 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 möglicherweise Schwierigkeiten, die relevanten Parameter aus dem Gespräch zu extrahieren.