Outils de code

Les outils de code permettent à votre agent d’exécuter du JavaScript personnalisé dans un environnement côté serveur isolé, sans avoir à déployer ni héberger votre propre endpoint webhook. Écrivez la logique une seule fois dans l’éditeur de code intégré, et ElevenLabs l’exécute chaque fois que l’agent appelle l’outil.

Vue d’ensemble

Un outil de code est une fonction JavaScript qui s’exécute lorsque l’agent l’appelle. Vous écrivez l’intégralité du corps de la fonction : l’outil peut donc faire plus ou moins selon les besoins de la tâche :

• Calculs personnalisés : appliquez des règles tarifaires, des conversions d’unités, une logique de notation ou des calculs de dates uniquement à l’aide des paramètres d’appel de l’outil. Aucun accès réseau n’est requis.
• Appels d’API externes : utilisez fetch depuis des domaines autorisés, avec les secrets du Workspace et les connexions d’authentification injectés dans le contexte de la fonction.
• Combinaison de plusieurs sources : appelez deux ou trois API et fusionnez, comparez ou rapprochez leurs résultats avant de renvoyer une réponse unique.
• Branchements conditionnels : exécutez une logique différente selon les paramètres d’appel de l’outil, sans nécessiter un outil distinct par branchement.
• Restructuration des données : renvoyez exactement la structure que vous souhaitez présenter à l’agent, plutôt qu’une réponse brute en amont.

Fonctionnement

Votre code est un module JavaScript qui exporte une unique fonction asynchrone par défaut. Cette fonction reçoit un objet ctx et renvoie le résultat de l’outil :

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

La valeur renvoyée devient le résultat de l’outil. Elle est transmise à l’agent, affichée dans la transcription de la conversation et peut servir à l’attribution dynamique de variables.

L’objet ctx

ctx est votre point d’accès à tout ce que l’outil peut consulter au moment de l’appel. Les paramètres fournis par l’agent arrivent toujours dans ctx.args ; les secrets, valeurs de configuration et connexions d’authentification sont facultatifs et n’apparaissent que si vous les associez dans la section Context object de l’outil.

Configuration des paramètres

Les paramètres sont les valeurs fournies par l’agent lorsqu’il appelle l’outil, et ils arrivent dans ctx.args. Définissez-les dans la section Parameters du formulaire de configuration de l’outil, ou dans l’éditeur de code, sous l’onglet Params, dans le sous-onglet Define Params. Chaque paramètre comprend un type de données, un identifiant et une description que l’agent utilise pour déterminer la valeur appropriée à partir de la conversation. Votre code lit cette valeur sous l’identifiant, comme ctx.args.appointment_datetime ci-dessous.

Configuration de l’objet de contexte

Ajoutez des secrets, des valeurs de configuration et des connexions d’authentification dans la section Context object de l’outil. Chaque entrée comprend un type et un nom. Le panneau affiche l’accesseur exact de chaque entrée, comme ctx.secrets.DEMO_KEY ci-dessous.

Accès réseau

Le code exécuté dans le sandbox ne peut atteindre que les domaines que votre Workspace a explicitement autorisés. Ajoutez les domaines que votre code doit appeler dans vos ElevenAgents Settings, sous Code Tool Network Access. Toute requête vers un autre domaine échoue.

Limites d’exécution

• Délai d’expiration : chaque exécution doit se terminer dans le délai de réponse configuré pour l’outil, de 1 à 30 secondes.
• Aucun package externe : les outils de code s’exécutent actuellement sans dépendances npm.

Tester votre code

Avant d’enregistrer, utilisez Run dans l’éditeur de code pour exécuter votre code avec des valeurs de paramètres d’exemple :

• Params : définissez des valeurs de test pour chaque paramètre défini par votre outil.
• Output : consultez le résultat renvoyé ou l’erreur si l’exécution a échoué.
• Logs : consultez tout ce qui est écrit avec console.log, console.warn ou console.error, ainsi que les durées de compilation et d’exécution.

Guide

Dans ce guide, nous allons créer un outil de code qui convertit une température et renvoie une chaîne conviviale et formatée :

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.

Exemples d’authentification

Appeler une API avec un 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();
};

Associez EXAMPLE_API_KEY à un secret du Workspace dans la section Context object de l’outil, puis ajoutez api.example.com à Code Tool Network Access pour autoriser la sortie de la requête. La valeur à laquelle vous faites référence est un espace réservé : le vrai secret est substitué dans l’en-tête à la sortie et n’est jamais visible par votre code.

Appeler une API avec une connexion d’authentification 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();
};

Associez EXAMPLE_CRM à une connexion d’authentification configurée dans la section Context object de l’outil. La valeur à laquelle vous faites référence est un espace réservé : l’identifiant réel est substitué dans l’en-tête à la sortie et n’est jamais visible par votre code.

Bonnes pratiques

Nommez les outils de manière intuitive, avec des descriptions détaillées

Si vous constatez que l’assistant n’appelle pas les bons outils, vous devrez peut-être mettre à jour les noms et descriptions de vos outils afin qu’il comprenne plus clairement quand sélectionner chaque outil. Évitez d’utiliser des abréviations ou des acronymes pour raccourcir les noms des outils et des arguments.

Vous pouvez également inclure des descriptions détaillées indiquant quand un outil doit être appelé. Pour les outils complexes, incluez des descriptions pour chacun des arguments afin d’aider l’assistant à savoir ce qu’il doit demander à l’utilisateur pour recueillir cet argument.

Nommez les paramètres des outils de manière intuitive, avec des descriptions détaillées

Utilisez des noms clairs et descriptifs pour les paramètres des outils. Le cas échéant, précisez dans la description le format attendu pour un paramètre, par exemple YYYY-mm-dd ou dd/mm/yy pour une date.

Envisagez de fournir des informations supplémentaires sur la manière et le moment d’appeler les outils dans le prompt système de votre assistant

Des instructions claires dans votre prompt système peuvent améliorer considérablement la précision des appels d’outils de l’assistant. Par exemple, guidez l’assistant avec des instructions comme celles-ci :

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

Fournissez du contexte pour les scénarios complexes. Par exemple :

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

Sélection du LLM

Il est important de noter que le choix du LLM est déterminant pour la réussite des appels de fonction. Certains LLM peuvent rencontrer des difficultés à extraire les paramètres pertinents de la conversation.