Implantar agentes A2A no Cloud Run

Este documento descreve como implantar seu agente A2A no Cloud Run. Essas etapas garantem uma operação segura, eficiente e escalonável no ambiente de nuvem.

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.

    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.

    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. Navegue até o diretório que contém o código-fonte do seu agente A2A:

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. Para os papéis e permissões do IAM necessários, consulte Papéis e permissões do IAM para agentes A2A do Cloud Run.

    14. Configurar a autenticação do serviço do Cloud Run

    Depois que o agente A2A estiver totalmente desenvolvido e o ambiente de implantação estiver preparado, configure a autenticação e use o comando gcloud run deploy para implantar o agente no Cloud Run.

    Use uma das seguintes opções para configurar o acesso e a autenticação do serviço do Cloud Run A2A:

    • Autenticação baseada no IAM para clientes internos Google Cloud :para clientes que operam em Google Cloud, como serviços internos como Agentspace, a autenticação baseada no IAM é a abordagem segura recomendada. Esses clientes usam contas de serviço e exigem o papel de chamador do Cloud Run (roles/run.invoker) para invocar seu serviço do Cloud Run. Para mais informações, consulte Autenticação serviço a serviço do Cloud Run.

      Para ativar a autenticação baseada no IAM para seu serviço do Cloud Run:

      • Use a flag --no-allow-unauthenticated durante a implantação.

    • Autenticação no nível do agente para exposição pública:se o servidor A2A for projetado para acesso público, ele vai processar a autenticação no nível do agente.

      Para permitir o acesso público ao serviço do Cloud Run:

    Implantar o agente A2A no Cloud Run

    Use o exemplo de ADK para implantar seu agente A2A. Especifique os seguintes parâmetros ao usar o comando gcloud run deploy:

    • Configuração de acesso:
      • Para usar a autenticação de serviço baseada no IAM, use a flag --no-allow-unauthenticated.
      • Para tornar os serviços públicos na Internet, use a flag --allow-unauthenticated.
    • Memória: o requisito mínimo de memória para a execução da instância de contêiner é 1Gi.
    • Chaves secretas: para usar chaves secretas, especifique os parâmetros DB_USER e DB_PASS.
    • Conta de serviço: para especificar uma conta de serviço, use o parâmetro a2a-service-account.
    • Variáveis de ambiente: para especificar variáveis de ambiente, use as seguintes variáveis:
      • APP_URL
      • DB_INSTANCE
      • DB_NAME
      • GOOGLE_GENAI_USE_VERTEXAI = true

    Para testes locais, use uma configuração TaskStore na memória. Para implantar seu serviço em produção, use o armazenamento permanente para um servidor A2A de produção. Confira um exemplo na seção Implantação do AlloyDB para PostgreSQL.

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

    Para implantar seu agente A2A com uma configuração TaskStore na memória, use o seguinte comando gcloud run deploy:

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --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"

    Se você não estiver no diretório que contém o código-fonte do seu agente A2A, atualize a flag --source com o caminho completo para o código do agente.

    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.

    Implantar com o AlloyDB para PostgreSQL

    Para manter as tarefas de 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:

    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 \
    --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"

    Se você não estiver no diretório que contém o código-fonte do seu agente A2A, atualize a flag --source com o caminho completo para o código do agente.

    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.

    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

    Depurar falhas de implantação

    Para depurar falhas de 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"