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 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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  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. Install the 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 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. Install the 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 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: a função 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 o 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 seu Google Cloud ID do projeto.
    • 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

    Nesta seção, descrevemos as configurações necessárias para preparar seu agente A2A para implantação no Cloud Run em uma exemplo de código Python.

    Preparar o agente A2A

    1. Clone o repositório do app de amostra na máquina local para recuperar o exemplo de código:

      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 fazer a implantação 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 seu 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 cruciais 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 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 é bem-sucedida, o Cloud Run fornece automaticamente um run.app URL, 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 em total 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 card atende às especificações do A2A.
    • Ativa o chat ao vivo:permite enviar e receber mensagens com o agente.
    • 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 do Cloud Run implantado 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.