GENAI120

O protocolo Agent2Agent (A2A) resolve um dos grandes desafios que o cenário da IA apresenta: ele permite que agentes de IA generativa, criados em frameworks diversos por diferentes empresas e executados em servidores separados, se comuniquem e colaborem de maneira eficaz como agentes, não apenas como ferramentas. O objetivo do A2A é estabelecer uma linguagem comum para agentes, promovendo um ecossistema de IA mais interconectado, potente e inovador.

O A2A foi criado com base em alguns conceitos principais que o tornam eficiente e flexível:

• Comunicação padronizada: JSON-RPC 2.0 por HTTP(S).
• Descoberta de agentes: os cards dos agentes detalham os recursos e as informações de conexão de um agente. Assim, os agentes podem se descobrir e conhecer os recursos uns dos outros.
• Troca de dados avançados: ele processa texto, arquivos e dados JSON estruturados.
• Interação flexível: é compatível com solicitação/resposta síncrona, streaming (SSE) e notificações push assíncronas.
• Pronto para empresas: é projetado com foco em segurança, autenticação e observabilidade.

Objetivos

Neste laboratório, você vai:

• Implantar um agente do ADK como um servidor A2A.
• Preparar um card do agente JSON para descrever os recursos de um agente A2A.
• Permitir que outro agente do ADK leia o card do agente A2A implantado e o use como um subagente.

Configuração e requisitos

Antes de clicar no botão Start Lab

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer, que é iniciado quando você clica em Start Lab, mostra por quanto tempo os recursos do Cloud ficarão disponíveis.

Este laboratório prático do Qwiklabs permite que você realize as atividades em um ambiente real de nuvem, não em um ambiente simulado ou de demonstração. Isso é possível porque você recebe credenciais novas e temporárias para fazer login e acessar o Google Cloud Platform durante o laboratório.

O que é necessário

Para fazer este laboratório, você precisa ter:

• acesso a um navegador de Internet padrão (recomendamos o Chrome);
• tempo para concluir todas as atividades.

Observação: não use um projeto seu nem uma conta pessoal do GCP neste laboratório.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Tarefa 1: instalar o ADK e configurar o ambiente

No ambiente deste laboratório, a API Vertex AI e a API Cloud Run já foram ativadas para você. Se você seguisse essas etapas no seu próprio projeto, elas seriam ativadas navegando até a Vertex AI e seguindo o comando para ativá-las.

Prepare uma guia do editor do Cloud Shell

1. Com a janela do console do Google Cloud selecionada, abra o Cloud Shell pressionando as teclas G e S no teclado. Como alternativa, clique no botão "Ativar o Cloud Shell" () no canto superior direito do console do Cloud.

2. Clique em Continuar.

3. Se for preciso autorizar o Cloud Shell, clique em Autorizar.

4. No canto superior direito do painel do terminal do Cloud Shell, clique no botão Abrir em uma nova janela .

5. No terminal do Cloud Shell, insira o seguinte código para abrir o Editor no seu diretório principal:

   cloudshell workspace ~

6. Feche qualquer outro tutorial ou painel do Gemini que apareça no lado direito da tela. Assim você terá mais espaço na janela do editor de código.

7. Durante o restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado (IDE) com o editor do Cloud Shell e o terminal do Cloud Shell.

Baixe e instale o ADK e os exemplos de código para este laboratório

1. Instale o ADK executando o comando a seguir no terminal do Cloud Shell. Observação: é importante especificar a versão para garantir que a versão do ADK que você instalar corresponda à usada neste laboratório:

   # Instale o ADK e o SDK Python do A2A cd ~ export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.8.0 a2a-sdk==0.2.16 pip install --upgrade google-genai # Corrigindo um erro de digitação nesta versão sed -i 's/{a2a_option}"/{a2a_option} "/' ~/.local/lib/python3.12/site-packages/google/adk/cli/cli_deploy.py

2. Cole os comandos a seguir no terminal do Cloud Shell para copiar o código do laboratório de um bucket do Cloud Storage e descompactá-lo:

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_and_a2a.zip ./adk_and_a2a.zip unzip adk_and_a2a.zip

   Clique em Verificar meu progresso para conferir o objetivo. Instalar o ADK e configurar o ambiente.

Tarefa 2: analisar o agente do ADK que você vai disponibilizar remotamente

Para este laboratório, imagine que você trabalha para uma empresa de manutenção de estádios: a Cymbal Stadiums. Trabalhando em um projeto, você desenvolveu um agente de geração de imagens que pode criar ilustrações de acordo com as diretrizes da sua marca. Agora várias equipes diferentes na sua organização também querem usá-lo.

Caso você copiasse o código para ser usado como um subagente por muitos agentes, seria muito difícil manter e aperfeiçoar todas essas cópias.

Você pode, em vez disso, implantar o agente uma vez como um agente encapsulado com um servidor A2A, e os agentes das outras equipes podem incorporá-lo consultando-o remotamente.

1. No painel do explorador de arquivos do editor do Cloud Shell, acesse o diretório adk_and_a2a/illustration_agent. Esse diretório contém o agente do ADK que você vai disponibilizar remotamente. Clique no diretório para abrir.

2. Abra o arquivo agent.py nesse diretório e role a tela até a seção # Tools.

3. Repare na função generate_image(), que será usada como uma ferramenta por esse agente. Ela recebe um comando e realiza um processo de duas etapas. Primeiro, ela usa o SDK da IA generativa do Google para chamar generate_content(), que retorna os dados brutos da imagem diretamente na resposta. Em seguida, a função usa a biblioteca do Cloud Storage para fazer o upload desses bytes de imagem para um bucket do GCS. Por fim, a ferramenta retorna o URL público do arquivo de imagem recém-criado.

4. A instruction (instrução) fornecida ao root_agent dá orientações específicas para que o agente use comandos de geração de imagens que respeitem as diretrizes da marca da empresa. Por exemplo, ela especifica:

   • um estilo de ilustração específico: (Corporate Memphis)
   • uma paleta de cores (roxos e verdes em gradientes de pôr do sol)
   • exemplos de imagens de estádios/esportes e manutenção, já que a empresa trabalha com manutenção de estádios

5. Para ver o recurso na prática, primeiro você precisa escrever um arquivo .env para definir as variáveis de ambiente exigidas pelos agentes do ADK. Execute o comando a seguir no terminal do Cloud Shell para gravar esse arquivo no diretório.

   cd ~/adk_and_a2a cat << EOF > illustration_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} IMAGE_MODEL={{{project_0.startup_script.gemini_flash_image_model_id | gemini_flash_image_model_id}}} EOF

6. Execute o comando a seguir para copiar o .env para outro diretório do agente que você vai usar neste laboratório:

   cp illustration_agent/.env slide_content_agent/.env

7. Agora, no terminal do Cloud Shell, inicie a interface do desenvolvedor do ADK com:

   adk web

   Saída

   INFO: Processo do servidor iniciado [2434] INFO: Aguardando a inicialização do aplicativo. +-------------------------------------------------------+ | Servidor da Web do ADK iniciado | | | | Para testes locais, acesse http://localhost:8000. | +-------------------------------------------------------+ INFO: A inicialização do aplicativo foi concluída. INFO: Uvicorn em execução em http://127.0.0.1:8000 (Pressione CTRL+C para sair)

8. Para visualizar a interface da web em uma nova guia, clique no link http://127.0.0.1:8000 na parte de baixo da saída do terminal.

9. Uma nova guia do navegador será aberta com a interface de desenvolvimento do ADK.

10. No menu suspenso Selecionar um agente à esquerda, selecione illustration_agent.

11. Consulte o agente com um texto que poderia ser usado em uma apresentação de recrutamento:

    Quando nos apoiamos, podemos realizar grandes conquistas!

12. Após cerca de 10 segundos, o agente vai responder com o comando gerado e um URL para visualizar a imagem. Clique no URL da imagem para visualizá-la e clique em Voltar no navegador para retornar à interface do desenvolvedor.

    Exemplo de resposta

    

    Exemplo de imagem

    

13. Veja que o comando enviado ao agente não incluiu esportes, estádios ou trabalhos de manutenção, mas o agente juntou seu texto com as diretrizes da marca em um único comando para o modelo de geração de imagens.

    Quando terminar de analisar o agente básico, feche a guia do navegador.

14. Clique no painel do terminal do Cloud Shell e pressione CTRL + C para interromper o servidor.

    Clique em Verificar meu progresso para conferir o objetivo. Analisar o agente do ADK.

Tarefa 3: implantar o agente como um servidor A2A

Agora você vai seguir as etapas para implantar esse agente como um agente A2A remoto.

1. Um agente A2A se identifica e mostra seus recursos ao exibir um card do agente. Execute o comando a seguir para criar um arquivo agent.json.

   touch illustration_agent/agent.json

2. Abra o arquivo agent.json no diretório adk_and_a2a/illustration_agent e cole o seguinte conteúdo:

   { "name": "illustration_agent", "description": "An agent designed to generate branded illustrations for Cymbal Stadiums.", "defaultInputModes": ["text/plain"], "defaultOutputModes": ["application/json"], "skills": [ { "id": "illustrate_text", "name": "Illustrate Text", "description": "Generate an illustration to illustrate the meaning of provided text.", "tags": ["illustration", "image generation"] } ], "url": "https://illustration-agent-{{{project_0.startup_script.project_number|Project Number}}}.{{{project_0.default_region| GCP_LOCATION}}}.run.app/a2a/illustration_agent", "capabilities": {}, "version": "1.0.0" }

3. Salve o arquivo.

4. Revise o JSON no arquivo agent.json. Veja que ele dá ao agente um name (nome) e uma description (descrição) e identifica algumas skills (habilidades). Ele também indica um url em que o próprio agente pode ser chamado.

   O url do agente é criado para ser o URL do serviço do Cloud Run depois de ser implantado de acordo com as instruções deste laboratório.

   Embora tenha um nome parecido com skills, o parâmetro capabilities (recursos) aqui é usado apenas para indicar capacidades como streaming.

5. Execute o comando a seguir para criar um arquivo requirements.txt no diretório illustration_agent.

   touch illustration_agent/requirements.txt

6. Selecione o arquivo e cole o seguinte comando nele.

   google-adk==1.8.0 a2a-sdk==0.2.16

7. Salve o arquivo.

8. No comando a seguir, você vai usar adk deploy cloud_run com a flag --a2a para implantar o agente no Cloud Run como um servidor A2A. Para saber mais sobre como implantar agentes no Cloud Run, procure o laboratório "Implantar agentes do ADK no Cloud Run". Nesse comando:

   • --project e --region definem o projeto e a região em que o serviço do Cloud Run será implantado.
   • --service_name define o nome do serviço do Cloud Run.
   • A flag --a2a indica que ele precisa ser hospedado como um agente A2A. Isso tem dois significados:
     • seu agente será encapsulado por uma classe que faz a ponte entre o agente do ADK e o A2A: o A2aAgentExecutor. Essa classe traduz a linguagem do protocolo A2A de tarefas e mensagens para um executor do ADK na linguagem de eventos.
     • o card do agente também será hospedado em CLOUD_RUN_URL/a2a/AGENT_NAME/.well-known/agent.json. Observação: embora essa versão do card esteja disponível em breve, a reescrita dinâmica do URL do agente não está funcionando com o Cloud Run no momento. e, por isso, não será usada nesta versão do laboratório.

   Implante o agente no Cloud Run como um servidor A2A com o comando a seguir:

   adk deploy cloud_run \ --project {{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} \ --region {{{project_0.default_region| GCP_LOCATION}}} \ --service_name illustration-agent \ --a2a \ illustration_agent

9. Você vai precisar permitir respostas não autenticadas para esse contêiner. Para o teste deste laboratório, digite Y no terminal do Cloud Shell (para "sim") e pressione Return.

   Observação: a implantação leva de 5 a 10 minutos. Se ocorrer um erro PERMISSION_DENIED, tente executar o comando acima novamente.

   Resposta esperada:

   Você vai ver etapas relacionadas à criação de um Dockerfile e à implantação do contêiner, depois à implantação do serviço, seguidas de:

   Service [illustration-agent] revision [illustration-agent-00001-xpp] has been deployed and is serving 100 percent of traffic. Service URL: https://illustration-agent-{{{project_0.startup_script.project_number|Project Number}}}.{{{project_0.default_region| GCP_LOCATION}}}.run.app

   Clique em Verificar meu progresso para conferir o objetivo. Implantar o agente como um servidor A2A.

Tarefa 4: permitir que outro agente do ADK chame este agente remotamente

Nesta tarefa, você vai permitir que um segundo agente do ADK identifique os recursos do seu agente de ilustração e o chame remotamente. Esse segundo agente vai criar conteúdo para uma apresentação de slides. Ele vai escrever um título e algumas frases para o corpo do texto e depois transferir para o agente de ilustração para gerar uma imagem que ilustre esse texto.

1. No terminal do Cloud Shell, execute o comando a seguir para copiar o arquivo JSON do card do agente para o diretório adk_and_a2a e mudar o nome dele para indicar que ele representa o illustration_agent.

   cp illustration_agent/agent.json illustration-agent-card.json

2. No painel do explorador de arquivos do editor do Cloud Shell, acesse adk_and_a2a/slide_content_agent e abra o arquivo agent.py.

   Revise a instruction (instrução) desse agente para ver que ele vai aceitar a sugestão de um usuário para um slide e escrever um título e um texto, e depois transferir para seu agente de A2A para ilustrar o slide.

3. Cole o código a seguir no cabeçalho # Agents para adicionar o agente remoto usando a classe RemoteA2aAgent do ADK:

   illustration_agent = RemoteA2aAgent( name="illustration_agent", description="Agent that generates illustrations.", agent_card=( "illustration-agent-card.json" ), )

4. Adicione illustration_agent como um subagente do root_agent adicionando o parâmetro a seguir ao root_agent:

   sub_agents=[illustration_agent]

5. Salve o arquivo.

6. Inicie a interface no terminal do Cloud Shell com:

   cd ~/adk_and_a2a adk web

7. Clique novamente no link http://127.0.0.1:8000 na saída do terminal.

8. Uma nova guia do navegador será aberta com a interface de desenvolvimento do ADK. No menu suspenso Selecionar um agente à esquerda, selecione slide_content_agent.

9. Consulte o agente sobre uma ideia para um slide:

   Crie conteúdo para um slide sobre nosso excelente treinamento no trabalho.

Você verá a seguinte resposta:

• Um título e um texto escritos pelo próprio slide_content_agent
• Uma chamada para transfer_to_agent, indicando uma transferência para o illustration_agent
• A resposta do illustration_agent com um link em que você pode clicar para ver a nova imagem.

Clique em Verificar meu progresso para conferir o objetivo. Ativar outro agente do ADK para chamar o agente remotamente.

Parabéns!

Neste laboratório, você implantou um agente do ADK como um servidor A2A, preparou um card do agente JSON para descrever os recursos de um agente A2A e permitiu que outro agente do ADK lesse o card do agente A2A implantado e o usasse como um subagente.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 6 de outubro de 2025

Laboratório testado em 6 de outubro de 2025

Copyright 2020 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.