Visão geral da hospedagem de agentes A2A no Cloud Run

Este guia fornece uma visão geral de como preparar e configurar agentes Agent2Agent (A2A) para implantação no Cloud Run. Ele aborda etapas essenciais, como configurar um ambiente de nuvem, configurar os papéis necessários do Identity and Access Management (IAM) e preparar o agente para implantação.

Antes de começar

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

Roteiro de implantação do agente A2A

Para implantar o agente, siga estas etapas:

Arquitetura de alto nível

O núcleo do agente A2A é uma camada de serviço e orquestração, como o Cloud Run. Essa camada gerencia interações com modelos de IA, como Gemini e Vertex AI, armazenamentos de memória, como AlloyDB e A2A TaskStore, e ferramentas externas por APIs. Os clientes interagem com o agente enviando solicitações, como "Get Agent Card" ou "send message", e recebem atualizações de tarefas.

O diagrama a seguir ilustra a arquitetura de um sistema de agente A2A, mostrando um cliente A2A (usuário ou agente) interagindo com o agente A2A.

Arquitetura do agente A2A mostrando a interação do cliente com o agente por uma camada de veiculação e orquestração.
Arquitetura do agente A2A

Para informações sobre o ciclo de vida da solicitação A2A, consulte a seção Ciclo de vida da solicitação A2A.

Papéis e permissões do IAM para agentes do Cloud Run A2A

Os papéis do IAM configurados corretamente são importantes para que seu serviço do Cloud Run interaja com segurança com outros serviços do Google Cloud. Crie uma conta de serviço dedicada e conceda as permissões específicas listadas nas seções a seguir para garantir a segurança e a eficiência operacionais.

Criar uma conta de serviço do Cloud Run

Antes de executar qualquer comando gcloud, verifique se você está autenticado. Execute o comando a seguir para fazer login na sua conta do Google Cloud :

gcloud auth login

Crie uma conta de serviço especificamente para a instância do serviço A2A implantada. Use o comando gcloud iam service-accounts create.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

Substitua A2A_SERVICE_ACCOUNT_NAME pelo nome da conta de serviço.

Configurar papéis do IAM para o agente A2A

Atribua os seguintes papéis do IAM à sua conta de serviço com base nos serviços Google Cloud com que seu agente A2A interage:

Acesso ao Secret Manager para credenciais seguras

  • Função:Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Finalidade:permite que a conta de serviço do Cloud Run busque secrets, como credenciais de banco de dados, do Secret Manager de forma segura.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Acesso a modelos da Vertex AI para recursos de IA

  • Função:Vertex AI User (roles/aiplatform.user)

  • Finalidade:necessário para que a conta de serviço do Cloud Run invoque APIs de previsão em modelos da Vertex AI.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Acesso à instância do Alloy DB para armazenamento permanente (se aplicável)

  • Papéis:AlloyDB Client (roles/alloydb.client) e Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Finalidade:permite que a identidade do serviço do Cloud Run interaja com o cluster do AlloyDB para armazenamento de tarefas persistentes, o que é crucial para agentes A2A de produção.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Preparar o agente A2A para implantação do Cloud Run

Esta seção descreve as configurações necessárias para preparar seu agente A2A para implantação no Cloud Run, garantindo uma operação segura, eficiente e escalonável na nuvem.

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.

Por exemplo, crie e gerencie secrets de senha e usuário do banco de dados no Google Secret Manager usando a CLI gcloud. Para mais informações, consulte Criar um secret.

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"

Criar 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 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.

Confira a seguir um exemplo de Dockerfile para implantação de agente A2A:

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.

A seguir