Protocole Agent-à-Agent (A2A)

ADK-Rust implémente le A2A Protocol v1.0.0 pour la communication entre agents sur plusieurs réseaux. L’implémentation se trouve dans adk-server derrière le drapeau de fonctionnalité a2a-v1 et couvre les 11 opérations JSON-RPC, les liaisons REST, la découverte de carte d’agent et la négociation de version. Voir Couverture des opérations pour l’opération dont la sémantique est plus restreinte que ce que la spécification autorise. Les types de transport sont fournis par a2a-protocol-types — le A2A SDK Rust vérifié par la Fondation par @tomtom215 (a2a-rust).

Vue d’ensemble

A2A est utile lorsque :

• Intégration avec des services d’agents tiers
• Construction d’architectures de microservices avec des agents spécialisés
• Activation de la communication entre agents dans plusieurs langages (tout langage avec un client A2A)
• Application de contrats formels entre systèmes d’agents

Pour une organisation interne simple, utilisez des sous-agents locaux plutôt que A2A pour de meilleures performances.

Conformité v1.0.0

L’implémentation est entièrement conforme à la spécification A2A Protocol v1.0.0 :

Fiches d’agent

Chaque agent A2A expose une fiche d’agent à /.well-known/agent-card.json décrivant ses capacités, ses compétences et les interfaces prises en charge.

use adk_server::a2a::v1::card::build_v1_agent_card;
use a2a_protocol_types::{AgentCapabilities, AgentSkill};

let card = build_v1_agent_card(
    "my-agent",
    "A helpful research agent",
    "http://localhost:3001/jsonrpc",
    "1.0.0",
    vec![AgentSkill {
        id: "research".to_string(),
        name: "Research & Summarize".to_string(),
        description: "Researches topics and produces structured summaries".to_string(),
        tags: vec!["research".to_string()],
        examples: None,
        input_modes: None,
        output_modes: None,
        security_requirements: None,
    }],
    AgentCapabilities::none()
        .with_streaming(true)
        .with_push_notifications(true),
);

La fiche d’agent inclut :

• Nom, description et version de l’agent
• Interfaces prises en charge avec l’association de protocole et la version
• Capacités : streaming, pushNotifications, extendedAgentCard
• Compétences dérivées de la configuration de l’agent
• Modes d’entrée/sortie par défaut

Les capacités sont désormais déclarées explicitement via le paramètre AgentCapabilities — plus de valeurs par défaut codées en dur.

Exposer un agent via A2A v1

Créez un serveur A2A v1.0.0 complet avec l’intégration LLM :

use std::sync::Arc;
use a2a_protocol_types::{AgentCapabilities, AgentSkill};
use adk_agent::LlmAgentBuilder;
use adk_server::a2a::v1::card::{CachedAgentCard, build_v1_agent_card};
use adk_server::a2a::v1::executor::V1Executor;
use adk_server::a2a::v1::jsonrpc_handler::jsonrpc_handler;
use adk_server::a2a::v1::push::NoOpPushNotificationSender;
use adk_server::a2a::v1::request_handler::RequestHandler;
use adk_server::a2a::v1::rest_handler::rest_router;
use adk_server::a2a::v1::task_store::InMemoryTaskStore;
use adk_server::a2a::v1::version::version_negotiation;
use adk_runner::RunnerConfig;
use adk_session::InMemorySessionService;
use axum::Router;
use axum::routing::post;
use tokio::sync::RwLock;

// 1. Create your agent
let model = adk_model::GeminiModel::new(&api_key, "gemini-2.5-flash")?;
let agent = LlmAgentBuilder::new("my-agent")
    .description("A helpful agent")
    .model(Arc::new(model))
    .instruction("You are a helpful assistant.")
    .build()?;

// 2. Set up A2A infrastructure
let task_store = Arc::new(InMemoryTaskStore::new());
let executor = Arc::new(V1Executor::new(task_store.clone()));
let push_sender = Arc::new(NoOpPushNotificationSender);

// 3. Build agent card with capabilities
let card = build_v1_agent_card(
    "my-agent", "A helpful agent",
    "http://localhost:3001/jsonrpc", "1.0.0",
    vec![/* skills */],
    AgentCapabilities::none().with_streaming(true),
);
let cached_card = Arc::new(RwLock::new(CachedAgentCard::new(card)));

// 4. Create runner config for LLM invocation
let session_service = Arc::new(InMemorySessionService::new());
let runner_config = Arc::new(RunnerConfig {
    app_name: "my-agent".to_string(),
    agent: Arc::new(agent),
    session_service,
    artifact_service: None,
    memory_service: None,
    plugin_manager: None,
    run_config: None,
    compaction_config: None,
    context_cache_config: None,
    cache_capable: None,
    request_context: None,
    cancellation_token: None,
});

// 5. Wire up the handler and routes
let handler = Arc::new(RequestHandler::with_runner(
    executor, task_store, push_sender, cached_card, runner_config,
));

let app = Router::new()
    .route("/jsonrpc", post(jsonrpc_handler))
    .with_state(handler.clone())
    .merge(rest_router(handler))
    .layer(axum::middleware::from_fn(version_negotiation));

// 6. Serve
let listener = tokio::net::TcpListener::bind("0.0.0.0:3001").await?;
axum::serve(listener, app).await?;

Cela expose :

• GET /.well-known/agent-card.json — Fiche d’agent avec mise en cache ETag
• POST /jsonrpc — point de terminaison JSON-RPC (les 11 opérations v1 ; voir Operation coverage)
• Routes REST pour toutes les opérations
• Négociation d’en-tête A2A-Version sur toutes les routes

Opérations JSON-RPC

Les 11 opérations A2A v1.0.0 sont prises en charge :

SendMessage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-123",
      "role": "ROLE_USER",
      "parts": [{"text": "Research quantum computing"}]
    }
  }
}

La réponse inclut un objet Task avec status, history et artifacts. La réponse utilise Content-Type: application/a2a+json.

SendStreamingMessage

Même format de requête que SendMessage. Renvoie un flux SSE où :

1. Le premier événement est un objet Task complet (selon la spec §3.1.2)
2. Les événements suivants sont TaskStatusUpdateEvent (Working, Completed, etc.)
3. Les événements d’artifact sont TaskArtifactUpdateEvent

Conversations multi-tours

Lorsqu’une tâche atteint l’état INPUT_REQUIRED, envoyez un message de suivi avec le même contextId pour la reprendre :

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-456",
      "role": "ROLE_USER",
      "contextId": "ctx-original",
      "parts": [{"text": "Yes, include more details on error correction"}]
    }
  }
}

Le gestionnaire retrouve automatiquement la tâche existante par contextId, la fait passer de INPUT_REQUIRED à Working, ajoute le nouveau message à l’historique et poursuit le traitement.

Idempotence

Les requêtes SendMessage en double avec le même messageId renvoient la tâche créée précédemment sans retraitement. Cela s’applique à la fois à SendMessage et SendStreamingMessage.

Authentification des notifications push

Lorsqu’un client enregistre un webhook via CreateTaskPushNotificationConfig, le serveur inclut des en-têtes d’authentification lors des livraisons de webhook :

• Authorization: Bearer <credentials> — lorsque le champ authentication contient des identifiants bearer
• a2a-notification-token: <token> — lorsque le champ token est présent

Les deux en-têtes peuvent être définis simultanément. La protection SSRF valide la URLs du webhook par rapport aux plages d’IP privées et à localhost.

Validation des entrées

Toutes les requêtes entrantes sont validées avant traitement :

Consommer un agent distant

Utilisez RemoteA2aAgent pour communiquer avec un agent A2A distant :

use adk_server::a2a::RemoteA2aAgent;

let remote_agent = RemoteA2aAgent::builder("prime_checker")
    .description("Checks if numbers are prime")
    .agent_url("http://localhost:8001")
    .build()?;

// Use as a sub-agent in a local agent hierarchy
let root_agent = LlmAgentBuilder::new("root")
    .model(Arc::new(model))
    .sub_agent(Arc::new(remote_agent))
    .build()?;

Client A2A

Pour une communication directe au niveau du protocole :

use adk_server::a2a::client::v1_client::A2aV1Client;

// Discover agent card
let card = A2aV1Client::resolve_agent_card("http://localhost:3001").await?;
let client = A2aV1Client::new(card);

// Send message
let task = client.send_message(message).await?;

// Get task
let task = client.get_task(&task_id, Some(10)).await?;

// List tasks
let tasks = client.list_tasks(None, None, None, None).await?;

// Cancel task
client.cancel_task(&task_id).await?;

// Streaming
let response = client.send_streaming_message(message).await?;

// Push notification CRUD
let config = client.create_push_notification_config(config).await?;
client.delete_push_notification_config(&task_id, &config_id).await?;

Gestion des erreurs

Les erreurs A2A se mappent à la fois aux codes JSON-RPC et aux codes d’état HTTP :

Exécution des exemples

Deux agents exemples complets A2A v1.0.0 sont inclus :

cargo run --manifest-path examples/a2a-research-agent/Cargo.toml
cargo run --manifest-path examples/a2a-writing-agent/Cargo.toml --bin a2a-writing-agent
cargo run --manifest-path examples/a2a-writing-agent/Cargo.toml --bin client

Le client valide : la découverte de la carte de l’agent, SendMessage (les deux agents avec de vraies LLM), GetTask, ListTasks, le chemin d’erreur CancelTask, SendStreamingMessage, les notifications push CRUD, GetExtendedAgentCard, la négociation de version et les chemins d’erreur.

Bonnes pratiques

1. Déclarer les capacités avec précision — définissez streaming, pushNotifications en fonction de ce que votre agent prend réellement en charge
2. Utiliser le streaming pour les opérations longues — SendStreamingMessage fournit aux clients une progression en temps réel
3. Gérer les flux à plusieurs tours — utilisez contextId pour conserver l’état de la conversation entre les messages
4. Valider le webhook URLs — la protection SSRF est intégrée, mais utilisez HTTPS en production
5. Définir des délais d’expiration appropriés — configurez des délais d’expiration des requêtes pour les appels à des agents distants
6. Utiliser l’idempotence — les clients peuvent réessayer sans risque SendMessage avec le même messageId

Liés

• LlmAgent — Création d’agents
• Systèmes multi-agents — Sous-agents et hiérarchies
• Déploiement du serveur — Exécution d’agents en tant que serveurs HTTP

---

Précédent : ← Serveur | Suivant : Évaluation →

Couverture des opérations

Les 11 opérations v1 JSON-RPC sont toutes distribuées et implémentées.

SubscribeToTask est un instantané

L’opération renvoie la tâche et son état actuel, puis ferme le flux. Elle ne fournit pas les mises à jour ultérieures, donc un client ne doit pas l’attendre pour suivre la progression.

Une ré-attache en direct nécessite une file d’événements par tâche qui survit à la requête d’origine. Les implémentations de référence obtiennent cela à partir de leur A2A SDKs — adk-python et adk-go délèguent toutes deux tasks/resubscribe entièrement au gestionnaire de files de SDK, et aucune ne l’implémente dans le code ADK. Ce serveur est réalisé à la main sur a2a-protocol-types, qui fournit des types de protocole plutôt qu’un runtime de serveur, donc la file n’existe pas encore.

Utilisez SendStreamingMessage lorsque des mises à jour en direct sont requises.

Contrat des événements en flux

SendStreamingMessage traduit les événements d’agent au fur et à mesure de leur arrivée:

Tous les fragments d’une réponse partagent un identifiant d’artefact afin qu’un client puisse les réassembler. Le texte assemblé est conservé, donc une requête ultérieure GetTask renvoie ce qui a été diffusé. Cela correspond au contrat adk-python et adk-go implémentent sur leur SDKs.