> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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.

> **Note**
>
> Cette fonctionnalité est réservée aux entreprises.

## 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.

> **Info**
>
> Pour un seul appel d’API externe sans logique personnalisée, les [outils webhook ](/docs/fr/eleven-agents/customization/tools/webhook-tools) sont généralement plus simples à configurer. Pour
> déclencher des actions dans le navigateur ou l’application d’un utilisateur, utilisez plutôt les [outils client ](/docs/fr/eleven-agents/customization/tools/client-tools).

## 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 :

```javascript
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](/docs/fr/eleven-agents/customization/tools/webhook-tools#tool-configuration).

### 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.

| Propriété              | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ctx.args`             | Les paramètres d’appel de l’outil fournis par l’agent.                                                                                                                                                                                                                                                                                                                                                 |
| `ctx.config`           | Variables de chaîne simples que vous avez associées au contexte de cet outil.                                                                                                                                                                                                                                                                                                                          |
| `ctx.secrets`          | Secrets du Workspace que vous avez associés au contexte de cet outil pour les utiliser dans les en-têtes de requête. Le secret brut n’est jamais exposé à votre code : l’injection a lieu à la sortie et exclusivement dans les en-têtes.                                                                                                                                                              |
| `ctx.auth_connections` | Références aux [connexions d’authentification](/docs/fr/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) configurées que vous avez associées au contexte de cet outil, à utiliser dans l’en-tête de requête `X-With-Auth-Connection`. L’identifiant sous-jacent n’est jamais exposé à votre code : l’injection a lieu à la sortie et exclusivement dans les en-têtes. |

> **Note**
>
> Seul `ctx.args` est visible par l’agent lorsqu’il appelle l’outil. Les secrets, valeurs de configuration et connexions d’authentification ne sont jamais révélés à l’agent.

#### 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.

![Définition d’un paramètre d’outil de code](/docs/_fern-files/_img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp)

#### 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.

![Association d’un secret de Workspace à l’objet de contexte d’un outil de code](/docs/_fern-files/_img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp)

### 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.

> **Warning**
>
> La modification de **Code Tool Network Access** nécessite des autorisations d’administrateur du Workspace.

### 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 :

#### Créer un nouvel outil de code

Dans la section **Agent** de la page des paramètres de votre agent, choisissez **Add Tool**. Sélectionnez **Code** comme type d’outil, puis définissez un nom et une description :

| Champ       | Valeur                                                |
| ----------- | ----------------------------------------------------- |
| Nom         | convert_temperature                                   |
| Description | Convertit une température entre Celsius et Fahrenheit |

#### Définir les paramètres

Ajoutez deux paramètres pour que le LLM sache quelles valeurs fournir :

| Type de données | Identifiant | Obligatoire | Description                       |
| --------------- | ----------- | ----------- | --------------------------------- |
| number          | value       | true        | Valeur de température à convertir |
| string          | from_unit   | true        | Unité de départ : `"C"` ou `"F"`  |

#### Écrire le code

Ouvrez l’éditeur de code et remplacez le code source par défaut par :

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

Utilisez **Run** avec quelques valeurs d’exemple (par exemple `value: 100, from_unit: "C"`) pour confirmer la sortie avant d’enregistrer.

#### Orchestration

Mettez à jour le prompt système de votre agent afin qu’il sache quand utiliser l’outil :

**`Prompt système`**

```plaintext Prompt système
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.
```

#### Tests

Démarrez une conversation et essayez :

> *Que représentent 100 degrés Celsius en Fahrenheit ?*

L’agent doit appeler l’outil et lire la valeur convertie.

### Exemples d’authentification

**Appeler une API avec un secret**

```javascript
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**

```javascript
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](/docs/fr/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) 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 :

```plaintext
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 :

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

#### Sélection du LLM

> **Warning**
>
> Lorsque vous utilisez des outils, nous recommandons de choisir des modèles à haute capacité de raisonnement comme GPT 6 ou Claude Sonnet 5.5.

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.