Protocolo Agent2Agent · A2A v1.0

Deixe agentes implantados de forma independente trabalhar juntos.

A2A oferece a um agente de IA uma maneira padrão de se apresentar a outro agente, aceitar um trabalho ou tarefa, relatar o progresso, solicitar mais informações e retornar resultados úteis – mesmo quando o outro agente é executado em um serviço de IA diferente, usa uma linguagem de programação ou estrutura de agente diferente ou é implantado em outra nuvem. Nenhum dos agentes precisa entender como o outro é construído. Eles usam o padrão A2A para se comunicar e trabalhar juntos.

Veja a arquitetura Crie um agente A2A

11 operações v1Cartões de AgenteJSON-RPC + RESTTransmissão SSETarefas multivoltasPush autenticadoRemoteA2aAgent

Arquitetura de referência ADK-Rust A2A

Arquitetura de agentes remotos A2A

The network contract stays separate from the agent's model, tools, memory, and internal orchestration.

Sistema de chamada

O agente ou aplicativo solicitando que outro agente trabalhe.

Agente coordenador

Decide qual especialista remoto deve receber a tarefa.

Cliente A2A

Descobre o cartão, escolhe o streaming e envia mensagens de protocolo.

HTTPS

Limite de serviço A2A

O contrato público que todo cliente compatível pode entender.

Cartão de Agente

Nome, habilidades, endpoint, versão do protocolo, segurança e recursos declarados.

Solicitar verificações

Versão, tipo de conteúdo, IDs, partes da mensagem, metadados, identidade e limites.

Gerenciador de solicitações

Despacha operações JSON-RPC ou REST por meio de uma implementação compartilhada.

chamada tipada

Tempo de execução ADK-Rust

A estrutura executa a tarefa e produz progresso tipado.

Runner

Cria o contexto de invocação e transmite eventos do agente.

Sistema de agente

LLM, fluxo de trabalho, gráfico, lógica personalizada ou multiagente.

Ferramentas

Ferramentas Rust e MCP

Estado

Sessões e memória

o estado da tarefa e os eventos são registrados enquanto o agente trabalha

Ciclo de vida da tarefa

Uma máquina de estado validada torna o trabalho de longa duração inspecionável.

Armazenamento de tarefas

Status, contexto, histórico, artefatos, metadados e configuração push.

Máquina de estado

Somente transições válidas são aceitas; tarefas terminais permanecem terminais.

Entrega de progresso

O chamador escolhe como deseja receber o troco.

Resposta direta

Retorne a tarefa completa e seus artefatos.

Fluxo SSE

Tarefa primeiro, depois atualizações de status e artefatos.

Trabalhe após a solicitação

Tarefas longas podem ser reportadas posteriormente sem manter uma conexão aberta.

Assinatura

Um cliente escuta atualizações para uma tarefa existente.

Empurrar webhook

Entrega autenticada com novas tentativas e verificações SSRF.

ADK-Rust mantém o contrato de transferência A2A, o ciclo de vida da tarefa, a execução do agente e os canais de entrega como peças separadas para que cada um possa ser protegido, testado e substituído de forma independente.

Comece com a ideia

Como posso trabalhar com um agente de IA hospedado externamente?

Dentro de um processo ADK-Rust, os agentes podem compartilhar tipos Rust, sessões, ferramentas e chamadas de função diretas. Quando um agente pertence a outro serviço – ou a outra organização – esses detalhes de implementação privada não constituem mais um contrato seguro.

A2A define o idioma compartilhado nesse limite. O chamador descobre o que o agente remoto oferece, envia uma mensagem estruturada, segue uma tarefa por meio de estados conhecidos e recebe artefatos sem precisar saber qual modelo, estrutura ou ferramentas são executadas por trás do endpoint.

ADK-Rust implementa A2A v1 em adk-server e conecta o protocolo diretamente ao Runner. O mesmo agente que você testa localmente pode se tornar um serviço de rede, enquanto RemoteA2aAgent permite que outro sistema ADK-Rust o consuma por meio da interface normal do Agente.

Cartão de Agente

Um perfil de serviço para um agente

Um pequeno documento público informa aos chamadores o nome do agente, endpoint, habilidades, versão do protocolo, requisitos de segurança e se ele oferece suporte a streaming ou notificações.

Mensagem

O que um agente diz para outro

Uma mensagem carrega uma função, um ID exclusivo e uma ou mais partes, como texto ou dados estruturados. O ID exclusivo possibilita novas tentativas seguras.

Tarefa

O trabalho que ambos os sistemas podem seguir

Uma tarefa fornece ao trabalho remoto um ID, um contexto de conversa, um estado, histórico de mensagens, metadados e quaisquer artefatos produzidos ao longo do caminho.

Artefato

O resultado útil do trabalho

Um artefato é um resultado nomeado anexado à tarefa: um relatório, decisão, plano, arquivo gerado ou outra saída estruturada que outro sistema pode usar.

Siga um trabalho

O protocolo carrega tanto a solicitação quanto a vida da obra.

Um chamador pode esperar por uma resposta, abrir um stream de evento ao vivo, inscrever-se em uma tarefa existente ou registrar um webhook para atualizações posteriores. A identidade e o contexto da tarefa mantêm cada modo de entrega vinculado ao mesmo trabalho.

Máquina de estado de tarefa

Um trabalho remoto tem uma vida que você pode seguir.

A2A faz mais do que retornar texto. Dá ao trabalho uma identidade, um contexto de conversação, um estado atual, uma história e artefatos. ADK-Rust valida cada transição antes de salvá-la.

SUBMITTED

O servidor aceitou a tarefa.

WORKING

O agente está executando.

INPUT REQUIRED

O agente precisa de mais informações.

AUTH REQUIRED

O chamador deve fornecer autorização.

COMPLETED

O trabalho e os artefatos estão prontos.

FAILED

A execução terminou com um erro.

CANCELED

Um cancelamento permitido encerrou a tarefa.

REJECTED

O servidor recusou a tarefa.

Trabalho multivoltas: quando uma tarefa atinge INPUT_REQUIRED, o chamador envia outra mensagem com o mesmo contextId. ADK-Rust encontra a tarefa e a retorna para WORKING, anexa a mensagem e continua o mesmo trabalho.

Fluxo lógico do mundo real

Case Study: Resolve a customer's damaged order across two distinct agent services.

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.

Essas informações operacionais pertencem a um agente de atendimento implantado separadamente. Através do A2A, o agente de suporte pode descobrir o que o agente de atendimento faz, enviar-lhe a investigação como uma tarefa, acompanhar seu andamento, atender solicitações de mais informações e receber a decisão final de substituição. Cada serviço mantém seu próprio código, dados, ferramentas, provedor de modelo e controles de segurança; eles compartilham apenas as mensagens, o estado da tarefa e os artefatos definidos pelo contrato A2A.

Conheça o especialista

Um coordenador de suporte lê o cartão do agente de atendimento e confirma que ele cuida da investigação do pedido e transmite o progresso.

Envie um trabalho claro

Ele envia o número do pedido, a solicitação do cliente, um messageId exclusivo e um novo contexto de conversa.

Rota dentro do serviço

O agente ADK-Rust remoto verifica as ferramentas de pedido, o estoque, o histórico de entrega e a política da empresa sem expor esses detalhes internos ao chamador.

Pergunte o que está faltando

Se for necessária prova de dano, a tarefa se torna INPUT_REQUIRED em vez de adivinhar ou falhar silenciosamente.

Retomar a mesma tarefa

O coordenador fornece as evidências aprovadas usando o mesmo contextId; o histórico e a identidade da tarefa permanecem intactos.

Retornar um resultado auditável

A tarefa é concluída com o histórico de status e um artefato contendo a decisão de substituição e as próximas etapas.

Sequence diagram

The task pauses and resumes without losing its identity.

Read from top to bottom. The A2A service owns the network contract and task record. The fulfilment agent owns its reasoning and private tools.

Support coordinator

Calling agent

A2A service

Protocol boundary

Fulfilment agent

ADK-Rust Runner

Business systems

Orders · inventory · policy

chamadas através de A2A

despachos para Runner

usa ferramentas aprovadas

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

The support coordinator never receives database credentials or fulfilment code. It receives only the Agent Card, protocol events, task state, and final artifact.

Respostas de código e fio

Veja o que cada lado envia e recebe.

Esses exemplos usam os mesmos nomes de operação v1, campos de mensagem, estados de tarefa e formatos de resposta SSE que a implementação ADK-Rust. IDs e detalhes do pedido são fixos para que toda a conversa seja fácil de acompanhar.

fulfilment.rsSERVIÇO DE CUMPRIMENTO · FERRUGEM

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?;

support.rsCOORDENADOR DE SUPORTE · RUST

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()?;

SendStreamingMessage.json1 · ENVIE O TRABALHO

{
    "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."
        }]
      }
    }
  }

text/event-stream2 · PROGRESSO DA TAREFA DE TRANSMISSÃO

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"}
    }}
  }

input-required.event.json3 · SOLICITE A EVIDÊNCIA FALTA

{
    "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."
          }]
        }
      }
    }
  }

SendMessage.follow-up.json4 · RETOMAR A MESMA TAREFA

{
    "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"
        }]
      }
    }
  }

final-events.json5 · RECEBA O ARTEFATO E CONCLUSÃO

{
    "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" }
    }
  }

O A2A v1 API

Tudo o que um cliente precisa para iniciar, acompanhar e finalizar o trabalho em um agente remoto.

ADK-Rust implementa todas as 11 operações no A2A v1. Para um trabalho curto, ligue para SendMessage e aguarde o resultado da tarefa. Quando o trabalho demorar mais, use SendStreamingMessage para receber a tarefa primeiro, seguido pelo status ao vivo e eventos de artefato em SSE.

O ID da tarefa retornado permite que seu cliente se reconecte sem enviar o trabalho novamente. Ele pode buscar o estado mais recente, listar tarefas relacionadas, assinar atualizações adicionais ou solicitar cancelamento. Se o cliente não conseguir manter uma conexão aberta, ele poderá registrar um webhook autenticado e permitir que o agente remoto entregue alterações posteriores.

Comece a trabalhar

Envie uma mensagem e receba uma tarefa completa ou uma transmissão ao vivo.

SendMessageSendStreamingMessage

Inspecione e controle

Leia o trabalho atual, liste tarefas correspondentes ou cancele uma tarefa quando seu estado permitir.

GetTaskListTasksCancelTask

Acompanhe o progresso

Abra uma assinatura SSE para atualizações de uma tarefa que já existe.

SubscribeToTask

Receba atualizações posteriores

Crie, leia, liste e remova destinos de webhook autenticados para uma tarefa.

CreatePushConfigGetPushConfigListPushConfigsDeletePushConfig

Descubra mais

Solicite a versão estendida do perfil de serviço publicado de um agente.

GetExtendedAgentCard

Um manipulador para duas ligações

As rotas JSON-RPC e REST são despachadas para o mesmo RequestHandler, para que o comportamento da tarefa não mude entre os transportes.

Execução apoiada por Runner

As mensagens A2A recebidas tornam-se conteúdo ADK-Rust. O Runner executa o agente selecionado e converte seus eventos em status de tarefa e artefatos.

Novas tentativas seguras

Um messageId repetido retorna a tarefa existente em vez de executar o mesmo trabalho duas vezes. As implantações de produção devem persistir esse mapeamento durante as reinicializações.

Streaming que começa com contexto

O primeiro evento SSE é a tarefa completa. Eventos posteriores carregam atualizações de status e artefatos, para que um cliente sempre saiba a que fluxo pertence.

Agentes remotos se sentem locais

RemoteA2aAgent implementa a característica do Agente ADK-Rust. Um coordenador pode incluir um serviço de rede em sua hierarquia de agentes e receber eventos normais da estrutura.

Proteção na fronteira

Negociação de versão, validação de mensagem, autenticação de portador, limitação de taxa, interceptadores de auditoria, autenticação de webhook e verificações de SSRF podem proteger o serviço.

Escolha o limite certo

Subagente local vs agente A2A remoto

A2A apresenta uma rede, um contrato público, autenticação, tratamento de falhas e estado de tarefa remota. Esses custos são valiosos quando criam uma verdadeira independência; eles são desnecessários quando todos os agentes já vivem no mesmo processo.

Subagente local

Agente A2A remoto

Melhor ajuste

Agentes pertencentes a um aplicativo

Agentes implantados ou de propriedade independente

Comunicação

Chamadas de agente em processo e eventos tipados

HTTP, JSON-RPC ou REST e SSE

Estado compartilhado

Pode usar as mesmas sessões e serviços

Compartilha apenas mensagens, tarefas e artefatos declarados

Limite de falha

Um tempo de execução e implantação

Falhas de rede, tempo limite, novas tentativas e serviço remoto

Interoperabilidade

Componentes ADK-Rust

Qualquer linguagem ou estrutura compatível com A2A

Do agente Rust ao serviço de rede

Exponha um agente e depois consuma-o como agente.

O servidor de conveniência cria um aplicativo Axum com cartão de agente, sessões, rotas A2A e streaming habilitados. O adaptador remoto descobre esse serviço e converte suas atualizações de tarefas novamente em eventos ADK-Rust.

serve.rsExpor um agente

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?;

coordinator.rsLigue de outro agente

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()?;

Para um serviço v1 totalmente configurado: use o documentado RequestHandler::with_runner caminho para escolher explicitamente o armazenamento de tarefas, o remetente push, o cartão do agente, os serviços Runner, a rota JSON-RPC, o roteador REST e o middleware de negociação de versão.

Antes da produção

Implantando agentes A2A

ADK-Rust fornece os tipos v1, manipuladores, ciclo de vida, clientes, validação, primitivas de entrega e integração com o Runner. A prontidão da produção ainda depende das políticas de armazenamento, identidade, rede, observabilidade e operação selecionadas para o seu serviço.

Publique um cartão honesto

Anuncie apenas as habilidades, vinculações, streaming, entrega push e esquemas de segurança que a implantação realmente suporta.

Escolha o estado durável

O InMemoryTaskStore incluído e o mapa de idempotência na memória são úteis para o desenvolvimento. O trabalho de produção de longa duração precisa de armazenamento que sobreviva às reinicializações do processo.

Proteja ambas as direções

Autentique chamadas de entrada e proteja a entrega push de saída. O remetente push HTTP oferece suporte a credenciais de portador, tokens de notificação, novas tentativas e rejeição de endereço privado.

Cancelamento de design e tempos limite

O trabalho remoto pode sobreviver a uma solicitação. Defina os tempos limite do cliente, a política de cancelamento, o comportamento de novas tentativas e o que acontece quando um dos serviços fica indisponível.

Conecte o sistema do agente

Exponha seu agente por meio de uma interface A2A padrão.

Comece com uma Carta de Agente honesta e uma tarefa útil. Adicione streaming, entrada multiturno, persistência de tarefas, assinaturas, push autenticado e controles de limite à medida que o trabalho se torna mais longo e o serviço se torna mais importante.

Leia o guia A2A Inspecione um agente completo