API d'agent

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 et d’un canal, 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é

1. Ouvrez la section API dans 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.

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.

Ouvrir en taille réelle

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 :

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 :

{ "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.

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.

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 :

• 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 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

CanauxLa voie d'accès pour les personnes plutôt que pour les programmes.

ApprobationsPourquoi un appel API ne peut pas envoyer d'e-mail de lui-même.

Sécurité et autorisationsCe qu'une clé peut atteindre, et comment la révoquer.