Atelier

Lección 1 — Cas d'usage et architecture

Deux agents, un protocole

5 min de lectura

Este contenido aún no está traducido. Se muestra la versión original.

Deux agents, un protocole

Le scénario

Un commercial demande : « Je voudrais un devis pour 500 VIS-M6. » Pour répondre, il faut :

  1. connaître la disponibilité et le prix unitaire : c'est le domaine de la logistique (agent agent_stock) ;
  2. calculer HT, TVA, TTC et proposer une livraison partielle si besoin : c'est le domaine des ventes (agent agent_commandes).

Les références (VIS-M6, ECR-M6, RON-M6) et les prix sont fictifs.

Sous-agent local ou agent distant ?

Sous-agent ADK (même processus)Agent distant en A2A
Codedans le même dépôt, même déploiementn'importe où, n'importe quel langage ou framework compatible A2A
Équipeune seulechacune garde son agent, ses données, son rythme de déploiement
Sécuritépartage des droits du processuschaque agent a sa identité et ses droits
Coûtaucun saut réseauun appel HTTP par délégation (latence, à surveiller)
Quand ?découper un agent trop grosfaire coopérer des agents indépendants

Dans quel cas A2A est-il le meilleur choix ?

Les trois objets du protocole A2A

  • Carte d'agent (Agent Card) : un document JSON publié à /.well-known/agent-card.json. Il donne le nom, la description, les compétences (skills) et l'URL où envoyer les messages. C'est l'équivalent d'une fiche de contact.
  • Message : ce qu'un client envoie, avec un rôle (ROLE_USER) et des parties (parts) : texte, données, fichiers.
  • Tâche (Task) : ce que l'agent renvoie, avec un état (TASK_STATE_COMPLETED, TASK_STATE_FAILED…), un historique et des artefacts (le résultat).

Le transport utilisé ici est JSON-RPC 2.0 sur HTTP : un POST avec {"method": "SendMessage", "params": {...}}.

sequenceDiagram
  participant C as "agent_commandes (client A2A)"
  participant S as "agent_stock (serveur A2A)"
  C->>S: GET /.well-known/agent-card.json
  S-->>C: carte : nom, compétences, URL RPC
  C->>S: POST URL RPC : SendMessage("Stock et prix de VIS-M6 ?")
  S->>S: agent ADK + outil verifier_stock
  S-->>C: Task COMPLETED + artefact texte
  C->>C: calculer_devis(500, 0.08)

Que fait un client A2A avant d'envoyer son premier message à un agent qu'il ne connaît que par son adresse ?

L'architecture du lab

flowchart TB
  subgraph Local["Étape 1 : en local"]
    L1["uvicorn commandes_agent:app :8002"] -->|"http://localhost:8001"| L2["uvicorn stock_agent:app :8001"]
  end
  subgraph Cloud["Étape 2 : Cloud Run"]
    C1["lab-a2a-commandes (SA lab-a2a-commandes)"] -->|"HTTPS + jeton d'identité"| C2["lab-a2a-stock (SA lab-a2a-stock)"]
  end
  Local --> Cloud

Le même code tourne dans les deux cas : seules les variables d'environnement changent (STOCK_URL, PUBLIC_URL). Quand STOCK_URL commence par https://, le client HTTP ajoute automatiquement un jeton d'identité.

Résultat obtenu

La carte réelle servie par agent_stock en local le 2026-10-15 (extrait, ADK 2.10 / a2a-sdk 1.2.2) :

GET http://localhost:8001/.well-known/agent-card.json (2026-10-15)
{"name":"agent_stock",
 "description":"Connaît le stock de l'entrepôt : disponibilité et prix unitaire d'une référence.",
 "supportedInterfaces":[{"url":"http://localhost:8001","protocolBinding":"JSONRPC","protocolVersion":"1.0"}],
 "capabilities":{"streaming":true},
 "skills":[{"id":"agent_stock","name":"model", "...": "..."},
           {"id":"agent_stock-verifier_stock","name":"verifier_stock", "...": "..."}]}

ADK a construit la carte tout seul à partir de l'agent : sa description et ses outils deviennent des compétences.

Exercice

L'équipe logistique veut ajouter un agent « transport » qui donne un délai de livraison. Faut-il en faire un sous-agent de agent_stock, un sous-agent de agent_commandes, ou un troisième service A2A ? Justifiez avec les critères du tableau.

Voir la solution

Tout dépend de qui le maintient et de quelles données il utilise :

  • s'il est maintenu par la logistique et lit les mêmes données que le stock, un sous-agent local de agent_stock (ou un simple outil) suffit : pas de saut réseau, une seule identité logistique ;
  • s'il est maintenu par une autre équipe (un transporteur, un autre service), ou s'il a besoin de droits différents (API d'un partenaire), un troisième service A2A avec son propre compte de service est le bon choix ;
  • en faire un sous-agent de agent_commandes mélangerait des responsabilités de deux équipes dans le même déploiement : à éviter.

Je sais faire

  • Choisir entre sous-agent local et agent distant A2A
  • Décrire carte d'agent, message et tâche
  • Lire une carte d'agent et y trouver l'URL d'envoi
  • Expliquer pourquoi on teste d'abord en local
Siguiente