> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Outils en code

## Vue d'ensemble

Un [outil](/docs/fr/eleven-agents/customization/tools) est stocké sous forme de configuration, avec des schémas JSON imbriqués pour ses paramètres. Rédiger cette configuration à la main implique de maintenir les paramètres de chemin synchronisés avec l'URL, les listes `required` avec leurs propriétés, et d'attribuer à chaque paramètre exactement une source de valeur. Le générateur d'outils des SDK Python et JavaScript vous permet de décrire le même outil à l'aide d'appels de méthodes chaînés. Il produit ensuite la requête déjà acceptée par `tools.create()` et `tools.update()`.

Utilisez-le pour :

* Définir des outils webhook, client et système dans du code, puis les examiner comme toute autre modification de code.
* Charger un outil, modifier un paramètre et le renvoyer sans affecter le reste de sa configuration.
* Stocker des outils au format JSON dans le contrôle de version et les valider dans votre intégration continue.

> **Note**
>
> Le générateur s'exécute entièrement dans le SDK. Il n'appelle aucun nouveau point de terminaison API, et tout ce qu'il génère peut être
> ouvert et modifié dans le Dashboard.

## Prérequis

* Python : le package `elevenlabs`. Le générateur est importé depuis `elevenlabs.agent_tools`.
* JavaScript : le package `@elevenlabs/elevenlabs-js`. Le générateur est exporté depuis la racine du package.

## Concevoir un outil webhook

`Tool.webhook(name, description)` initialise un [outil webhook](/docs/fr/eleven-agents/customization/tools/webhook-tools). Le nom et la description sont ceux que le LLM voit lorsqu'il décide d'appeler ou non l'outil. Cet exemple recherche une commande à partir du numéro fourni par l'appelant, envoie une clé API depuis les secrets du Workspace et stocke le statut de la commande dans une variable dynamique :

```python
from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool

elevenlabs = ElevenLabs()

get_order = (
    Tool.webhook("get_order", "Look up an order by the number the caller gives")
    .get("https://api.example.com/orders/{order_id}")
    .path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
    .query_param("include", Schema.string().constant("items"))
    .header("Authorization", Header.secret("sec_orders_api"))
    .assign("order_status", "order.status")
    .options(response_timeout_secs=10)
)

tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
```

```typescript
import { ElevenLabsClient, Header, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const getOrder = Tool.webhook("get_order", "Look up an order by the number the caller gives")
  .get("https://api.example.com/orders/{order_id}")
  .pathParam("order_id", Schema.string().describe("The order number, e.g. A-1042"))
  .queryParam("include", Schema.string().constant("items"))
  .header("Authorization", Header.secret("sec_orders_api"))
  .assign("order_status", "order.status")
  .options({ responseTimeoutSecs: 10 });

const tool = await elevenlabs.conversationalAi.tools.create(getOrder.build());
```

Les méthodes de requête définissent la méthode HTTP et l'URL. Les espaces réservés `{name}` dans l'URL sont renseignés à partir des paramètres de chemin :

| Python                                                           | JavaScript                 | Définit                                                                                                                                  |
| ---------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | idem                       | La méthode et l'URL. `POST`, `PUT` et `PATCH` nécessitent un corps ; `GET` ne peut pas en avoir.                                         |
| `path_param(name, schema)`                                       | `pathParam(name, schema)`  | Un paramètre de chemin, pour l'espace réservé `{name}` dans l'URL.                                                                       |
| `query_param(name, schema)`                                      | `queryParam(name, schema)` | Un paramètre de requête.                                                                                                                 |
| `body(schema)`                                                   | `body(schema)`             | Le corps de la requête. Doit être un schéma d'objet.                                                                                     |
| `response(schema)`                                               | `response(schema)`         | Le schéma du corps de la réponse. Doit être un schéma d'objet.                                                                           |
| `header(name, value)`                                            | `header(name, value)`      | Un en-tête de requête. Consultez [En-têtes et authentification](#headers-and-authentication).                                            |
| `auth(connection)`                                               | `auth(connection)`         | La [connexion d'authentification](/docs/fr/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) à utiliser. |
| `assign(variable, path)`                                         | `assign(variable, path)`   | Stocke la valeur située à `path` dans la réponse (notation par points) dans une variable dynamique.                                      |

Définir un paramètre ou un en-tête dont le nom existe déjà le remplace tout en conservant sa position. `remove_path_param()`, `remove_query_param()`, `remove_header()` et `remove_assignment()` (`removePathParam()` et ainsi de suite en JavaScript) en suppriment un. Les noms des paramètres doivent être uniques parmi les paramètres de chemin, de requête et de corps.

Un corps est un schéma d'objet construit propriété par propriété :

```python
refund = (
    Tool.webhook("issue_refund", "Refund an order the caller asked to return")
    .post("https://api.example.com/refunds")
    .body(
        Schema.object()
        .property("order_id", Schema.string().from_variable("order_id"))
        .property(
            "reason",
            Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
        )
        .property("note", Schema.string().describe("Anything else the caller said").optional())
    )
)
```

```typescript
const refund = Tool.webhook("issue_refund", "Refund an order the caller asked to return")
  .post("https://api.example.com/refunds")
  .body(
    Schema.object()
      .property("order_id", Schema.string().fromVariable("order_id"))
      .property(
        "reason",
        Schema.string()
          .describe("Why the caller wants a refund")
          .choices(["damaged", "late", "other"])
      )
      .property("note", Schema.string().describe("Anything else the caller said").optional())
  );
```

## Schémas de paramètres

`Schema` construit les schémas de paramètres utilisés par les outils webhook et client. Chaque méthode renvoie un nouveau schéma et laisse inchangé celui sur lequel elle a été appelée. Vous pouvez donc définir un schéma une fois et l'utiliser dans plusieurs outils.

| Constructeur                                                              | Construit                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `Schema.string()`, `Schema.integer()`, `Schema.number()`, `Schema.bool()` | Une valeur littérale                                         |
| `Schema.object()`                                                         | Un objet. Ajoutez des propriétés avec `property()`.          |
| `Schema.array(items)`                                                     | Un tableau dont les éléments correspondent au schéma `items` |

### Origine d'une valeur

Chaque valeur littérale nécessite exactement une source de valeur, quel que soit son emplacement : dans un paramètre, dans un corps, dans un schéma de réponse ou dans un objet ou un tableau. Un objet ou un tableau peut également en avoir une, qui fournit alors la valeur entière.

| Python                | JavaScript           | La valeur                                                                                                                                       |
| --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `describe(text)`      | `describe(text)`     | Est fournie par le LLM, guidé par `text`.                                                                                                       |
| `from_variable(name)` | `fromVariable(name)` | Est lue depuis une [variable dynamique](/docs/fr/eleven-agents/customization/personalization/dynamic-variables) lors de l'exécution de l'outil. |
| `constant(value)`     | `constant(value)`    | Est toujours `value`.                                                                                                                           |
| `system_provided()`   | `systemProvided()`   | Est renseignée par le système lors de l'exécution de l'outil. Valeurs littérales uniquement.                                                    |
| `omit()`              | `omit()`             | Est exclue de la requête. Uniquement pour une propriété facultative.                                                                            |

Sur un objet ou un tableau, `describe()` documente le conteneur pour le LLM, et chaque propriété ou élément conserve sa propre source.

### Autres méthodes de schéma

| Python                                            | JavaScript                                    | Fonction                                                                                                    |
| ------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `optional()`                                      | `optional()`                                  | Rend une propriété facultative. Les propriétés sont obligatoires sauf indication contraire.                 |
| `choices(values)`                                 | `choices(values)`                             | Limite une chaîne à un ensemble fixe de valeurs parmi lesquelles le LLM choisit.                            |
| `allowed_from(variable)`                          | `allowedFrom(variable)`                       | Rejette une valeur de LLM absente de la liste contenue dans une variable dynamique. Nécessite `describe()`. |
| `property(name, schema)` / `without(name)`        | `property(name, schema)` / `without(name)`    | Ajoute, remplace ou supprime une propriété d'objet. Une propriété remplacée conserve sa position.           |
| `require_any_of(names)` / `require_all_of(names)` | `requireAnyOf(names)` / `requireAllOf(names)` | Exige au moins une, ou toutes, les propriétés facultatives d'un groupe.                                     |

## En-têtes et authentification

Une valeur d'en-tête provient de l'un de quatre emplacements. Utilisez un secret ou une variable d'environnement pour toute donnée sensible afin que la valeur n'apparaisse jamais dans la configuration de l'outil :

| Constructeur                                     | La valeur de l'en-tête est                                                                                                                |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Header.value(text)`                             | Du texte fixe.                                                                                                                            |
| `Header.secret(id)`                              | Un secret du magasin de secrets du Workspace.                                                                                             |
| `Header.variable(name)`                          | Une variable dynamique, lue lors de l'exécution de l'outil.                                                                               |
| `Header.env_var(label)` / `Header.envVar(label)` | Une [variable d'environnement](/docs/fr/eleven-agents/integrate/environment-variables) du Workspace, résolue pour l'environnement actuel. |

`AuthConnection.id(id)` utilise une connexion d'authentification du Workspace via son ID. `AuthConnection.env_var(label)` / `AuthConnection.envVar(label)` la sélectionne depuis une variable d'environnement, afin qu'une même configuration d'outil puisse utiliser une connexion différente dans chaque environnement.

```python
from elevenlabs.agent_tools import AuthConnection, Header

update_profile = (
    Tool.webhook("update_profile", "Update the caller's email address")
    .put("https://api.example.com/profiles/{profile_id}")
    .path_param("profile_id", Schema.string().from_variable("profile_id"))
    .body(Schema.object().property("email", Schema.string().describe("The new email address")))
    .header("X-Api-Key", Header.env_var("profiles_api_key"))
    .auth(AuthConnection.env_var("profiles_oauth"))
)
```

```typescript
import { AuthConnection, Header } from "@elevenlabs/elevenlabs-js";

const updateProfile = Tool.webhook("update_profile", "Update the caller's email address")
  .put("https://api.example.com/profiles/{profile_id}")
  .pathParam("profile_id", Schema.string().fromVariable("profile_id"))
  .body(Schema.object().property("email", Schema.string().describe("The new email address")))
  .header("X-Api-Key", Header.envVar("profiles_api_key"))
  .auth(AuthConnection.envVar("profiles_oauth"));
```

## Concevoir un outil client

`Tool.client(name, description)` initialise un [outil client](/docs/fr/eleven-agents/customization/tools/client-tools), qui s'exécute dans votre application plutôt que sur un serveur. Ajoutez ses paramètres avec `param(name, schema)`. Définissez `expects_response` / `expectsResponse` lorsque l'agent doit attendre le résultat de votre application :

```python
show_map = (
    Tool.client("show_store_map", "Show the caller a map of the nearest store")
    .param("store_id", Schema.string().describe("The store to show"))
    .options(expects_response=False)
)
```

```typescript
const showMap = Tool.client("show_store_map", "Show the caller a map of the nearest store")
  .param("store_id", Schema.string().describe("The store to show"))
  .options({ expectsResponse: false });
```

## Concevoir un outil système

Les [outils système](/docs/fr/eleven-agents/customization/tools/system-tools) sont intégrés à la plateforme. Chacun dispose de son propre constructeur sur `SystemTool`, qui accepte les paramètres de cet outil :

| Python                                                  | JavaScript                                            |
| ------------------------------------------------------- | ----------------------------------------------------- |
| `SystemTool.end_call()`                                 | `SystemTool.endCall()`                                |
| `SystemTool.skip_turn(wait_timeout_secs=...)`           | `SystemTool.skipTurn({ waitTimeoutSecs })`            |
| `SystemTool.language_detection(...)`                    | `SystemTool.languageDetection(options?)`              |
| `SystemTool.play_keypad_touch_tone(...)`                | `SystemTool.playKeypadTouchTone(options?)`            |
| `SystemTool.voicemail_detection(voicemail_message=...)` | `SystemTool.voicemailDetection({ voicemailMessage })` |
| `SystemTool.knowledge_base(enabled_strategies=...)`     | `SystemTool.knowledgeBase({ enabledStrategies })`     |
| `SystemTool.transfer_to_number(...)`                    | `SystemTool.transferToNumber(options?)`               |
| `SystemTool.transfer_to_agent()`                        | `SystemTool.transferToAgent()`                        |

Les deux outils de transfert reçoivent leurs destinations depuis `transfer(condition, destination, options)`. La condition indique au LLM quand effectuer le transfert, et la destination utilise le même `Destination` que les [workflows en code](/docs/fr/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Un transfert vers un URI SIP nécessite un transfert SIP REFER :

```python
from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination

transfer = (
    SystemTool.transfer_to_number()
    .transfer("Caller asks for billing", Destination.phone("+15551234567"))
    .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)

to_sales = SystemTool.transfer_to_agent().transfer(
    "Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)
```

```typescript
import { Destination, SystemTool } from "@elevenlabs/elevenlabs-js";

const transfer = SystemTool.transferToNumber()
  .transfer("Caller asks for billing", Destination.phone("+15551234567"))
  .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), {
    transferType: "sip_refer",
  });

const toSales = SystemTool.transferToAgent().transfer(
  "Caller wants to buy something",
  Destination.agent("agent_sales"),
  { transferMessage: "Connecting you to sales" }
);
```

## Options des outils

Les paramètres communs à tous les types d'outils sont définis dans `options()`, sous forme d'arguments nommés en Python et d'objet en JavaScript. Leurs noms correspondent aux champs de la configuration de l'outil dans l'API :

| S'applique à    | Python                                                                                                                                       | JavaScript                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Tous les outils | `name`, `description`, `response_timeout_secs`, `interruption_mode`, `pre_tool_speech`, `tool_call_sound`, `tool_error_handling_mode`, ...   | `name`, `description`, `responseTimeoutSecs`, `interruptionMode`, `preToolSpeech`, `toolCallSound`, `toolErrorHandlingMode`, ...    |
| Outils webhook  | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Outils client   | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `expectsResponse`, `dynamicVariablePlaceholders`                                                                   |

Le délai d'attente de réponse d'un outil webhook est compris entre 5 et 300 secondes. Celui d'un outil client est compris entre 1 et 120 secondes, ou peut être défini sur -1 pour attendre aussi longtemps que nécessaire, ce qui requiert `expects_response` / `expectsResponse`. `follow_redirects` / `followRedirects` requiert une liste de domaines autorisés.

## Associer des outils à un agent

Les outils webhook et client sont créés séparément avec `tools.create()` et associés aux agents par ID. Un même outil peut donc être partagé par plusieurs agents. Les outils système font partie de la configuration de l'agent : `build_config()` / `buildConfig()` renvoie l'entrée correspondant aux outils intégrés de l'agent.

```python
from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput

order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

agent = elevenlabs.conversational_ai.agents.create(
    name="Support line",
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt=PromptAgentApiModelOutput(
                prompt="You are a support agent for Acme.",
                tool_ids=[order_tool.id],
                built_in_tools=BuiltInToolsOutput(
                    end_call=SystemTool.end_call().build_config(),
                    transfer_to_number=transfer.build_config(),
                ),
            )
        )
    ),
)
```

```typescript
const orderTool = await elevenlabs.conversationalAi.tools.create(getOrder.build());

const agent = await elevenlabs.conversationalAi.agents.create({
  name: "Support line",
  conversationConfig: {
    agent: {
      prompt: {
        prompt: "You are a support agent for Acme.",
        toolIds: [orderTool.id],
        builtInTools: {
          endCall: SystemTool.endCall().buildConfig(),
          transferToNumber: transfer.buildConfig(),
        },
      },
    },
  },
});
```

> **Warning**
>
> Le champ `prompt.tools` de l'agent, qui contient les configurations d'outils intégrées, est obsolète. Il ne peut pas être
> combiné avec `tool_ids` et, lorsqu'une requête l'inclut, les outils intégrés de l'agent sont remplacés
> par les outils système qu'il contient. Créez plutôt les outils avec `tools.create()` et associez-les par ID.

## Modifier un outil existant

`Tool.from_response()` / `Tool.fromResponse()` charge un outil renvoyé par `tools.get()`. Les champs que le générateur ne modélise pas, ainsi que les valeurs par défaut renseignées par l'API, sont conservés. Le renvoyer ne modifie donc que les éléments que vous avez changés. `as_webhook()`, `as_client()` et `as_system()` (`asWebhook()` et ainsi de suite en JavaScript) vous donnent l'outil typé à modifier, ou `None` / `undefined` s'il est d'un autre type.

Pour modifier une propriété du corps, lisez le schéma du corps, définissez de nouveau la propriété, puis définissez le corps :

```python
from elevenlabs.agent_tools import ObjectSchema

loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
    raise ValueError("Not a webhook tool")

body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())

elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())
```

```typescript
import { type ObjectSchema, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const loaded = Tool.fromResponse(
  await elevenlabs.conversationalAi.tools.get("tool_id")
).asWebhook();
if (!loaded) throw new Error("Not a webhook tool");

const body = loaded.bodySchema as ObjectSchema;
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")));
loaded.queryParam("locale", Schema.string().describe("The caller's language").optional());

await elevenlabs.conversationalAi.tools.update("tool_id", loaded.build());
```

## Stocker des outils dans le contrôle de version

`to_json_string()` / `toJSONString()` écrit l'outil au format de transfert de l'API : clés en snake_case, triées à chaque niveau, avec une indentation de 2 espaces. Il s'agit de la même structure que conserve la [CLI](/docs/fr/eleven-agents/operate/cli) dans son répertoire `tool_configs/`, et les deux SDK écrivent des fichiers identiques octet par octet pour un même outil, afin de limiter les différences. `Tool.from_json()` / `Tool.fromJSON()` le relit.

```python
from pathlib import Path

from elevenlabs.agent_tools import Tool

Path("tool_configs/get_order.json").write_text(get_order.to_json_string())

stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())
```

```typescript
import { Tool } from "@elevenlabs/elevenlabs-js";
import { readFile, writeFile } from "node:fs/promises";

await writeFile("tool_configs/get_order.json", getOrder.toJSONString());

const stored = Tool.fromJSON(await readFile("tool_configs/get_order.json", "utf8"));
await elevenlabs.conversationalAi.tools.update("tool_id", stored.build());
```

Une configuration classique est identique à celle des [workflows](/docs/fr/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control) : initialisez les fichiers avec `elevenlabs tools pull`, modifiez-les directement ou avec le générateur, exécutez `Tool.from_json(file).build()` / `Tool.fromJSON(file).build()` dans l'intégration continue pour chaque pull request, puis envoyez-les avec `tools.update()` ou `elevenlabs tools push` lors de la fusion.

## Validation

Les appels chaînés n'échouent jamais seuls. `build()`, `build_config()` / `buildConfig()`, `to_json()` / `toJSON()` et `to_json_string()` / `toJSONString()` vérifient l'ensemble de l'outil et lèvent ou déclenchent une seule `ToolValidationError`, dont la liste `issues` répertorie tous les problèmes, chacun avec un `code`, un `message` et le `path` de la partie concernée, par exemple `body.reason`.

```python
from elevenlabs.agent_tools import ToolValidationError

try:
    request = refund.build()
except ToolValidationError as err:
    for issue in err.issues:
        print(issue.code, issue.path, issue.message)
```

```typescript
import { ToolValidationError } from "@elevenlabs/elevenlabs-js";

try {
  const request = refund.build();
} catch (err) {
  if (err instanceof ToolValidationError) {
    for (const issue of err.issues) console.error(issue.code, issue.path, issue.message);
  } else {
    throw err;
  }
}
```

Les erreurs incluent :

* Un espace réservé d'URL sans paramètre de chemin, ou un paramètre de chemin sans espace réservé. Les modèles de variables d'environnement tels que `{{system__env_api_host}}` ne sont pas des espaces réservés.
* Une valeur littérale sans source de valeur, ou avec plusieurs sources.
* Un corps sur un `GET`, ou l'absence de corps sur un `POST`, `PUT` ou `PATCH`.
* Le même nom de paramètre dans plusieurs emplacements parmi le chemin, la requête et le corps.
* `omit()` sur une propriété obligatoire, `choices()` sur un schéma qui n'est pas une chaîne, ou une constante qui ne correspond pas au type du schéma.
* Un outil de transfert sans destination, une destination du mauvais type, ou une destination URI SIP sans transfert SIP REFER.
* Une option qui ne s'applique pas à ce type d'outil, ou un délai d'attente hors de sa plage autorisée.

## Types d'outils plus récents que votre SDK

Un outil chargé depuis l'API ou depuis un fichier peut être d'un type que le générateur ne peut pas modifier, comme un outil MCP. Il est chargé avec le type `"other"`, reste inchangé lors des passages par `from_json()` / `fromJSON()` et `to_json_string()` / `toJSONString()`, et `build()` le signale comme avertissement via `on_warning` / `onWarning`.