Esta página foi traduzida pela API Cloud Translation.

Crie um sistema multiagente com o ADK, implante no Agent Engine e comece a usar o protocolo A2A

1. Objetivo deste laboratório

Neste laboratório prático, você vai criar um aplicativo multiagente que gera uma imagem com base no seu comando e a avalia em relação a ele. Se a imagem não atender satisfatoriamente aos requisitos descritos no comando, o agente vai gerar imagens continuamente até que uma delas atenda aos seus requisitos. Cada um dos agentes neste exercício prático tem uma única finalidade, e eles cooperam entre si para alcançar a meta geral.

O que você vai aprender

Entenda os conceitos básicos do ADK e saiba como criar um sistema multiagente.
Saiba como implantar e usar facilmente os agentes no GCP.
Entenda os conceitos básicos do protocolo A2A
Aprenda a usar o protocolo A2A e o ADK juntos para criar agentes abertos.

2. Antes de começar

Se você ainda não tiver um projeto para usar, crie um novo no console do GCP.
Neste laboratório, vamos usar o GCP Cloud Shell para realizar nossas tarefas. Abra o Cloud Shell e defina o projeto usando o Cloud Shell.
Abra o editor do Cloud Shell do GCP clicando no botão do editor do Cloud Shell. Se o pop-up "Autorizar Shell" aparecer, clique para autorizar o editor do Cloud Shell.
É possível verificar se o projeto já está autenticado usando o seguinte comando.

gcloud auth list

Execute o comando a seguir no Cloud Shell para confirmar seu projeto:

gcloud config list project

Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

Precisamos ativar alguns serviços para executar este laboratório. Execute o seguinte comando no Cloud Shell:

gcloud services enable aiplatform.googleapis.com

3. Visão geral: benefícios do Agent Development Kit

O Agent Development Kit oferece várias vantagens importantes para desenvolvedores que criam aplicativos agênticos:

Sistemas multiagentes: crie aplicativos modulares e escalonáveis combinando vários agentes especializados em uma hierarquia. Permite coordenação e delegação complexas.
Ecossistema de ferramentas avançadas: equipe os agentes com diversas funcionalidades. Use ferramentas pré-criadas (Pesquisa, Execução de código etc.), crie funções personalizadas, integre ferramentas de frameworks de agentes de terceiros (LangChain, CrewAI) ou até mesmo use outros agentes como ferramentas.
Orquestração flexível: defina fluxos de trabalho usando agentes de fluxo de trabalho (SequentialAgent, ParallelAgent e LoopAgent) para pipelines previsíveis ou aproveite o roteamento dinâmico baseado em LLM (transferência LlmAgent) para um comportamento adaptável.
Experiência de desenvolvedor integrada: desenvolva, teste e depure localmente com uma CLI eficiente e uma interface de desenvolvimento interativa. Inspecione eventos, estado e etapa de execução do agente.
Avaliação integrada: avalie sistematicamente a performance do agente avaliando a qualidade da resposta final e a trajetória de execução detalhada em relação a casos de teste predefinidos.
Pronto para implantação: coloque em contêineres e implante seus agentes em qualquer lugar. Execute localmente, dimensione com o Vertex AI Agent Engine ou integre à infraestrutura personalizada usando o Cloud Run ou o Docker.

Embora outros SDKs de IA generativa ou frameworks de agentes também permitam consultar modelos e até mesmo capacitá-los com ferramentas, a coordenação dinâmica entre vários modelos exige muito trabalho da sua parte.

O Agent Development Kit oferece uma estrutura de nível mais alto do que essas ferramentas, permitindo que você conecte facilmente vários agentes para fluxos de trabalho complexos, mas fáceis de manter.

4. Introdução ao A2A

O protocolo Agent2Agent (A2A) é um padrão aberto projetado para permitir a comunicação e a colaboração perfeitas e seguras entre agentes autônomos de IA de diferentes frameworks, fornecedores e domínios.

Interoperabilidade universal:a A2A permite que os agentes trabalhem juntos, independentemente das tecnologias subjacentes, promovendo um ecossistema verdadeiramente multiagente. Isso significa que agentes criados por empresas diferentes em plataformas diferentes podem se comunicar e se coordenar.
Descoberta de recursos:os agentes podem anunciar seus recursos usando "cards de agente" (documentos JSON), que descrevem a identidade, os recursos de A2A compatíveis, as habilidades e os requisitos de autenticação. Isso permite que outros agentes descubram e selecionem o mais adequado para uma determinada tarefa.
Proteção sempre:a segurança é um princípio fundamental. O A2A incorpora mecanismos de autenticação e autorização de nível empresarial, usando padrões como HTTPS/TLS, JWT, OIDC e chaves de API para garantir interações seguras e proteger dados sensíveis.
Independente da modalidade:o protocolo é compatível com várias modalidades de comunicação, incluindo texto, áudio e streaming de vídeo, além de formulários interativos e iframes incorporados. Essa flexibilidade permite que os agentes troquem informações no formato mais adequado para a tarefa e o usuário.
Gerenciamento estruturado de tarefas:o A2A define protocolos claros para delegação, monitoramento e conclusão de tarefas. Ele permite agrupar e gerenciar tarefas relacionadas em diferentes agentes usando IDs de tarefa exclusivos. As tarefas podem passar por ciclos de vida definidos (por exemplo, enviada, em andamento, concluída).
Execução opaca:um recurso importante é que os agentes não precisam revelar a outros agentes os processos de raciocínio internos, a memória ou ferramentas específicas. Eles expõem apenas os serviços chamáveis, promovendo modularidade e privacidade.
Criado com base em padrões atuais:o A2A usa tecnologias da Web estabelecidas, como HTTP, eventos enviados pelo servidor (SSE) para streaming em tempo real e JSON-RPC para troca de dados estruturados, facilitando a integração com a infraestrutura de TI atual.
Comunicação assíncrona:o protocolo foi projetado com a comunicação assíncrona como uma consideração principal, facilitando a progressão flexível de tarefas e permitindo notificações push para atualizações, mesmo quando uma conexão não é mantida de forma persistente.

5. Arquitetura do agente

Neste laboratório, você vai criar um aplicativo multiagente que gera uma imagem de acordo com sua especificação e a avalia antes de apresentar a você.

O sistema é estruturado com um agente principal chamado image_scoring, que organiza todo o processo. Esse agente principal tem um subagente chamado image_generation_scoring_agent, que, por sua vez, tem subagentes próprios para tarefas mais específicas. Isso cria uma relação hierárquica em que o agente principal delega tarefas aos subagentes. Figura 2: fluxo geral do agente.

Lista de todos os agentes

image_scoring (agente principal):
Finalidade: é o agente raiz que gerencia o fluxo de trabalho geral. Ele executa repetidamente o image_generation_scoring_agent e o checker_agent em um loop até que uma condição de encerramento seja atendida.
Subagentes:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (subagente de image_scoring):
Finalidade: esse agente é responsável pela lógica principal de geração e pontuação de imagens. Para isso, ele executa uma sequência de três subagentes.
Subagentes:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (subagente de image_scoring):
Finalidade: esse agente verifica se o processo de pontuação da imagem deve continuar ou ser encerrado. Ela usa a ferramenta check_tool_condition para avaliar a condição de encerramento.
image_generation_prompt_agent (subagente de image_generation_scoring_agent):
Finalidade: esse agente é especialista em criar comandos para geração de imagens. Ele recebe um texto de entrada e gera um comando detalhado adequado para o modelo de geração de imagens.
image_generation_agent (subagente de image_generation_scoring_agent):
Finalidade: este agente é especialista em criar imagens usando o Imagen 3. Ele usa o comando do image_generation_prompt_agent e gera uma imagem.
scoring_images_prompt (subagente de image_generation_scoring_agent):
Finalidade: este agente é especialista em avaliar e pontuar imagens com base em vários critérios. Ele pega a imagem gerada e atribui uma pontuação a ela.

Ferramentas usadas pelos agentes

check_tool_condition:
Descrição: essa ferramenta verifica se a condição de término do loop foi atendida ou se o número máximo de iterações foi atingido. Se uma delas for verdadeira, o loop será interrompido.
Usado por: checker_agent_instance
generate_images:
Descrição: essa ferramenta gera imagens usando o modelo Imagen 3. Ele também pode salvar as imagens geradas em um bucket do Google Cloud Storage.
Usado por: image_generation_agent
get_policy:
Descrição: essa ferramenta busca uma política em um arquivo JSON. A política é usada pelo image_generation_prompt_agent para criar o comando de geração de imagens e pelo scoring_images_prompt para classificar as imagens.
Usado por: image_generation_prompt_agent, scoring_images_prompt
get_image:
Descrição: essa ferramenta carrega o artefato de imagem gerado para que ele possa ser pontuado.
Usado por: scoring_images_prompt
set_score:
Descrição: essa ferramenta define a pontuação total da imagem gerada no estado da sessão.
Usado por: scoring_images_prompt

6. Tarefa 1: Instalar o ADK e configurar o ambiente

Neste exercício prático, vamos usar o Cloud Shell para realizar as tarefas.

Ativar as APIs recomendadas da Vertex AI

Na parte de cima do console do Google Cloud, pesquise e acesse a Vertex AI.
Clique em Ativar todas as APIs recomendadas.

Preparar uma guia do editor do Cloud Shell

Com a janela do console do Google Cloud selecionada, abra o Cloud Shell pressionando as teclas G e S no teclado. Você também pode clicar no botão do Cloud Shell no canto superior direito do console do Google Cloud.
Clique em Continuar.
Quando for preciso autorizar o Cloud Shell, clique em Autorizar.
No canto superior direito do painel do Cloud Shell, clique no botão Abrir em uma nova janela .
Clique no ícone de lápis Abrir editor ( ) na parte de cima do painel para ver os arquivos.
Na parte de cima do menu de navegação à esquerda, clique no ícone do Explorador para abrir o explorador de arquivos.
Clique no botão Abrir pasta.
Ao longo do restante deste laboratório, você pode trabalhar nessa janela como seu IDE com o editor e o terminal do Cloud Shell.

Faça o download e instale o ADK e as amostras de código para este laboratório

Execute os comandos a seguir para clonar a origem necessária do GitHub e instalar as bibliotecas necessárias.

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

Vamos usar o poetry para instalar outros requisitos:

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

Se você não tiver um bucket do Cloud Storage, crie um em Google Cloud Storage. Também é possível criar o bucket usando o comando gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

No editor, acesse View->Toggle hidden files. Na pasta image_scoring, crie um arquivo .env com o seguinte conteúdo. Adicione os detalhes necessários, como o nome do projeto e o bucket do Cloud Storage.

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

Confira a estrutura do agente no código-fonte, começando por agent.py . Esse agente contém o agente raiz que se conecta aos outros agentes.
Volte ao diretório principal multiagenthandson no terminal e execute o comando a seguir para executar o agente localmente:

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

Figura 1

Pressione Ctrl+Clique (CMD+Clique para MacOS) no URL http:// exibido no terminal para abrir o cliente GUI baseado em navegador do ADK. Ele vai ficar parecido com a Figura 2

Vamos gerar algumas imagens. Tente os comandos a seguir ou crie os seus.
Uma paisagem de montanha tranquila ao pôr do sol
Um gato andando de bicicleta

Figura 2

7. Tarefa 2: Implantar no Agent Engine

Agora vamos implantar o agente no Agent Engine. O Agent Engine é um serviço totalmente gerenciado para implantação de agentes no GCP. O Agent Engine é compatível com o ADK. Assim, os agentes criados com o ADK podem ser implantados no Agent Engine.

Definir algumas variáveis de ambiente

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

Crie o arquivo requirements.txt usando o poetry. O Poetry vai usar pyproject.toml para criar o arquivo requirements.txt. Depois de executar o comando, verifique se o arquivo requirements.txt foi criado.

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

Crie o pacote. Precisamos agrupar nosso app em um pacote Python .whl. Vamos usar o Poetry para fazer isso. Depois de executar o comando, verifique se uma pasta "dist" foi criada e se ela contém o arquivo .whl.

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

Agora vamos preparar o script de implantação. O script de implantação vai implantar nosso agente de pontuação de imagens ou o serviço do mecanismo de agente. Mude o conteúdo de deploy.py na pasta image_scoring, conforme abaixo.

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

Agora podemos executar o script de implantação.

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

Depois da implantação, você vai ver algo como abaixo,

Figura 3.

Agora vamos testar o agente implantado. Para testar o mecanismo do agente implantado remotamente, primeiro copie o local do agente da saída de implantação no terminal. Ele será semelhante a este: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Acesse a pasta testclient,abra o arquivo remote_test.py e edite as seguintes linhas.

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. Tarefa 3: Criar um agente A2A

Nesta etapa, vamos criar um agente A2A simples com base no agente criado nas etapas anteriores. Os agentes do ADK atuais podem ser publicados no protocolo A2A. Estes são os principais pontos que você vai aprender nesta etapa.

Conheça os conceitos básicos do protocolo A2A.
Saiba como os protocolos ADK e A2A funcionam juntos.
Saiba como interagir com o protocolo A2A.

Neste exercício prático, vamos usar o código na pasta image_scoring_adk_a2a_server. Antes de começar a tarefa, mude o diretório para essa pasta.

Criar card de agente A2A

O protocolo A2A exige um cartão do agente que contenha todas as informações sobre ele, como recursos, guia de uso etc. Depois que um agente A2A é implantado, o cartão pode ser acessado usando o link ".well-known/agent-card.json". Os clientes podem consultar essas informações para enviar a solicitação aos agentes.

Na pasta remote_a2a/image_scoring, confirme se há um arquivo agents.json com o seguinte conteúdo.

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

Criar agente A2A

Na pasta raiz image_scoring_adk_a2a_server, confirme se há um arquivo a2a_agent.py, que é o ponto de entrada do agente a2a. Ele precisa ter o seguinte conteúdo:

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

Executar o agente A2A

Agora podemos executar o agente. Para executar o agente, execute o seguinte comando na pasta principal image_scoring_adk_a2a_server

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

Testar o agente A2A

Depois que o agente estiver em execução, podemos testá-lo. Primeiro, vamos verificar o card do agente.

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

A execução do comando acima mostra o card do agente A2A, que é principalmente o conteúdo de agent.json criado na etapa anterior.

Agora vamos enviar uma solicitação ao agente. Podemos usar curl para enviar solicitações ao agente.

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

Na solicitação acima, você pode mudar o comando alterando a linha "Crie uma imagem de um gato". Depois de executar o comando, verifique a imagem de saída no Cloud Storage especificado.

9. Limpar

Agora vamos limpar o que acabamos de criar.

Exclua o servidor do Agent Engine que acabamos de criar. Acesse a Vertex AI digitando "Vertex AI" na barra de pesquisa do console do Google Cloud. Clique no mecanismo de agente à esquerda.Para excluir o agente, clique em "Excluir".

Figura 4

Excluir os arquivos no Cloud Shell

#Execute the following to delete the files
rm -R imagescoring

Exclua o bucket. Acesse o console do GCP -> Cloud Storage , selecione e exclua seu bucket.