AgentChat
🇺🇸English 🇨🇳简体中文 🇭🇰繁體中文 🇯🇵日本語 🇰🇷한국어 🇫🇷Français 🇩🇪Deutsch 🇪🇸Español 🇮🇹Italiano
Se connecter
← Tous les articles
Architecture·10 min de lecture

Comment ajouter un agent d’IA à votre SaaS à l’aide des API que vous possédez déjà

Une architecture pratique pour transformer les API produit existantes en fonctionnalités sécurisées pour les agents, sans créer un outil personnalisé pour chaque action.

Ce guide met en œuvre une intégration complète d’AgentChat pour un SaaS fictif appelé SupportFlow. SupportFlow dispose déjà d’API permettant de trouver les factures en retard, d’envoyer des rappels et d’ajouter des notes aux comptes. Nous allons intégrer ces API à AgentChat, créer un chat associé à un utilisateur, démarrer une exécution asynchrone de l’agent et afficher le résultat à partir des messages persistants et de la propre base de données de SupportFlow.

La limite architecturale importante est concrète : AgentChat gère le raisonnement du modèle, la sélection des outils, l’historique du chat et le contrôle des exécutions. SupportFlow reste responsable des clients, des factures, de l’autorisation, de la validation et des enregistrements métier finaux. La documentation de l’API relie les deux systèmes.

N’ajoutez pas toutes les fonctionnalités du SaaS à l’environnement d’exécution de l’agent. Exposez un petit ensemble d’opérations métier essentielles sous forme d’API HTTP et intégrez leurs contrats à chaque chat.

Le flux de requêtes terminé

  1. SupportFlow crée une seule clé API AgentChat depuis le tableau de bord et la stocke uniquement sur son backend.
  2. Son backend enregistre les opérations de SupportFlow avec POST /api/api-documents.
  3. Lorsqu’un utilisateur ouvre l’assistant, SupportFlow crée une session avec l’UUID du document, un UUID de configuration du LLM et des identifiants utilisateur en écriture seule pour son hôte d’API.
  4. SupportFlow envoie le message de l’utilisateur à POST /api/agent/sessions/{id}/chat.
  5. AgentChat lit le contrat joint et utilise son outil intégré http_request pour appeler SupportFlow.
  6. SupportFlow interroge régulièrement les messages d’AgentChat, tandis que son interface utilisateur habituelle lit les factures et les notes dans la base de données de SupportFlow.

Étape 1 : exposer des opérations métier ciblées

L’agent n’a besoin ni d’un accès à la base de données ni d’une unique API interne gigantesque. Pour ce flux de travail, SupportFlow expose exactement trois points de terminaison adaptés aux locataires :

GET /v1/invoices?status=overdue&limit=3
→ { "items": [{ "invoice_id": "inv_72", "account_id": "acct_9", "amount": 480, "currency": "USD", "due_at": "2026-08-01" }] }

POST /v1/reminders
{ "invoice_id": "inv_72", "tone": "friendly" }
→ { "reminder_id": "rem_31", "status": "queued" }

POST /v1/accounts/acct_9/notes
{ "body": "Friendly reminder queued for overdue invoice inv_72." }
→ { "note_id": "note_55", "created_at": "2026-08-23T09:30:00Z" }

Chaque endpoint authentifie l'appelant, déduit le locataire à partir des identifiants d'authentification et filtre chaque opération de base de données. Les identifiants renvoyés par un appel deviennent des entrées sûres pour le suivant. Le modèle ne reçoit jamais de mot de passe de base de données ni d'interface de requête sans restriction.

Étape 2 : créer la configuration du modèle une seule fois

Chaque session AgentChat nécessite une configuration LLM appartenant à l'utilisateur. SupportFlow peut en créer une via le tableau de bord ou l'API et conserver l'UUID renvoyé.

POST $AGENTCHAT_SITE_URL/api/llm-config
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "name": "Support production model",
  "api_url": "https://llm-provider.example.com/v1/chat/completions",
  "api_key": "provider_secret",
  "model": "provider-model-name",
  "max_context_length": 128000,
  "max_output_tokens": 8192,
  "temperature": 0.2,
  "disable_reasoning": false
}

La réponse est encapsulée dans success et data. Enregistrez data.id comme llm_config_id, utilisé lors de la création des conversations. AgentChat masque la clé du fournisseur lors de la récupération des configurations.

Étape 3 : provisionner le document API de SupportFlow

Il s'agit du mécanisme de plugin. Le document contient des instructions opérationnelles, des entrées exactes, des sorties exactes et des règles de séquencement — pas de texte marketing ni de lien qui oblige l'agent à deviner.

POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "SupportFlow Invoice Actions",
  "description": "Find overdue invoices, queue reminders, and record account notes.",
  "content": "# SupportFlow Invoice Actions\nBase URL: https://support.example.com/v1\n\nGET /invoices?status=overdue&limit=3 returns items with invoice_id, account_id, amount, currency, and due_at. Use only when the user requests invoice lookup.\n\nPOST /reminders body: invoice_id required; tone is friendly or firm. Response: reminder_id and status. Never send more reminders than the user requested.\n\nPOST /accounts/{account_id}/notes body: body required. Call only after the reminder request succeeds. Include the invoice ID and reminder status in the note.\n\nIf any write returns 401 or 403, stop writing and explain that the session credential needs access. Do not retry a permission denial."
}

AgentChat renvoie le nouveau document dans data, avec son UUID. Conservez cet UUID dans la configuration d’intégration de SupportFlow. La mise à jour ultérieure de ce document modifie les instructions utilisées lors des tours de chat suivants, car les sessions joignent le document au lieu de le copier.

Étape 4 : créer un chat pour l’utilisateur SupportFlow actuel

POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "Invoice assistant for user_42",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["supportflow_document_uuid"],
  "system_prompt": "Act only on the user’s explicit request. Summarize every write with the affected invoice and account IDs.",
  "compact_threshold_percent": 80,
  "max_turns": 12,
  "tool_timeout_seconds": 120,
  "tool_result_max_chars": 10000,
  "host_headers": [
    { "host": "support.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_user_42_token" },
    { "host": "support.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_7" }
  ]
}

Les valeurs des en-têtes sont en écriture seule. AgentChat les stocke pour cette session, les injecte uniquement lorsque http_request cible l’hôte correspondant et n’expose pas leurs valeurs au modèle ni dans les réponses de l’API. Un deuxième utilisateur de SupportFlow obtient une session différente avec le même UUID de document, mais des en-têtes différents.

Étape 5 : démarrer l’exécution asynchrone

POST $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{ "message": "Find my three most overdue invoices, send each a friendly reminder, and add a note to each account." }

→ { "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

AgentChat rend la main immédiatement et poursuit l’exécution en arrière-plan. L’agent reçoit le document SupportFlow joint ainsi qu’exactement quatre outils intégrés : get_api_document, http_request, sleep et view_image. Les fonctionnalités de SupportFlow ne sont pas compilées dans ces outils ; elles sont apprises à partir du contrat d’API fourni et exécutées via http_request.

Ce que fait l’agent pendant cette requête

  1. Appeler via http_request le point de terminaison documenté des factures en retard.
  2. Lire les éléments structurés et sélectionner au maximum les trois factures demandées par l’utilisateur.
  3. Mettre les rappels en file d’attente. Les appels indépendants produits par une réponse du modèle peuvent être exécutés simultanément.
  4. Une fois les résultats concluants des rappels disponibles, appeler le point de terminaison des notes de compte avec chaque facture et identifiant de compte renvoyés.
  5. Produire un message final de l’assistant répertoriant les opérations terminées ainsi que toute erreur pour chaque facture.

C’est pourquoi la conception des réponses est importante. Un résultat vague tel que « réussite » ne donne à l’agent rien de fiable auquel rattacher l’action suivante. Des identifiants et des statuts structurés permettent à la boucle de raisonnement de combiner plusieurs API ordinaires pour produire un seul résultat pour l’utilisateur.

Étape 6 : interroger des messages persistants, pas un flux de LLM

GET $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENTCHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "message_uuid", "role": "assistant", "content": "...", "stream_status": "streaming", "revision": 4 }],
    "last_id": "message_uuid",
    "last_revision": 4,
    "is_processing": true,
    "total_tokens": 2840
  }
}

SupportFlow interroge son backend ou un client proxy une fois par seconde, regroupe les lignes par ID de message et ne remplace le contenu que lorsque la révision augmente. La base de données d’AgentChat est la source de vérité pour le contenu de la conversation. La base de données de SupportFlow reste la source de vérité pour les factures, les rappels et les notes.

Lorsque is_processing devient false, SupportFlow peut actualiser ses requêtes de factures et de comptes. L’interface produit standard affiche alors les rappels et les notes créés via ses propres API ; elle n’a pas besoin d’analyser le texte de l’assistant pour reconstituer l’état métier.

Contrôle de l’exécution et récupération après erreur

GET  /api/agent/sessions/session_uuid/state
POST /api/agent/sessions/session_uuid/stop
POST /api/agent/sessions/session_uuid/continue

Le point de terminaison d’état indique si le traitement est actif et si l’action suivante est « continue ». Les demandes d’arrêt annulent une exécution active. Si une défaillance récupérable ou une limite maximale de tours interrompt le travail, « continue » démarre une nouvelle exécution avec un nouveau budget de tours et le même contexte de conversation persistant.

Ce qu’il faut provisionner — et ce qu’il ne faut pas provisionner

  • Mettez à disposition des API qui représentent des capacités métier stables : rechercher, créer, mettre à jour, valider, publier ou consulter l’état des tâches.
  • Documentez les champs obligatoires, les contraintes, les objets de réponse, la signification des erreurs, les effets secondaires et les exigences d’ordre.
  • Joignez uniquement les documents nécessaires à l’expérience de chat, plutôt que tous les points de terminaison internes.
  • Conservez les identifiants dans des en-têtes de session propres à l’hôte, jamais dans les prompts ni dans le contenu de la documentation des API.
  • N’exposez pas de SQL brut, d’accès sans restriction aux fichiers ni de proxy interne générique simplement pour rendre l’agent flexible.
  • Faites exécuter votre propre autorisation et votre propre validation à chaque demande d’outil, exactement comme pour les autres clients.

Pourquoi le périmètre fonctionnel peut s’étendre sans augmenter l’ensemble des outils principaux

Un produit RAG peut provisionner des endpoints de recherche et de citation. Un produit de création d’histoires peut provisionner des endpoints pour les chapitres, la génération d’images et la publication. Un produit de développement peut provisionner des endpoints pour les fichiers de l’espace de travail, les vérifications et les déploiements. AgentChat utilise toujours les mêmes quatre outils principaux. Les opérations propres à l’application arrivent sous forme de documents d’API, de sorte que l’ajout d’une capacité constitue une modification de provisionnement plutôt qu’une nouvelle version du runtime de l’agent.

C’est le modèle central d’AgentChat : créer des documents d’API, créer une session de chat avec un périmètre défini, laisser l’agent composer vos opérations HTTP, consommer des messages persistants et restituer les enregistrements obtenus depuis la base de données de votre propre application.