Implemente agentes A2A no Cloud Run

Este documento descreve como implementar o seu agente A2A no Cloud Run. Estes passos garantem um funcionamento seguro, eficiente e escalável no ambiente da 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. Make sure that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    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. Make sure that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. Navegue para o diretório que contém o código-fonte do agente A2A:

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. Para ver as funções e as autorizações de IAM necessárias, consulte Funções e autorizações de IAM para agentes A2A do Cloud Run.

Configure a autenticação do serviço do Cloud Run

Depois de o agente A2A estar totalmente desenvolvido e o respetivo ambiente de implementação preparado, tem de configurar a autenticação e usar o comando gcloud run deploy para implementar o agente no Cloud Run.

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

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

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

    • Tem de usar a flag --no-allow-unauthenticated durante a implementação.

  • Autenticação ao nível do agente para exposição pública: se o seu servidor A2A for concebido para acesso público, processa a autenticação ao nível do agente.

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

Implemente o agente A2A no Cloud Run

Use o exemplo de ADK existente para implementar o seu agente A2A. Especifique os seguintes parâmetros quando 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 instância do contentor ser executada é de 1Gi.
  • Secrets: para usar secrets, 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 TaskStorena memória. Para implementar o seu serviço em produção, tem de usar armazenamento persistente para um servidor A2A de produção. Veja um exemplo na secção Implementação do AlloyDB para PostgreSQL.

Implemente com uma configuração de TaskStore na memória

Para implementar o 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 não estiver no diretório que contém o código fonte do agente A2A, atualize a flag --source com o caminho completo para o código do agente.

Substitua o seguinte:

  • REGION: a Google Cloud região onde quer implementar o seu serviço. Por exemplo, europe-west1.
  • PROJECT_ID: o ID do seu projeto.
  • PROJECT_NUMBER: o número do seu projeto.

Implemente com o AlloyDB para PostgreSQL

Para persistir tarefas A2A, use o AlloyDB for PostgreSQL. Para implementar o seu agente A2A com o AlloyDB for PostgreSQL para armazenamento de tarefas persistente, 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 não estiver no diretório que contém o código fonte do agente A2A, atualize a flag --source com o caminho completo para o código do agente.

Substitua o seguinte:

  • REGION: a Google Cloud região onde quer implementar o seu serviço. Por exemplo, europe-west1.
  • PROJECT_ID: o ID do seu projeto.
  • PROJECT_NUMBER: o número do seu projeto.
  • CLUSTER_NAME: o nome do seu cluster do AlloyDB for PostgreSQL.

Compreenda o URL da aplicação do Cloud Run

Após a implementação bem-sucedida, o Cloud Run fornece automaticamente um run.app URL, que funciona como o ponto final para consultar o 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
  • URL de exemplo: https://sample-a2a-agent-1234.europe-west1.run.app

Depure falhas de implementação

Para depurar falhas de implementação do Cloud Run, considere o seguinte:

  • Registos detalhados: para ver registos de implementação detalhados, defina a flag --verbosity=info no comando gcloud run deploy.

  • Diferença entre URLs: se o URL run.app devolvido pelo comando de implementação diferir do URL determinístico esperado, atualize a variável de ambiente APP_URL para o seu 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 o seguinte:

      • SERVICE_NAME: o nome do seu serviço do Cloud Run.
      • PROJECT_ID: o ID do seu projeto.
      • REGION: a Google Cloud região onde quer implementar o seu serviço. Por exemplo, europe-west1.
      • CLOUD_RUN_SERVICE_URL: o URL do seu serviço do Cloud Run.

    2. Confirme se o elemento APP_URL está atualizado corretamente descrevendo o serviço:

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