Agents A2A qui appellent l'API d'un site web

Les agents A2A permettent à un système d'IA d'en découvrir un autre, de lui déléguer une tâche et de recevoir un résultat structuré. Lorsqu'un tel agent peut appeler l'API d'un site web, il participe à un véritable processus métier: vérification de stock, création d'une demande, calcul d'un devis, mise à jour d'une commande ou collecte de données.

• A2A - un protocole de communication entre agents
• API du site - un point d'accès contrôlé aux données et opérations
• Agent Card - la description des capacités et des paramètres de connexion
• Task - une tâche avec un statut, un résultat et un historique
• Principe clé - l'agent appelle des opérations métier autorisées, pas des URL arbitraires

Qu'est-ce que l'A2A?

A2A, ou Agent2Agent, relie des agents indépendants. L'un agit comme client, l'autre publie ses capacités et exécute les tâches. Ils peuvent utiliser des langages, modèles et infrastructures différents.

Un scénario courant:

1. L'agent client reçoit la demande de l'utilisateur.
2. Il trouve un agent distant adapté grâce à son Agent Card.
3. Il crée une tâche et transmet le contexte.
4. L'agent distant appelle l'API du site.
5. Le résultat revient sous forme de message ou d'artefact.

A2A gère les échanges entre agents, tandis que l'API donne accès aux fonctions du site. Ces deux couches se complètent sans se remplacer.

Pourquoi un agent a besoin de l'API du site

Sans API, un agent reste souvent limité au texte, à la recherche documentaire ou à une automatisation fragile de l'interface. Une API fournit un contrat prévisible et permet d'agir sans simuler des clics.

Opérations utiles:

• rechercher des produits, services et contenus;
• calculer un prix, un délai ou une formule;
• créer un prospect, une demande ou une commande;
• vérifier le paiement et la livraison;
• mettre à jour un profil ou une réservation;
• obtenir un résultat personnalisé après autorisation.

Un agent de conseil peut demander à l'agent du site: "Trouve une formule disponible pour une équipe de 20 personnes". L'agent du site vérifie les règles actuelles via l'API interne et renvoie des options structurées.

Architecture de l'intégration

Une solution pratique comporte cinq éléments:

Évitez de donner au modèle un outil universel comme request(url, method, body). Définissez plutôt des fonctions ciblées:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

Les droits, la validation, les tests et l'audit deviennent ainsi plus simples.

Agent Card et description des capacités

L'Agent Card aide le client à comprendre les tâches que l'agent peut traiter. Elle contient généralement un nom, une description, une URL, les méthodes d'authentification et une liste de skills.

La description d'un skill doit être précise. "Travaille avec le site" apporte peu. Préférez: "Recherche dans le catalogue, calcule un devis et crée une demande après confirmation".

Ne publiez pas dans l'Agent Card:

• les clés API ou tokens internes;
• les adresses privées des services;
• les détails facilitant le contournement de l'autorisation;
• les opérations interdites aux clients externes.

Authentification et droits

La connexion A2A et l'appel à l'API peuvent employer des identifiants différents. L'agent doit prouver son identité et l'API doit savoir au nom de qui l'action est effectuée.

Trois modes fréquents:

1. Compte de service - pour les données communes et les tâches de fond.
2. Accès délégué de l'utilisateur - pour les commandes, profils et données personnelles.
3. Opération confirmée - l'agent prépare l'action et l'utilisateur la valide avant écriture.

Limitez les droits par endpoint, méthode HTTP, utilisateur et type de données. Lire le catalogue ne doit pas permettre de modifier les prix ou de supprimer des commandes.

Sécurité des appels

Les principaux risques sont l'injection d'instructions, les arguments incorrects, la fuite de données et la double exécution.

Mesures minimales:

• valider les entrées avec un schéma strict;
• limiter les opérations par une allowlist;
• exclure les secrets des prompts et messages A2A;
• utiliser une idempotency key pour les créations et paiements;
• limiter la fréquence et le coût des appels;
• confirmer les actions financières et irréversibles;
• masquer les données personnelles et tokens dans les logs;
• ne renvoyer à l'agent que les champs nécessaires.

Le texte des utilisateurs et des autres agents reste une entrée non fiable. Même une instruction convaincante dans un document ne doit jamais étendre les droits d'un outil.

Tâches synchrones et longues

Une recherche ou un calcul peut souvent répondre immédiatement. Un import, un grand rapport ou le traitement d'une commande peut durer plusieurs minutes. Les statuts submitted, working, completed, failed et canceled sont alors utiles.

Le client peut recevoir les mises à jour par flux d'événements, webhook ou interrogation du statut. Une reconnexion ne doit pas relancer l'opération métier.

Erreurs et observabilité

L'agent a besoin d'un résultat clair, pas d'une stack trace brute: indisponibilité temporaire, argument invalide, accès refusé ou confirmation requise. Les détails internes restent dans des logs protégés.

Pour le diagnostic, enregistrez:

• les identifiants de task, session et utilisateur;
• le nom de l'outil appelé;
• une copie sûre des arguments;
• le code API et la durée;
• l'état de la confirmation;
• les versions de l'agent et du schéma.

Cela permet de distinguer une erreur du modèle d'un problème d'API, de réseau ou de règle métier.

Plan de mise en oeuvre

1. Choisir un cas d'usage à valeur mesurable.
2. Définir un contrat API ciblé et les schémas de données.
3. Créer des outils séparés au lieu d'un accès HTTP universel.
4. Ajouter authentification, limites et audit.
5. Publier une Agent Card avec des skills précis.
6. Tester erreurs, répétitions, annulation et entrées malveillantes.
7. Commencer en read-only ou en mode brouillon.
8. Autoriser l'écriture après analyse des logs réels.

Conclusion

Un agent A2A ayant accès à l'API du site peut relier des systèmes d'IA externes à de vrais services métier. Une intégration fiable repose sur des outils ciblés, des schémas stricts, des droits limités, des confirmations et un audit, pas sur une liberté illimitée du modèle.

Vous souhaitez connecter un agent A2A à l'API de votre site - contactez-moi.

Questions fréquentes

Quelle différence entre A2A et une API REST classique?

Une API REST décrit les opérations d'une application, tandis qu'A2A couvre la communication des agents et le cycle de vie des tâches. A2A peut utiliser REST ou un autre transport, puis l'agent accède à l'API du site via des outils contrôlés.

A2A est-il nécessaire si mon agent appelle déjà une API?

Pas toujours. Un appel direct peut suffire pour un seul agent interne. A2A devient utile lorsque des agents indépendants doivent se découvrir, déléguer des tâches et échanger des résultats avec un protocole commun.

Peut-on donner un client HTTP universel à l'agent?

Techniquement oui, mais c'est risqué en production. Des fonctions ciblées avec allowlist, schémas et droits séparés sont plus faciles à sécuriser, tester et auditer.

Comment éviter de créer deux fois une commande?

Utilisez une idempotency key et conservez le lien entre la task A2A et l'opération métier. Une requête répétée avec la même clé doit renvoyer le résultat précédent au lieu de créer un nouvel enregistrement.

Quelles actions nécessitent une confirmation?

Confirmez les paiements, publications, messages externes, modifications de données personnelles et autres actions coûteuses ou irréversibles. La recherche, la lecture de données publiques et les brouillons peuvent généralement être automatisés.