A2A offre à un agent IA un moyen standard de se présenter à un autre agent, d'accepter un travail ou une tâche, de signaler la progression, de demander plus d'informations et de renvoyer des résultats utiles, même lorsque l'autre agent s'exécute dans un autre service d'IA, utilise un langage de programmation ou un framework d'agent différent, ou est déployé dans un autre cloud. Aucun des deux agents n’a besoin de comprendre comment l’autre est construit. Ils utilisent la norme A2A pour communiquer et travailler ensemble.
Architecture de référence ADK-Rust A2A
The network contract stays separate from the agent's model, tools, memory, and internal orchestration.
01
Agent ou application demandant à un autre agent d'effectuer un travail.
Décide quel spécialiste à distance doit recevoir la tâche.
Découvre la carte, choisit le streaming et envoie des messages de protocole.
02
Le contrat public que tout client compatible peut comprendre.
Nom, compétences, point de terminaison, version du protocole, sécurité et capacités déclarées.
Version, type de contenu, identifiants, parties du message, métadonnées, identité et limites.
Répartit les opérations JSON-RPC ou REST via une implémentation partagée.
03
Le framework exécute la tâche et produit une progression typée.
Crée le contexte d'appel et diffuse les événements de l'agent.
LLM, workflow, graphique, logique personnalisée ou multi-agents.
Outils Rust et MCP
Séances et mémoire
04
Une machine à états validée rend les travaux de longue durée inspectables.
Statut, contexte, historique, artefacts, métadonnées et configuration push.
Seules les transitions valides sont acceptées ; les tâches terminales restent terminales.
05
L'appelant choisit la manière dont il souhaite recevoir la monnaie.
Renvoyez la tâche complète et ses artefacts.
Tâche d'abord, puis mises à jour du statut et des artefacts.
06
Les tâches longues peuvent être signalées plus tard sans maintenir une seule connexion ouverte.
Un client écoute les mises à jour pour une tâche existante.
Livraison authentifiée avec nouvelle tentative et contrôles SSRF.
Commencez par l'idée
Au sein d'un processus ADK-Rust, les agents peuvent partager des types, des sessions, des outils et des appels de fonction directs Rust. Une fois qu'un agent appartient à un autre service (ou à une autre organisation), ces détails de mise en œuvre privés ne constituent plus un contrat sûr.
A2A définit la langue partagée à cette limite. L'appelant découvre ce que propose l'agent distant, envoie un message structuré, suit une tâche à travers des états connus et reçoit des artefacts sans avoir besoin de savoir quel modèle, framework ou outils s'exécutent derrière le point de terminaison.
ADK-Rust implémente A2A v1 dans adk-server et connecte le protocole directement au Runner. Le même agent que vous testez localement peut devenir un service réseau, tandis que RemoteA2aAgent permet à un autre système ADK-Rust de le consommer via l'interface d'agent normale.
Carte d'agent
Un petit document public indique aux appelants le nom de l’agent, le point de terminaison, les compétences, la version du protocole, les exigences de sécurité et s’il prend en charge le streaming ou les notifications.
Message
Un message comporte un rôle, un identifiant unique et une ou plusieurs parties telles que du texte ou des données structurées. L'ID unique permet des tentatives sécurisées.
Tâche
Une tâche donne au travail à distance un identifiant, un contexte de conversation, un état, un historique des messages, des métadonnées et tous les artefacts produits en cours de route.
Artefact
Un artefact est un résultat nommé attaché à la tâche : un rapport, une décision, un plan, un fichier généré ou toute autre sortie structurée qu'un autre système peut utiliser.
Suivre un emploi
Un appelant peut attendre une réponse, ouvrir un flux d'événements en direct, s'abonner à une tâche existante ou enregistrer un webhook pour des mises à jour ultérieures. L'identité et le contexte de la tâche maintiennent chaque mode de livraison attaché au même travail.
Machine à états de tâches
A2A fait plus que renvoyer du texte. Cela donne au travail une identité, un contexte de conversation, un état actuel, une histoire et des artefacts. ADK-Rust valide chaque transition avant de la sauvegarder.
SUBMITTEDLe serveur a accepté la tâche.
WORKINGL'agent est en train de l'exécuter.
INPUT REQUIREDL'agent a besoin de plus d'informations.
AUTH REQUIREDL'appelant doit fournir une autorisation.
COMPLETEDLes travaux et les artefacts sont prêts.
FAILEDL'exécution s'est terminée par une erreur.
CANCELEDUne annulation autorisée a mis fin à la tâche.
REJECTEDLe serveur a refusé la tâche.
INPUT_REQUIRED, l'appelant envoie un autre message avec le même contextId. ADK-Rust trouve la tâche, la renvoie à WORKING, ajoute le message et continue le même travail.Flux logique du monde réel
A customer tells the company's support agent that an order arrived damaged. The support agent remains responsible for the conversation: it understands the request, keeps the customer informed, collects any missing evidence, and presents the final decision. It does not have direct access to warehouse stock, delivery records, or replacement policy.
Ces informations opérationnelles appartiennent à un agent d’exécution déployé séparément. Grâce à A2A, l'agent de support peut découvrir ce que fait l'agent d'exécution, lui envoyer l'enquête sous forme de tâche, suivre sa progression, répondre aux demandes d'informations supplémentaires et recevoir la décision finale de remplacement. Chaque service conserve son propre code, ses données, ses outils, son fournisseur de modèles et ses propres contrôles de sécurité ; ils partagent uniquement les messages, l'état des tâches et les artefacts définis par le contrat A2A.
Un coordinateur d’assistance lit la carte de l’agent d’exécution et confirme qu’il gère l’enquête sur les commandes et suit la progression.
Il envoie le numéro de commande, la demande du client, un messageId unique et un nouveau contexte de conversation.
L'agent distant ADK-Rust vérifie les outils de commande, l'inventaire, l'historique des livraisons et la politique de l'entreprise sans exposer ces éléments internes à l'appelant.
Si une preuve de dommage est requise, la tâche devient INPUT_REQUIRED au lieu de deviner ou d'échouer silencieusement.
Le coordinateur fournit les preuves approuvées en utilisant le même contextId ; l’histoire et l’identité des tâches restent intactes.
La tâche se termine avec l'historique des statuts et un artefact contenant la décision de remplacement et les étapes suivantes.
Sequence diagram
Read from top to bottom. The A2A service owns the network contract and task record. The fulfilment agent owns its reasoning and private tools.
Calling agent
Protocol boundary
ADK-Rust Runner
Orders · inventory · policy
GET /.well-known/agent-card.json
Discover skills and streaming
Agent Card
Fulfilment capability published
SendStreamingMessage
ORD-1042 · messageId msg-order-1042
Runner invocation
Create task and execute agent
order.lookup + policy.check
Use private business tools
Evidence required
Damage photo is missing
INPUT_REQUIRED
Persist state and context
SSE status update
Ask support for evidence
SendMessage · same contextId
Approved photo reference
Resume task
INPUT_REQUIRED → WORKING
inventory.reserve
Reserve replacement stock
Artifact + COMPLETED
Replacement decision
Final SSE events
Auditable result returned
Réponses aux codes et aux câbles
Ces exemples utilisent les mêmes noms d'opération v1, champs de message, états de tâche et formes de réponse SSE que l'implémentation ADK-Rust. Les identifiants et les détails de la commande sont corrigés afin que l'ensemble de la conversation soit facile à suivre.
let fulfilment = LlmAgentBuilder::new("fulfilment")
.description("Investigates orders and delivery")
.model(model)
.instruction(
"Use the approved order, inventory, and policy tools. Ask for evidence when the replacement policy requires it."
)
.build()?;
A2aServer::builder()
.agent(Arc::new(fulfilment))
.agent_card_name("Fulfilment Agent")
.streaming(true)
.build()?
.serve()
.await?;let fulfilment = RemoteA2aAgent::builder("fulfilment")
.description("Investigates orders and delivery")
.agent_url("https://agents.example.com/fulfilment")
.streaming(true)
.build()?;
let support = LlmAgentBuilder::new("support")
.model(model)
.instruction("Own the customer conversation.")
.sub_agent(Arc::new(fulfilment))
.build()?;{
"jsonrpc": "2.0",
"id": "replace-1",
"method": "SendStreamingMessage",
"params": {
"message": {
"messageId": "msg-order-1042",
"role": "ROLE_USER",
"parts": [{
"text": "Investigate damaged order ORD-1042 and prepare a replacement decision."
}]
}
}
}data: {
"jsonrpc":"2.0", "id":"replace-1",
"result":{"task":{
"id":"task-order-1042",
"contextId":"ctx-order-1042",
"status":{"state":"TASK_STATE_SUBMITTED"}
}}
}
data: {
"jsonrpc":"2.0", "id":"replace-1",
"result":{"statusUpdate":{
"taskId":"task-order-1042",
"contextId":"ctx-order-1042",
"status":{"state":"TASK_STATE_WORKING"}
}}
}{
"statusUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"status": {
"state": "TASK_STATE_INPUT_REQUIRED",
"message": {
"role": "ROLE_AGENT",
"parts": [{
"text": "Please provide a photo showing the damaged item."
}]
}
}
}
}{
"jsonrpc": "2.0",
"id": "replace-2",
"method": "SendMessage",
"params": {
"message": {
"messageId": "msg-order-1042-photo",
"contextId": "ctx-order-1042",
"role": "ROLE_USER",
"parts": [{
"text": "Evidence received and approved: damage-photo-8841.jpg"
}]
}
}
}{
"artifactUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"artifact": {
"artifactId": "replacement-decision-1042",
"name": "Replacement decision",
"parts": [{
"text": "Approved. Reserve SKU-RED-42 and dispatch with priority shipping."
}]
}
}
}
{
"statusUpdate": {
"taskId": "task-order-1042",
"contextId": "ctx-order-1042",
"status": { "state": "TASK_STATE_COMPLETED" }
}
}Le A2A v1 API
ADK-Rust implémente les 11 opérations dans A2A v1. Pour un travail court, appelez SendMessage et attendez le résultat de la tâche. Lorsque le travail peut prendre plus de temps, utilisez SendStreamingMessage pour recevoir d'abord la tâche, suivie des événements d'état et d'artefact en direct sur SSE.
L'ID de tâche renvoyé permet à votre client de se reconnecter sans soumettre à nouveau le travail. Il peut récupérer le dernier état, répertorier les tâches associées, s'abonner à d'autres mises à jour ou demander une annulation. Si le client ne peut pas maintenir une connexion ouverte, il peut enregistrer un webhook authentifié et laisser l'agent distant apporter des modifications ultérieures.
Envoyez un message et recevez soit une tâche complète, soit un flux en direct.
SendMessageSendStreamingMessageLisez le travail en cours, répertoriez les tâches correspondantes ou annulez une tâche lorsque son état le permet.
GetTaskListTasksCancelTaskOuvrez un abonnement SSE pour les mises à jour d'une tâche qui existe déjà.
SubscribeToTaskCréez, lisez, répertoriez et supprimez les destinations de webhook authentifiées pour une tâche.
CreatePushConfigGetPushConfigListPushConfigsDeletePushConfigDemandez la version étendue du profil de service publié d’un agent.
GetExtendedAgentCardLes routes JSON-RPC et REST sont réparties dans le même RequestHandler, de sorte que le comportement des tâches ne dérive pas entre les transports.
Les messages A2A entrants deviennent du contenu ADK-Rust. Le Runner exécute l'agent sélectionné et convertit ses événements en statut de tâche et en artefacts.
Un messageId répété renvoie la tâche existante plutôt que d'exécuter le même travail deux fois. Les déploiements de production doivent conserver ce mappage lors des redémarrages.
Le premier événement SSE est la tâche complète. Les événements ultérieurs comportent des mises à jour de statut et d'artefacts, de sorte qu'un client sait toujours à quoi appartient le flux.
RemoteA2aAgent implémente le trait d'agent ADK-Rust. Un coordinateur peut inclure un service réseau dans sa hiérarchie d'agents et recevoir des événements de structure normaux.
La négociation de version, la validation des messages, l'authentification du support, la limitation du débit, les intercepteurs d'audit, l'authentification des webhooks et les contrôles SSRF peuvent protéger le service.
Choisissez la bonne limite
A2A introduit un réseau, un contrat public, l'authentification, la gestion des pannes et l'état des tâches à distance. Ces coûts sont précieux lorsqu’ils créent une réelle indépendance ; ils sont inutiles lorsque tous les agents vivent déjà dans le même processus.
Sous-agent local
Agent A2A distant
De l'agent Rust au service réseau
Le serveur pratique crée une application Axum avec une carte d'agent, des sessions, des itinéraires A2A et la diffusion en continu activés. L'adaptateur distant découvre ce service et reconvertit ses mises à jour de tâches en événements ADK-Rust.
use adk_server::a2a::convenience::A2aServer;
let app = A2aServer::quick_start(agent);
let listener = tokio::net::TcpListener::bind(
"0.0.0.0:8080"
).await?;
axum::serve(listener, app).await?;use adk_server::a2a::RemoteA2aAgent;
let fulfilment = RemoteA2aAgent::builder("fulfilment")
.description("Investigates orders and delivery")
.agent_url("https://agents.example.com/fulfilment")
.build()?;
let coordinator = LlmAgentBuilder::new("support")
.model(model)
.sub_agent(Arc::new(fulfilment))
.build()?;RequestHandler::with_runner chemin pour choisir explicitement le magasin de tâches, l'expéditeur push, la carte d'agent, les services Runner, la route JSON-RPC, le routeur REST et le middleware de négociation de version.Avant la production
ADK-Rust fournit les types v1, les gestionnaires, le cycle de vie, les clients, la validation, les primitives de livraison et l'intégration avec Runner. La préparation à la production dépend toujours des politiques de stockage, d’identité, de réseau, d’observabilité et d’exploitation sélectionnées pour votre service.
Annoncez uniquement les compétences, les liaisons, le streaming, la livraison push et les systèmes de sécurité réellement pris en charge par le déploiement.
Le InMemoryTaskStore inclus et la carte d'idempotence en mémoire sont utiles pour le développement. Les travaux de production de longue durée nécessitent un stockage qui survit aux redémarrages des processus.
Authentifiez les appels entrants et protégez la livraison push sortante. L'expéditeur push HTTP prend en charge les informations d'identification du porteur, les jetons de notification, les tentatives et le rejet d'adresse privée.
Le travail à distance peut survivre à une demande. Définissez les délais d'attente des clients, la politique d'annulation, le comportement des nouvelles tentatives et ce qui se passe lorsque l'un des services devient indisponible.
Connecter le système d'agent
Commencez avec une carte d'agent honnête et une tâche utile. Ajoutez le streaming, la saisie multi-tours, la persistance des tâches, les abonnements, le push authentifié et les contrôles de limites à mesure que le travail devient plus long et que le service devient plus important.