Protocole Agent-à-Agent (A2A)

Le protocole Agent-à-Agent (A2A) permet aux agents de communiquer et de collaborer au-delà des limites du réseau. ADK-Rust offre un support complet pour l'exposition d'agents via A2A et la consommation d'agents A2A distants.

Vue d'ensemble

A2A est utile lorsque :

• Intégration avec des services d'agent tiers
• Construction d'architectures de microservices avec des agents spécialisés
• Activation de la communication d'agent inter-langages
• Application de contrats formels entre les systèmes d'agents

Pour une organisation interne simple, utilisez des sous-agents locaux au lieu d'A2A pour de meilleures performances.

Cartes d'Agent

Chaque agent A2A expose une carte d'agent qui décrit ses capacités. La carte est générée automatiquement et servie à l'adresse /.well-known/agent.json.

use adk_server::a2a::build_agent_card;

let agent_card = build_agent_card(&agent, "http://localhost:8080");

println!("Agent: {}", agent_card.name);
println!("Skills: {}", agent_card.skills.len());
println!("Streaming: {}", agent_card.capabilities.streaming);

La carte d'agent comprend :

• Nom et description de l'Agent
• URL de base pour la communication
• Capacités (streaming, historique d'état, etc.)
• Compétences dérivées de l'agent et de ses sous-agents

Exposer un Agent via A2A

Pour exposer un agent afin que d'autres agents puissent l'utiliser, créez un serveur HTTP avec des points d'extrémité A2A :

use adk_server::{create_app_with_a2a, ServerConfig};
use adk_agent::LlmAgentBuilder;
use adk_model::gemini::GeminiModel;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create your agent
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;
    let agent = LlmAgentBuilder::new("weather_agent")
        .description("Answers weather questions")
        .model(Arc::new(model))
        .build()?;

    // Create server config
    let config = ServerConfig::new(
        Arc::new(SingleAgentLoader::new(Arc::new(agent))),
        Arc::new(InMemorySessionService::new()),
    );

    // Create app with A2A support
    let app = create_app_with_a2a(config, Some("http://localhost:8080"));

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

    Ok(())
}

Ceci expose :

• GET /.well-known/agent.json - Carte d'agent
• POST /a2a - Point d'extrémité JSON-RPC pour le protocole A2A
• POST /a2a/stream - Point d'extrémité de streaming SSE

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
let root_agent = LlmAgentBuilder::new("root")
    .model(Arc::new(model))
    .sub_agent(Arc::new(remote_agent))
    .build()?;

Le RemoteA2aAgent :

• Récupère automatiquement la carte d'agent depuis l'URL distante
• Convertit les événements ADK vers/depuis les messages du protocole A2A
• Gère les réponses en streaming
• Fonctionne de manière transparente comme sous-agent

Client A2A

Pour une communication directe avec des agents distants, utilisez le A2aClient :

use adk_server::a2a::{A2aClient, Message, Part, Role};

// Create client from URL (fetches agent card)
let client = A2aClient::from_url("http://localhost:8080").await?;

// Build a message
let message = Message::builder()
    .role(Role::User)
    .parts(vec![Part::text("What's the weather?".to_string())])
    .message_id(uuid::Uuid::new_v4().to_string())
    .build();

// Send message (blocking)
let response = client.send_message(message.clone()).await?;

// Or send with streaming
let mut stream = client.send_streaming_message(message).await?;
while let Some(event) = stream.next().await {
    match event? {
        UpdateEvent::TaskArtifactUpdate(artifact) => {
            println!("Artifact: {:?}", artifact);
        }
        UpdateEvent::TaskStatusUpdate(status) => {
            println!("Status: {:?}", status.status.state);
        }
    }
}

Protocole JSON-RPC

adk-rust implémente le protocole A2A à l'aide de JSON-RPC 2.0. Méthodes prises en charge :

message/send

Envoyer un message à l'Agent :

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-123",
      "parts": [{"text": "Hello!"}]
    }
  },
  "id": 1
}

La réponse inclut un objet task avec le status et les artifacts.

message/stream

Identique à message/send mais renvoie des Server-Sent Events (SSE) pour les réponses en streaming.

tasks/cancel

Annuler une task en cours d'exécution :

{
  "jsonrpc": "2.0",
  "method": "tasks/cancel",
  "params": {
    "taskId": "task-123"
  },
  "id": 1
}

Exemple multi-agent

Combiner des agents locaux et distants :

// Local agent
let roll_agent = LlmAgentBuilder::new("roll_agent")
    .description("Rolls dice")
    .model(Arc::new(model.clone()))
    .tool(Arc::new(roll_die_tool))
    .build()?;

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

// Root agent orchestrates both
let root_agent = LlmAgentBuilder::new("root_agent")
    .instruction("Delegate dice rolling to roll_agent and prime checking to prime_agent")
    .model(Arc::new(model))
    .sub_agent(Arc::new(roll_agent))
    .sub_agent(Arc::new(prime_agent))
    .build()?;

Gestion des erreurs

Les opérations A2A renvoient des erreurs adk standard :

match client.send_message(message).await {
    Ok(response) => {
        if let Some(error) = response.error {
            eprintln!("RPC error: {} (code: {})", error.message, error.code);
        }
    }
    Err(e) => {
        eprintln!("Request failed: {}", e);
    }
}

Codes d'erreur courants :

• -32600: Requête invalide
• -32601: Méthode introuvable
• -32602: Paramètres invalides
• -32603: Erreur interne

Bonnes pratiques

1. Utiliser les agent cards : Toujours récupérer et valider les agent cards avant toute communication
2. Gérer le streaming : Utiliser le streaming pour les opérations de longue durée
3. Récupération d'erreurs : Implémenter une logique de nouvelle tentative pour les pannes réseau
4. Délais d'attente : Définir des délais d'attente appropriés pour les appels distants
5. Sécurité : Utiliser HTTPS en production et implémenter l'authentification

Configuration de sécurité

Configurez CORS, les timeouts et les security headers pour les déploiements en production :

use adk_server::{ServerConfig, SecurityConfig};
use std::time::Duration;

// Production configuration
let config = ServerConfig::new(agent_loader, session_service)
    .with_allowed_origins(vec![
        "https://myapp.com".to_string(),
        "https://admin.myapp.com".to_string(),
    ])
    .with_request_timeout(Duration::from_secs(30))
    .with_max_body_size(10 * 1024 * 1024);  // 10MB

// Or use presets
let dev_config = ServerConfig::new(agent_loader, session_service)
    .with_security(SecurityConfig::development());  // Permissive for dev

let prod_config = ServerConfig::new(agent_loader, session_service)
    .with_security(SecurityConfig::production(allowed_origins));

Les fonctionnalités de sécurité incluent :

• CORS : Origines autorisées configurables (par défaut : permissif pour le développement)
• Délai d'attente des requêtes : Délai d'attente configurable (par défaut : 30 secondes)
• Limite de taille du corps : Taille maximale du corps de la requête (par défaut : 10 Mo)
• En-têtes de sécurité : X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
• Assainissement des erreurs : Les erreurs internes sont journalisées mais non exposées aux clients en production

Lié

• LlmAgent - Création d'agents
• Systèmes multi-agents - Sub-agents et hiérarchies
• Déploiement de serveur - Exécution d'agents en tant que serveurs HTTP

---

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