# API d'agent

> Appelez un agent en HTTP avec une clé qui lui est réservée — une requête ponctuelle, ou une session qui garde son contexte d'un appel à l'autre.

La section **API** génère des clés qui permettent d'appeler cet agent depuis l'extérieur d'endue. C'est la troisième voie d'accès, à côté d'une [conversation](/fr/docs/work/conversations/) et d'un [canal](/fr/docs/automate/channels/), et celle-ci s'adresse aux programmes.

## Quand l'utiliser

Quand l'appelant est du code : un script qui dépose un résumé chaque jour, un backend qui demande à un agent de classer quelque chose, une tâche qui tourne en CI. Si l'appelant est une personne, un canal convient mieux : il lui offre un fil, des questions et des approbations.

## Créer une clé

<Steps>

1. **Ouvrez la section API** dans [Agent Builder](/fr/docs/build/agent-builder/) et créez une clé.

2. **Copiez-la tout de suite.** La clé ne s'affiche qu'une fois. Si vous la perdez, révoquez-la et générez-en une autre.

3. **Rangez-la là où un programme peut la lire, mais pas une personne** : une variable d'environnement ou un gestionnaire de secrets, jamais un dépôt de code.

</Steps>

Une clé créée ici est **limitée à cet agent** : elle ne permet pas d'appeler vos autres agents. Les clés valables pour tout le compte, qui le permettent, se génèrent dans **Paramètres → Compte**. Préférez la clé la plus restreinte.

<Screenshot
  name="studio-api"
  alt="La section API : une clé générée, affichée avec son préfixe et sa dernière utilisation, au-dessus d'un exemple de requête prêt à copier."
/>

## Appeler l'agent

Envoyez la clé dans `Authorization: Bearer sk_…` (ou `X-API-Key`), puis indiquez dans une requête POST ce que l'agent doit faire :

```http
POST /api/public/v1/agents/{agent_id}/invoke
Authorization: Bearer sk_...
Content-Type: application/json

{ "input": "Summarize yesterday's support tickets" }
```

La réponse contient ce que l'agent a répondu, accompagné d'un **identifiant de session**. Renvoyez cet identifiant lors de l'appel suivant et l'agent poursuit dans le même contexte (la même conversation, avec son historique) au lieu de repartir de zéro :

```json
{ "input": "Now group them by product area", "session_id": "..." }
```

Ajoutez `"stream": true` pour recevoir la réponse au fil de sa génération, sans attendre la fin de l'exécution.

<Aside type="note" title="Une session est une conversation">
  Les sessions ne sont pas un objet à gérer à part. Chacune est une conversation que vous pouvez
  ouvrir dans endue (dans la barre latérale, sous le groupe API de l'agent) pour lire ce qu'on a
  demandé à l'agent et ce qu'il a répondu.
</Aside>

## Ce à quoi un appel API n'a pas droit

Un appelant API n'est pas assis devant la conversation. Son appel est donc traité comme une [exécution sans surveillance](/fr/docs/automate/routines/#personne-nest-là-pour-approuver) :

- Les actions qui envoient vers l'extérieur ou qui suppriment sont **refusées**, et non mises en attente d'une approbation.
- Personne n'est là pour répondre aux [questions](/fr/docs/work/questions/) que l'agent a besoin de poser.

Rédigez la requête assez précisément pour que l'agent n'ait aucune décision à prendre, et attendez-vous à des brouillons plutôt qu'à des envois.

## Limites

- Une seule exécution à la fois par session. Un nouvel appel pendant qu'une exécution est en cours sur cette session est rejeté, pas mis en file d'attente.
- Les clés ne s'affichent qu'une fois et ne peuvent pas être récupérées : révoquez-les et générez-en de nouvelles.
- Une clé limitée à un agent ne fonctionne que pour cet agent ; pour tout autre agent, le point de terminaison répond « introuvable ».
- La révocation d'une clé prend effet immédiatement.

## Voir aussi

<CardGrid>
  <LinkCard
    title="Canaux"
    href="/fr/docs/automate/channels/"
    description="La voie d'accès pour les personnes plutôt que pour les programmes."
  />
  <LinkCard
    title="Approbations"
    href="/fr/docs/work/approvals/"
    description="Pourquoi un appel API ne peut pas envoyer d'e-mail de lui-même."
  />
  <LinkCard
    title="Sécurité et autorisations"
    href="/fr/docs/account/security/"
    description="Ce qu'une clé peut atteindre, et comment la révoquer."
  />
</CardGrid>