Exemplo A2A Java

Clonar Código

git clone https://github.com/google-a2a/a2a-samples
cd a2a-samples/samples/java

Este projeto é um exemplo de implementação Java do protocolo Agent2Agent (A2A), fornecendo SDKs completos de cliente e servidor, juntamente com uma aplicação de demonstração de serviço de tradução alimentado por IA.

Arquitetura do Projeto

Este projeto usa uma arquitetura Maven multi-módulo, contendo os seguintes três módulos principais:

samples/java/
├── model/          # Modelos de Dados do Protocolo A2A
├── server/         # SDK do Servidor A2A & Serviço de Tradução
├── client/         # SDK do Cliente A2A & Código de Exemplo
└── pom.xml         # Arquivo de Configuração Maven Principal

Detalhes dos Módulos

🎯 Módulo Model (model/)

Modelos de dados principais para o protocolo A2A, fornecendo estruturas de dados completas para JSON-RPC 2.0 e protocolo A2A:

• Modelos de Mensagem: Message, Part, TextPart, Artifact
• Modelos de Tarefa: Task, TaskStatus, TaskState
• Modelos de Agente: AgentCard, AgentCapabilities, AgentSkill
• Modelos JSON-RPC: JSONRPCRequest, JSONRPCResponse, JSONRPCError
• Modelos de Evento: TaskStatusUpdateEvent, TaskArtifactUpdateEvent

🚀 Módulo Server (server/)

SDK do servidor A2A baseado em Spring Boot, integrado com framework Spring AI:

• Componentes Principais:

  • A2AServer: Classe principal do servidor gerenciando comportamento do agente
  • A2AController: Controlador REST implementando endpoints do protocolo A2A
  • TaskHandler: Interface de processamento de tarefas
  • A2AServerConfiguration: Configuração do bot de tradução IA

• Recursos Principais:

  • Suporte completo ao JSON-RPC 2.0
  • Publicação de cartão de agente (/.well-known/agent-card)
  • Gerenciamento de tarefas (enviar, consultar, cancelar)
  • Suporte a resposta em streaming (Server-Sent Events)
  • Integração Spring AI suportando OpenAI e outros modelos

📱 Módulo Client (client/)

SDK cliente A2A Java puro com exemplos de cliente de tradução:

• Componentes Principais:

  • A2AClient: Classe principal do cliente lidando com todas as operações A2A
  • StreamingEventListener: Interface de ouvinte de eventos de streaming
  • A2AClientException: Tratamento de exceções específicas do A2A
  • A2AClientExample: Exemplo completo de cliente de tradução

• Recursos Principais:

  • Implementação de cliente JSON-RPC 2.0
  • Descoberta de agente e consulta de capacidades
  • Operações de tarefa síncronas/assíncronas
  • Tratamento de resposta em streaming
  • Pool de conexões e recuperação de erros

Implementação da Funcionalidade Principal

🤖 Serviço de Tradução IA

O projeto implementa um agente de tradução inteligente suportando tradução multilíngue:

Lógica de Tradução:

• Chinês → Inglês
• Inglês → Chinês
• Outras línguas → Inglês

Recursos Técnicos:

• Baseado em Spring AI ChatClient
• Suporta OpenAI, Azure OpenAI e outros modelos
• Tradução de linguagem natural consciente do contexto
• Respostas em streaming em tempo real

🔄 Implementação do Protocolo A2A

Implementação completa das especificações do protocolo A2A:

Operações Principais:

• tasks/send: Enviar mensagens de tarefa
• tasks/get: Consultar status da tarefa
• tasks/cancel: Cancelar execução da tarefa

Recursos do Protocolo:

• Comunicação JSON-RPC 2.0
• Descoberta de capacidades do agente
• Rastreamento de status da tarefa
• Push de eventos em streaming
• Códigos de erro padronizados

📡 Mecanismos de Comunicação

Comunicação Síncrona:

• HTTP POST /a2a - Requisições JSON-RPC padrão
• HTTP GET /.well-known/agent-card - Recuperação de informações do agente

Comunicação em Streaming:

• HTTP POST /a2a/stream - Server-Sent Events
• Atualizações de status de tarefa em tempo real
• Reconexão automática e recuperação de erros

Como Executar

Requisitos

• Java: 17 ou superior

Passo 1: Compilar o Projeto

Execute a compilação no diretório raiz do projeto:

cd samples/java
./mvnw clean install -DskipTests

Passo 2: Configurar Variáveis de Ambiente

Defina variáveis de ambiente relacionadas ao modelo IA (necessário para funcionalidade de tradução):

# Configuração OpenAI
export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_BASE_URL="https://api.openai.com"
export OPENAI_CHAT_MODEL="gpt-4o"

# Ou Configuração GCP OpenAI
export OPENAI_API_KEY="your-gcp-api-key"
export OPENAI_BASE_URL="https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi"
export OPENAI_CHAT_MODEL="gemini-2.5-pro-preview-05-06"

Configuração OpenRouter

export OPENAI_API_KEY="sk-or-v1-"
export OPENAI_BASE_URL="https://openrouter.ai/api"
export OPENAI_CHAT_MODEL="openai/gpt-4o-2024-11-20"

Preste atenção ao OPENAI_BASE_URL, não há /v1 na URL.

Passo 3: Iniciar o Servidor de Tradução

Inicie o servidor de tradução A2A:

cd server
../mvnw spring-boot:run

O servidor iniciará em http://localhost:8080, fornecendo os seguintes endpoints:

• http://localhost:8080/.well-known/agent-card - Informações do agente
• http://localhost:8080/a2a - Endpoint do protocolo A2A
• http://localhost:8080/a2a/stream - Endpoint de streaming

Validar o Cartão do Agente:

• Validador do Protocolo A2A
• Guia: Como validar seu cartão de agente

Passo 4: Executar o Cliente de Tradução

Em uma nova janela de terminal, execute o exemplo do cliente:

cd client
../mvnw exec:java -Dexec.mainClass="com.google.a2a.client.A2AClientExample"

Diagrama de Sequência

O seguinte diagrama de sequência ilustra o fluxo completo de interação da aplicação de exemplo A2A Java, baseado no A2AClientExample.java:

sequenceDiagram
    participant Example as A2AClientExample
    participant Client as A2AClient
    participant Server as A2A Server<br/>(localhost:8080)
    
    Note over Example,Server: Diagrama de Sequência do Exemplo A2A Java
    
    %% 1. Initialize Client
    Example->>Client: new A2AClient("http://localhost:8080")
    activate Client
    
    %% 2. Get Agent Card
    Example->>Client: getAgentCard()
    Client->>Server: GET /.well-known/agent-card
    Server-->>Client: AgentCard (name, description, version, skills)
    Client-->>Example: AgentCard
    Note over Example: Imprimir informações do agente
    
    %% 3. French to Chinese Translation
    Example->>Client: sendTask(frenchToChineseParams)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Imprimir resultado da tradução
    
    %% 4. Chinese to English Translation
    Example->>Client: sendTask(chineseParams)
    Note right of Example: TextPart: "你好，世界！<br/>欢迎使用AI翻译机器人。"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Imprimir resultado da tradução
    
    %% 5. Streaming Translation
    Example->>Client: sendTaskStreaming(frenchParams, StreamingEventListener)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a/stream<br/>Server-Sent Events
    activate Server
    
    loop Resposta em Streaming
        Server-->>Client: SSE Event (progresso da tradução)
        Client-->>Example: onEvent(event)
        Note over Example: Imprimir eventos de tradução em tempo real
    end
    
    Server-->>Client: SSE Complete
    deactivate Server
    Client-->>Example: onComplete()
    Note over Example: Tradução em streaming concluída
    
    %% 6. Query Task Status
    Example->>Client: getTask(queryParams)
    Note right of Example: Consultar status da tarefa de tradução francesa
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/get
    Server-->>Client: Task (status atualizado)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Imprimir status da tarefa
    
    %% 7. Send Task to be Canceled
    Example->>Client: sendTask(cancelParams)
    Note right of Example: TextPart: "Diese Übersetzung<br/>wird abgebrochen." (Alemão)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status)
    Client-->>Example: JSONRPCResponse<Task>
    
    %% 8. Cancel Task
    Example->>Client: cancelTask(cancelTaskParams)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/cancel
    Server-->>Client: Task (status cancelado)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: Imprimir resultado do cancelamento
    
    deactivate Client
    Note over Example,Server: Execução do programa de exemplo concluída

Padrões de Interação Principais

O diagrama de sequência demonstra os seguintes padrões de interação principais:

1. Inicialização do Cliente: Criando uma instância A2AClient conectada ao servidor local
2. Descoberta do Agente: Recuperando informações do agente via endpoint /.well-known/agent-card
3. Exemplos de Tradução Multilíngue:
   • Tradução Francês → Chinês
   • Tradução Chinês → Inglês
   • Tradução em streaming Alemão → Inglês
4. Gerenciamento de Tarefas:
   • Consulta de status da tarefa
   • Cancelamento da execução da tarefa

Mecanismos de Comunicação

• Tradução Síncrona: Usando endpoint POST /a2a com requisições JSON-RPC
• Tradução em Streaming: Usando endpoint POST /a2a/stream com Server-Sent Events (SSE)
• Consultas de Status: Usando método tasks/get para verificar status de execução da tarefa
• Cancelamento de Tarefa: Usando método tasks/cancel para cancelar tarefas em execução

Exemplos de Uso da API

Obter Informações do Agente

curl -X GET http://localhost:8080/.well-known/agent-card \
  -H "Accept: application/json"

Enviar Tarefa de Tradução

curl -X POST http://localhost:8080/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "tasks/send",
    "params": {
      "id": "translation-task-1",
      "message": {
        "messageId": "msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

Tradução em Streaming

curl -X POST http://localhost:8080/a2a/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "stream-request-1",
    "method": "tasks/send",
    "params": {
      "id": "streaming-translation-task",
      "message": {
        "messageId": "stream-msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello world!"
          }
        ]
      }
    }
  }'