Implemente agentes A2A no Cloud Run

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

Este guia aborda os passos essenciais para implementar agentes A2A:

Reveja a especificação A2A e os agentes de exemplo

Antes de começar a desenvolver e implementar o 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. Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a 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. Install the Google Cloud CLI.

  10. Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a 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 apresentar na consola Google Cloud

    Conceda as funções da conta de serviço

    Para conceder as funções de IAM necessárias à 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"

    Substituir:

    • PROJECT_ID: o ID do seu projeto
    • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta de serviço
    • ROLE: a função que está a adicionar à conta de serviço

    Funções necessárias

    Para receber as autorizações de que precisa para implementar agentes A2A, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

    Conceda as funções

    Consola

    1. Na Google Cloud consola, aceda à página IAM.

      Aceda ao IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.

    4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email usado para implementar o serviço do Cloud Run.

    5. Na lista Selecionar uma função, selecione uma função.
    6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
    7. Clique em Guardar.

    gcloud

    Para conceder as funções de IAM necessárias à sua conta no seu projeto:

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

    Substituir:

    • PROJECT_NUMBER com o número do seu Google Cloud projeto.
    • PROJECT_ID com o ID do seu Google Cloud projeto.
    • PRINCIPAL com a conta à qual está a adicionar a associação. Normalmente, este é o endereço de email que é usado para implementar o serviço do Cloud Run.
    • ROLE com a função que está a adicionar à conta do implementador.

    Prepare-se para a implementação do Cloud Run

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

    Prepare o agente A2A

    1. Obtenha o exemplo de código clonando o repositório da app de exemplo para o seu computador local:

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

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

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

    Configure segredos para serviços do Cloud Run

    Forneça todas as credenciais confidenciais, como chaves da API e palavras-passe da base de dados, ao seu servidor A2A através de um mecanismo seguro. O Cloud Run suporta o fornecimento de segredos como variáveis de ambiente ou volumes montados dinamicamente. Para mais informações, consulte o artigo Configure segredos no Cloud Run.

    Os agentes precisam de acesso a serviços externos para concluir as respetivas tarefas. Os Secrets são o mecanismo seguro para conceder esse acesso. Quando implementar com o AlloyDB for PostgreSQL, precisa do utilizador e da palavra-passe. Crie e faça a gestão dos segredos do utilizador e da palavra-passe da base 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 Crie um segredo.

    Dockerfile para contentorização

    O Cloud Run pode implementar serviços a partir de imagens de contentores já alojadas ou diretamente a partir do seu código fonte. Quando implementa a partir do código-fonte, o Cloud Run cria automaticamente uma imagem de contentor se existir um Dockerfile no diretório raiz do seu projeto.

    O Dockerfile determina os detalhes da imagem do contentor. Segue-se o Dockerfile do agente A2A de exemplo que 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"]

    Implemente a partir do código-fonte sem um Dockerfile

    Para repositórios de código fonte sem um Dockerfile, o Cloud Run oferece suporte integrado para determinadas linguagens de programação populares, simplificando o processo de contentorização.

    Implemente o agente A2A no Cloud Run

    Implemente a sua aplicação 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 respetivos dados exclusivamente na instância do contentor do Cloud Run. Isto significa que todos os dados das tarefas são perdidos quando a instância do contentor é encerrada, reduzida ou reiniciada.
    • O AlloyDB para PostgreSQL oferece persistência de dados, o que permite aos agentes serem dimensionados horizontalmente e garante que as tarefas sobrevivem a reinícios de contentores, eventos de dimensionamento e implementações.

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

    Os comandos seguintes mostram como usar a autenticação baseada no IAM para o seu serviço do Cloud Run. A utilização da flag --no-allow-unauthenticated no momento da implementação é a abordagem recomendada para configurar a autenticação para clientes Google Cloud internos, como o Gemini Enterprise.

    Se o seu servidor A2A estiver concebido para acesso público e precisar de processar a autenticação ao nível do agente, pode especificar a flag --allow-unauthenticated durante a implementação. Consulte o artigo 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, também tem de fornecer informações de autenticação cruciais no cartão do seu agente A2A através dos parâmetros securitySchemes e security. Para mais informações, consulte Especificação A2A: detalhes do objeto SecurityScheme.

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

    Para implementar o 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 o seguinte:

    • REGION: a Google Cloud região onde quer implementar o seu serviço, por exemplo, europe-west1.
    • PROJECT_ID: o ID do projeto.
    • PROJECT_NUMBER: o número do seu projeto.
    • A2A_SERVICE_ACCOUNT_NAME: o nome da sua conta do serviço A2A.

    Faça a implementação 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 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 o seguinte:

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

    Depure falhas de implementação

    Se encontrar erros ou 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 run.app URL devolvido pelo comando de implementação diferir do URL determinístico esperado, atualize a APP_URL variável de ambiente 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 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"

    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

    Teste e monitorize a implementação de agentes A2A

    Depois de implementar com êxito o seu agente A2A no Cloud Run, teste minuciosamente a respetiva funcionalidade. Estabeleça práticas de monitorização rigorosas para garantir o desempenho e a fiabilidade contínuos.

    Inspetor A2A: valide a conformidade dos agentes

    Use a ferramenta a2a-inspector para inspecionar, depurar e validar o seu agente Google A2A implementado. Esta ferramenta garante que o seu agente está totalmente em conformidade com a especificação A2A e funciona corretamente.

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

    • Apresenta o cartão do agente: mostra automaticamente o cartão do seu agente.
    • Valida a conformidade: verifica se o cartão cumpre as especificações da A2A.
    • Ativa o chat em direto: permite-lhe enviar e receber mensagens com o agente.
    • Mostra dados não processados: apresenta mensagens JSON-RPC 2.0 não processadas numa consola para depuração.

    Interação da CLI com um agente A2A implementado

    Use as ferramentas da interface de linhas de comando (CLI) do repositório de exemplos A2A para interagir com o serviço implementado. Esta CLI suporta a autenticação baseada em tokens de portador.

    Se o seu serviço usar a autenticação baseada na 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 seu serviço do Cloud Run implementado.

    Testes locais de serviços A2A implementados

    Pode testar o serviço do Cloud Run implementado localmente. Isto é particularmente útil quando implementa a autenticação baseada na IAM.

    Teste a autenticação baseada na IAM para agentes do Cloud Run

    Os clientes que interagem com o seu serviço do Cloud Run protegido pela gestão de identidade e de acesso (IAM) têm de ter a função de IAM roles/run.invoker.

    Teste localmente o fluxo de autenticação do serviço implementado com 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 seu serviço do Cloud Run implementado.