Use o protocolo A2A na comunicação com os agentes de IA

O A2A, ou protocolo Agent2Agent, é um padrão aberto que permite a comunicação estruturada entre agentes de IA, clientes e ferramentas. Neste tutorial, você pode construir um sistema de agentes em que um cliente de chat processa as consultas do usuário e as envia para um agente de IA executado em um servidor compatível com o A2A.

A maioria das aplicações de IA agêntica implementa comunicação personalizada entre componentes (por exemplo, o ChatChain do ChatDev), dificultando a reutilização do mesmo agente em diferentes aplicações ou a integração de ferramentas externas. Essa falta de padronização impede a interoperabilidade e limita o desenvolvimento de um ecossistema de agentes mais amplo.

A A2A soluciona essa limitação separando a camada de comunicação da lógica do agente por meio de um protocolo padronizado criado em HTTP, JSON-RPC 2.0 e eventos enviados pelo servidor (SSE). Essa separação permite que os agentes colaborem com outros agentes, atendam às solicitações dos clientes e acessem ferramentas externas sem um código de integração personalizado.

O A2A é compatível com arquiteturas descentralizadas que permitem que as equipes evoluam seus sistemas de IA de forma incremental, sem quebrar o código do cliente. As equipes podem atualizar ferramentas, trocar modelos ou modificar o comportamento dos agentes enquanto mantêm uma interface consistente em fluxos de trabalho complexos.

Os agentes trocam informações em mensagens estruturadas no formato JSON-RPC, que incluem metadados que enriquecem as interações dos agentes com clareza e consistência. Cada servidor A2A expõe um AgentCard em um endpoint conhecido (.well-known/agent-card.json), que descreve os recursos do agente como dados JSON estruturados. Assim, ele permite que os clientes descubram dinamicamente o que um agente pode fazer, semelhante a como a documentação das APIs descreve os endpoints disponíveis.

Acompanhe para criar e executar um sistema de agentes A2A e ganhar experiência prática com:

• BeeAI: um framework agêntico de código aberto para a criação de agentes de IA.
• Protocolo A2A: um protocolo de comunicação padronizado para interoperabilidade de agentes.
• Ollama: uma ferramenta para executar grandes modelos de linguagem (LLMs) localmente.
• Ferramentas de agentes: Recursos especializados, incluindo pesquisa na web (DuckDuckGo), dados meteorológicos (OpenMeteo), acesso à Wikipedia (WikipediaTool) e raciocínio (ThinkTool)

Observação: se você já trabalhou com o ACP (Agent Communication Protocol), reconhece as semelhanças. O ACP, originalmente desenvolvido pelo BeeAI da IBM, uniu forças com o Google A2A sob a Linux Foundation. O BeeAI agora usa adaptadores A2A (A2AServer e A2AAgent) para fornecer comunicação compatível com A2A. O A2A também trabalha ao lado do MCP (Model Context Protocol) para permitir que os agentes interajam com fontes de dados e ferramentas, criando ecossistemas de agentes interoperáveis.

Este projeto demonstra como o A2A permite uma separação clara entre a interface do cliente e a lógica do agente.

O fluxo de trabalho segue esta sequência:

1. Entrada do usuário: o cliente captura a entrada do usuário por meio da interface do terminal.
2. Solicitação A2A: o cliente formata a entrada como uma carga útil de mensagem JSON-RPC e a envia para o servidor do agente.
3. Processamento de agentes: o servidor encaminha a solicitação para oRequirementAgent , que analisa a tarefa e executa as ferramentas apropriadas conforme a necessidade.
4. Resposta A2A: o servidor retorna a resposta do agente como dados estruturados no formato JSON-RPC, transmitindo os resultados em tempo real à medida que são gerados.
5. Exibição: o cliente extrai e exibe o texto da resposta no terminal.

Esse fluxo de trabalho demonstra um padrão reutilizável aplicável a casos de uso que exigem comunicação estruturada entre cliente e agente, como chatbots, sistemas de automação de tarefas, agentes de suporte ao cliente e assistentes de pesquisa com orquestração de ferramentas.

Este projeto usa um único agente de IA com vários recursos de ferramentas. Em sistemas mais complexos, você pode implementar vários agentes especializados, cada um focado em domínios ou tarefas específicas.

RequirementAgent (BeeAI): um agente declarativo que seleciona e coordena dinamicamente várias ferramentas com base na solicitação do usuário. Ele usa:

• ThinkTool para raciocínio e operações lógicas
• DuckDuckGoSearchTool para buscas na web
• OpenMeteoTool  para dados meteorológicos
• WikipediaTool para recuperação de informações

O servidor A2A (beeai-a2a-server/beeai_chat_server.py ) expõe a funcionalidade do agente por meio de uma API HTTP. Lida com três responsabilidades principais:

1. inicialização do LLM: carrega um modelo de idioma local por meio do Ollama

2. Configuração de agentes: cria um RequirementAgent com ferramentas e memória para lidar com o ciclo de vida dos agentes

3. Configuração do servidor: expõe o agente por meio de endpoint HTTP compatível com A2A

O servidor expõe automaticamente um AgentCard em /.well-known/agent-card.json que descreve os recursos dos agentes e ajuda a validar as configurações dos agentes.

O cliente A2A (beeai-a2a-client/beeai_chat_client.py ) fornece a interface do usuário e lida com a comunicação com o servidor usando o A2A SDK e a biblioteca assíncrona do Python para o processamento de mensagens assíncronas.

Configuração de conexão: cria um adaptador de cliente A2A

Ourl o parâmetro especifica o endpoint do servidor compatível com A2A (padrão:http://127.0.0.1:9999 ). Omemory o parâmetro armazena o histórico de conversas localmente, permitindo que o cliente mantenha o contexto durante as interações e é compatível com tarefas de longa duração.

Troca de mensagens: envia prompts assíncronos e processa respostas:

OA2AAgent é um adaptador do lado do cliente que abstrai os detalhes da comunicação JSON-RPC. Não é um agente autônomo: ele simplesmente converte a entrada do usuário em mensagens compatíveis com A2A e lida com as respostas do servidor, permitindo a troca de dados e a observabilidade sem dificuldades.

Estes são os requisitos do sistema para executar este projeto:

• Sistema operacional: macOS, Linux ou Windows
• Memória (RAM): >= 8 GB (recomendado: 16 GB ou mais para executar LLMs locais)
• Espaço em disco: >= 5 GB de espaço livre (recomendado: 10 GB ou mais para acomodar o ambiente do Python e os modelos locais)
• Versão do Python: >= 3.11

Antes de começar, aqui está uma visão geral das ferramentas necessárias para este projeto:

• BeeAI: um kit de desenvolvimento de agentes de código aberto para a criação de agentes de IA. O BeeAI é compatível com vários provedores de LLMs, incluindo Ollama (usado neste tutorial), OpenAI e Anthropic.
• Ollama: para executar LLMs locais para alimentar o agente de IA.
• Protocolo A2A: integrado ao framework BeeAI para permitir comunicação estruturada entre o cliente e o servidor.
  
• Terminal ou IDE: um terminal ou IDE semelhante ao Visual Studio Code (recomendado para gerenciar vários terminais e visualizar logs).
  
• Ambiente virtual do Python: para isolar dependências para o cliente e o servidor.

Esse projeto usa o Ollama como provedor de modelos para o agente de IA. Siga estas etapas para configurar o Ollama:

1. Baixe e instale o Ollama:
   -     Acesse Ollama e instale a aplicação para seu sistema operacional
2. Inicie o servidor Ollama 
   -   Abra um terminal e execute:
   ollama serve
3. Use o modelo padrão (requer aproximadamente 5 GB de espaço em disco):
   
   ollama pull granite3.3:8b

Observação: você pode usar qualquer modelo compatível com o Ollama configurando aBEEAI_MODEL variável de ambiente. Verifique a biblioteca de modelos Ollama para obter modelos disponíveis e seus tamanhos.

Para executar esse projeto, clone o repositório do GitHub usando https://github.com/IBM/ibmdotcom-tutorials.git como a URL HTTPS. Para ver etapas detalhadas sobre como clonar um repositório, consulte a documentação do GitHub.

Este tutorial pode ser encontrado dentro do diretório de projetos do repo.

Dentro de um terminal, navegue até o diretório deste tutorial:

Este projeto exige dois scripts Python separados para execução simultânea, um para o servidor e o outro para o cliente. Você precisa abrir duas janelas ou guias de terminal.

Mantenha seu terminal atual aberto e, em seguida, abra um segundo terminal e certifique-se de que ambos sejam navegados para o diretório de projeto correto (oa2a_tutorial diretório raiz).

Usando um IDE?

Se você estiver usando um IDE como o Visual Studio Code, você pode usar a funcionalidade Dividir terminal para gerenciar vários terminais lado a lado.

Caso contrário, abra duas janelas de terminal independentes e navegue até o diretório do projeto.

Os ambientes virtuais ajudam a deixar as dependências separadas e com manutenção. Para manter as dependências do servidor e do cliente separadas, crie um ambiente virtual para cada componente.

Para o servidor:

Navegue até obeeai-a2a-server diretório:

Crie um ambiente virtual com o Python 3.11:

Ative o ambiente virtual:

Observação para usuários do Windows: use venv\Scripts\activate para ativar o ambiente virtual.

Para o cliente:

Navegue até obeeai-a2a-client diretório:

Crie e ative um ambiente virtual:

Instale as dependências necessárias para cada componente executando este código em cada terminal:

Você pode executarpip freeze no terminal para verificar se o ambiente está atualizado com as dependências.

No primeiro terminal, inicie o servidor do agente A2A:

Você deverá ver:

O servidor agora está atendendo às solicitações recebidas da aplicação do cliente, pronto para atender à comunicação entre agentes.

No outro terminal, inicie o cliente A2A:  

Isso deve solicitar uma entrada de sua parte:

Digite uma mensagem no terminal do cliente e pressioneEnter . O agente processa sua consulta e responderá:

No terminal do servidor, é possível ver os logs do protocolo A2A mostrando a comunicação com notificações por push:

A primeira solicitação recupera o AgentCard que descreve os recursos do agente. A segunda solicitação envia sua mensagem como umTextPart (uma unidade de conteúdo de texto na mensagem A2A) e recebe a resposta.

Observação: as saídas dos LLMs são probabilísticas e podem variar cada vez que você executa o fluxo de trabalho, mesmo com a mesma entrada.

Experimente com diferentes tipos de consultas para testar as várias ferramentas do agente:

• Pesquisa na web: "Pesquise notícias recentes sobre inteligência artificial"
• Dados meteorológicos: "Como está o clima em Tóquio?"
• Wikipedia: “Fale-me sobre computação quântica”
• Raciocínio: "Quais são as três razões pelas quais o céu é azul?"

Navegue até https://0.0.0.0:9999/.well-known/agent-card.json no seu navegador para visualizar oRequirementAgent do AgentCard.

Este documento JSON descreve:

• O nome do agente (RequirementAgent) e uma breve descrição de seus recursos.
• Os protocolos de comunicação e formatos de mensagem compatíveis
• Quaisquer requisitos ou restrições

Esse AgentCard permite que qualquer cliente em conformidade com o A2A descubra e interaja com o agente sem conhecimento prévio dos detalhes de implementação.

Neste tutorial, você criou um sistema de chat usando um servidor de reclamações A2A que expôs uma interface estruturada para comunicação entre cliente e agente. Ao separar a camada de mensagens da lógica interna, o protocolo Agent2Agent permite que as equipes atualizem os recursos do agente, troquem modelos ou modifiquem as configurações de ferramentas sem alterar o código do cliente. Essa flexibilidade é especialmente valiosa ao coordenar tarefas que exigem entradas, acompanhar o status das tarefas ou tratar cada operação como uma unidade discreta de trabalho.

O A2A funciona definindo um formato de mensagem comum que qualquer componente compatível pode entender, permitindo que agentes autônomos colaborem com outros agentes. A especificação do protocolo define como as mensagens são estruturadas no formato JSON-RPC e enriquecidas com metadados para garantir consistência e clareza entre as interações.

Este tutorial baseia-se nos exemplos básicos fornecidos pelo repositório de amostras A2A. Para mais informações sobre a implementação original, consulte o arquivo readme no repositório, que traz mais contexto e exemplos para a criação de sistemas em conformidade com o A2A.

Para implementações no mundo real, os servidores A2A podem implementar mecanismos de autenticação para proteger os endpoints dos agentes, usar eventos enviados pelo servidor para transmitir respostas e escalar para lidar com fluxos de trabalho de produção. Seguindo esse fluxo de trabalho, você viu como um cliente de linha de comando pode interagir com um agente de IA por meio de um protocolo padronizado, permitindo que o agente coordene várias ferramentas e forneça respostas contextuais. Essa abordagem demonstra o poder do A2A para permitir sistemas de IA sustentáveis, escaláveis e flexíveis.

Quando você terminar de experimentar o sistema, siga estas etapas para encerrar corretamente todos os componentes em execução:

Em cada janela do terminal, pressione Ctrl+C para interromper o processo de execução.

Você deverá ver a saída como:

Se o servidor não responder ou travar ao ser desligado, você poderá pará-lo à força:

Encontre a ID do processo (PID):

Identifique a PID do processo que você está tentando interromper.

Encerre o processo:

repita esse processo para cada servidor, se necessário.

É isso. Você executou com sucesso um sistema de chat completo em conformidade com o A2A.