Implantar agentes A2A no Cloud Run

Prepare e configure agentes Agent2Agent (A2A) para implantação no Cloud Run.

Este guia aborda as etapas essenciais para implantar agentes A2A:

Revise a especificação A2A e os agentes de amostra

Antes de começar a desenvolver e implantar seu agente A2A, familiarize-se com os seguintes conceitos e recursos:

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Instale a CLI do Google Cloud.

  5. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  6. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Instale a CLI do Google Cloud.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  11. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  12. Para criar uma conta de serviço, execute o comando a seguir:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Substitua os seguintes valores:

    • A2A_SERVICE_ACCOUNT_NAME: o nome da conta de serviço.

    • DESCRIPTION: uma descrição opcional da conta de serviço.

    • DISPLAY_NAME: um nome de conta de serviço a ser exibido no console Google Cloud .

Conceder papéis à conta de serviço

Para conceder os papéis do IAM necessários à sua conta no projeto:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

Substitua:

  • PROJECT_ID: ID do projeto;
  • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço
  • ROLE: o papel que você está adicionando à conta de serviço

Funções exigidas

Para receber as permissões necessárias para implantar agentes A2A, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder os papéis

Console

  1. No console do Google Cloud , acesse a página IAM.

    Acessar IAM
  2. Selecione o projeto.
  3. Clique em Conceder acesso.

  4. No campo Novos principais, digite seu identificador de usuário. Normalmente, esse é o endereço de e-mail usado para implantar o serviço do Cloud Run.

  5. Na lista Selecionar papel, escolha um.
  6. Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.
  7. Clique em Salvar.

gcloud

Para conceder os papéis do IAM necessários à sua conta no projeto:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

Substitua:

  • PROJECT_NUMBER pelo número do projeto do Google Cloud .
  • PROJECT_ID com o ID do seu projeto Google Cloud .
  • PRINCIPAL com a conta a que você está adicionando a vinculação. Normalmente, esse é o endereço de e-mail usado para implantar o serviço do Cloud Run.
  • ROLE com o papel que você está adicionando à conta do implantador.

Preparar para a implantação do Cloud Run

Esta seção descreve as configurações necessárias para preparar seu agente A2A para implantação no Cloud Run para um exemplo de código Python.

Preparar o agente A2A

  1. Recupere o exemplo de código clonando o repositório do app de exemplo na máquina local:

    git clone https://github.com/a2aproject/a2a-samples

  2. Acesse o diretório que contém o exemplo de código:

    cd a2a-samples/samples/python/agents/adk_cloud_run

Configurar secrets para serviços do Cloud Run

Forneça todas as credenciais sensíveis, como chaves de API e senhas de banco de dados, ao servidor A2A usando um mecanismo seguro. O Cloud Run oferece suporte ao fornecimento de secrets como variáveis de ambiente ou volumes montados dinamicamente. Para mais informações, consulte Configurar secrets no Cloud Run.

Os agentes precisam de acesso a serviços externos para concluir as tarefas. Os secrets são o mecanismo seguro para conceder esse acesso. Ao implantar com o AlloyDB para PostgreSQL, você precisa do usuário e da senha. Crie e gerencie os secrets de senha e usuário do banco de dados no Secret Manager executando os seguintes comandos na CLI gcloud:

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

Para mais informações, consulte Criar um secret.

Dockerfile para contêinerização

O Cloud Run pode implantar serviços de imagens de contêiner já hospedadas ou diretamente do código-fonte. Ao fazer a implantação do código-fonte, o Cloud Run cria automaticamente uma imagem de contêiner se um Dockerfile estiver presente no diretório raiz do projeto.

O Dockerfile determina os detalhes da imagem do contêiner. Este é o Dockerfile do agente A2A de exemplo que você clonou antes:

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Implantar do código-fonte sem um Dockerfile

Para repositórios de código-fonte sem um Dockerfile, o Cloud Run oferece suporte integrado a algumas linguagens de programação conhecidas, simplificando o processo de contêinerização.

Implantar o agente A2A no Cloud Run

Implante seu aplicativo A2A com uma configuração TaskStore na memória ou com o AlloyDB para PostgreSQL.

  • Uma configuração TaskStore na memória armazena todos os dados exclusivamente na instância de contêiner do Cloud Run. Isso significa que todos os dados de tarefas são perdidos quando a instância do contêiner é desligada, reduzida ou reiniciada.
  • O AlloyDB para PostgreSQL oferece persistência de dados, permitindo que os agentes sejam escalonados horizontalmente e garantindo que as tarefas sobrevivam a reinicializações de contêineres, eventos de escalonamento e implantações.

Uma configuração TaskStore na memória é adequada para desenvolver agentes A2A no ambiente local, e o AlloyDB para PostgreSQL é adequado para escalonar o agente A2A em produção.

Os comandos a seguir mostram como usar a autenticação baseada no IAM para seu serviço do Cloud Run. Usar a flag --no-allow-unauthenticated na implantação é a abordagem recomendada para configurar a autenticação de clientes Google Cloud internos, como o Gemini Enterprise.

Se o servidor A2A for projetado para acesso público e precisar processar autenticação no nível do agente, especifique a flag --allow-unauthenticated durante a implantação. Consulte Autenticação de acesso público do Cloud Run para mais detalhes. Para permitir o acesso público ao seu serviço do Cloud Run, você também precisa fornecer informações de autenticação importantes no card do agente A2A usando os parâmetros securitySchemes e security. Para mais informações, consulte Especificação A2A: detalhes do objeto SecurityScheme.

Implantar com uma configuração TaskStore na memória

Para implantar seu agente A2A com uma configuração TaskStore na memória, execute o seguinte comando no diretório que contém o código-fonte do agente A2A:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

Substitua:

  • REGION: a região Google Cloud em que você quer implantar o serviço, por exemplo, europe-west1.
  • PROJECT_ID: o ID do projeto.
  • PROJECT_NUMBER: o número do projeto.
  • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço A2A.

Implantar com o AlloyDB para PostgreSQL

Para manter as tarefas A2A, use o AlloyDB para PostgreSQL. Para implantar seu agente A2A com o AlloyDB para PostgreSQL para armazenamento de tarefas persistentes, use o seguinte comando:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

Substitua:

  • REGION: a região Google Cloud em que você quer implantar o serviço, por exemplo, europe-west1.
  • PROJECT_ID: o ID do projeto.
  • PROJECT_NUMBER: o número do projeto.
  • CLUSTER_NAME: o nome do seu cluster do AlloyDB para PostgreSQL.
  • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço A2A.

Depurar falhas de implantação

Se você encontrar erros ou falhas na implantação do Cloud Run, considere o seguinte:

  • Registros detalhados:para registros detalhados de implantação, defina a flag --verbosity=info no comando gcloud run deploy.

  • Incompatibilidade de URL:se o URL run.app retornado pelo comando de implantação for diferente do URL determinístico esperado, atualize a variável de ambiente APP_URL para seu serviço do Cloud Run:

    1. Use o comando a seguir para atualizar a variável de ambiente APP_URL:

      gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

      Substitua:

      • SERVICE_NAME: o nome do seu serviço do Cloud Run;
      • PROJECT_ID: o ID do projeto.
      • REGION: a região Google Cloud em que você quer implantar o serviço. Por exemplo: europe-west1
      • CLOUD_RUN_SERVICE_URL: o URL do seu serviço do Cloud Run.

    2. Verifique se o APP_URL foi atualizado corretamente descrevendo o serviço:

      gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

Entender o URL do aplicativo do Cloud Run

Quando a implantação é concluída, o Cloud Run fornece automaticamente um URL run.app que serve como endpoint para consultar seu serviço A2A ativo. O URL é determinístico e previsível se o nome do serviço for suficientemente curto.

  • Formato do URL do Cloud Run:https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
  • Exemplo de URL: https://sample-a2a-agent-1234.europe-west1.run.app

Testar e monitorar a implantação do agente A2A

Depois de implantar o agente A2A no Cloud Run, teste a funcionalidade dele. Estabeleça práticas de monitoramento eficientes para garantir desempenho e confiabilidade contínuos.

Inspetor de A2A: validar a conformidade do agente

Use a ferramenta a2a-inspector para inspecionar, depurar e validar o agente do Google A2A implantado. Essa ferramenta garante que seu agente esteja totalmente em conformidade com a especificação A2A e funcione corretamente.

Após uma conexão bem-sucedida, o inspetor realiza as seguintes ações:

  • Mostra o card do agente:mostra automaticamente o card do seu agente.
  • Valida a conformidade:verifica se o cartão atende às especificações de A2A.
  • Ativa o chat ao vivo:permite enviar e receber mensagens com o representante.
  • Mostra dados brutos:exibe mensagens JSON-RPC 2.0 brutas em um console para depuração.

Interação da CLI com um agente A2A implantado

Use as ferramentas de interface de linha de comando (CLI) do repositório de amostras A2A para interagir com o serviço implantado. Essa CLI é compatível com a autenticação baseada em token de portador.

Se o serviço usa a autenticação baseada no IAM, exporte o token gcloud para uma interação bem-sucedida:

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

Substitua CLOUD_RUN_SERVICE_URL pelo URL do serviço do Cloud Run implantado.

Teste local de serviços A2A implantados

É possível testar o serviço implantado do Cloud Run localmente. Isso é especialmente útil ao implementar a autenticação baseada no IAM.

Testar a autenticação baseada no IAM para agentes do Cloud Run

Os clientes que interagem com seu serviço do Cloud Run protegido pelo Identity and Access Management (IAM) precisam ter o papel do IAM roles/run.invoker.

Teste localmente o fluxo de autenticação do serviço implantado usando o comando gcloud auth print-identity-token:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

Substitua CLOUD_RUN_SERVICE_URL pelo URL do serviço do Cloud Run implantado.