Implantar agentes A2A no Cloud Run

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

Este guia aborda as etapas essenciais para implantar agentes do A2A:

Analisar a especificação do A2A e os agentes de amostra

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

Antes de começar

  1. Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários 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 Google Cloud CLI.

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

  6. Para inicializar a CLI gcloud, 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 Google Cloud CLI.

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

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

    gcloud init

  12. Para criar uma conta de serviço, execute o seguinte comando:
    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 Google Cloud console.

Conceder papéis da conta de serviço

Para conceder os papéis necessários do IAM à sua conta no seu 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 do 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 personalizados papéis ou outros predefinidos papéis.

Conceder os papéis

Console

  1. No Google Cloud console, 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 necessários do IAM à sua conta no seu projeto:

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

Substitua:

  • PROJECT_NUMBER pelo seu Google Cloud projeto número.
  • PROJECT_ID pelo ID do Google Cloud projeto.
  • PRINCIPAL com a conta para a qual você está adicionando a vinculação. Normalmente, esse é o endereço de e-mail que é usado para implantar o serviço do Cloud Run.
  • ROLE pelo 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 do A2A para implantação no Cloud Run para um exemplo de código Python.

Preparar o agente do 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 do 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 usuário e senha 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 implantar do código-fonte, o Cloud Run cria automaticamente uma imagem do contêiner se um Dockerfile estiver presente no diretório raiz do projeto.

O Dockerfile determina os detalhes da imagem do contêiner. A seguir, o Dockerfile do agente de amostra do A2A que você clonou anteriormente:

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 do A2A no Cloud Run

Implante seu aplicativo do 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 da tarefa 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 do A2A no ambiente local, e o AlloyDB para PostgreSQL é adequado para escalonar o agente do A2A na produção.

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

Se o servidor do A2A for projetado para acesso público e precisar processar a 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 serviço do Cloud Run, você também precisa fornecer informações de autenticação importantes no card do agente do A2A usando os parâmetros securitySchemes e security. Para mais informações, consulte Especificação do A2A: detalhes do objeto SecurityScheme.

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

Para implantar o agente do 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 do 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: aregião em que você quer implantar o serviço, por exemplo, europe-west1. Google Cloud
  • PROJECT_ID: ID do projeto.
  • PROJECT_NUMBER: o número do projeto.
  • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço do A2A.

Implantar com o AlloyDB para PostgreSQL

Para persistir tarefas do A2A, use o AlloyDB para PostgreSQL. Para implantar o agente do A2A com o AlloyDB para PostgreSQL para armazenamento de tarefas persistente, 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: aregião em que você quer implantar o serviço, por exemplo, europe-west1. Google Cloud
  • PROJECT_ID: ID do projeto.
  • PROJECT_NUMBER: o número do projeto.
  • CLUSTER_NAME: o nome do cluster do AlloyDB para PostgreSQL.
  • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço do A2A.

Depurar falhas de implantação

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

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

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

    1. Use o seguinte comando 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 serviço do Cloud Run.
      • PROJECT_ID: ID do projeto.
      • REGION: a Google Cloud região 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 é bem-sucedida, o Cloud Run fornece automaticamente um run.app URL, que serve como endpoint para consultar o serviço do 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
  • URL de exemplo:https://sample-a2a-agent-1234.europe-west1.run.app

Testar e monitorar a implantação do agente do A2A

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

Inspetor do 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 o agente esteja totalmente em conformidade com a especificação do 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 agente.
  • Valida a conformidade:verifica se o card atende às especificações do A2A.
  • Ativa o chat ao vivo:permite enviar e receber mensagens com o agente.
  • Mostra dados brutos:mostra mensagens JSON-RPC 2.0 brutas em um console para depuração.

Interação da CLI com um agente do A2A implantado

Use as ferramentas de interface de linha de comando (CLI) do repositório de exemplos do A2A para interagir com o serviço implantado. Essa CLI oferece suporte à 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 do A2A implantados

É possível testar o serviço do Cloud Run implantado localmente. Isso é particularmente ú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 o serviço do Cloud Run protegido pelo 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.