Alojamento de agentes A2A no Cloud Run: vista geral

Este guia fornece uma vista geral de como preparar e configurar agentes Agent2Agent (A2A) para implementação no Cloud Run. Abrange passos essenciais, como a configuração de um ambiente na nuvem, a configuração das funções de gestão de identidades e acessos (IAM) necessárias e a preparação do seu agente para implementação.

Antes de começar

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

Plano de implementação do agente A2A

Para implementar o seu agente, conclua os seguintes passos:

Arquitetura de nível elevado

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

O diagrama seguinte ilustra a arquitetura de um sistema de agente A2A, mostrando um cliente A2A (utilizador ou agente) a interagir com o agente A2A.

Arquitetura do agente A2A que mostra a interação do cliente com o agente através de uma camada de publicação e orquestração.
Arquitetura do agente A2A

Para informações sobre o ciclo de vida do pedido A2A, consulte a secção Ciclo de vida do pedido A2A.

Funções e autorizações de IAM para agentes A2A do Cloud Run

As funções do IAM configuradas corretamente são importantes para que o seu serviço do Cloud Run interaja de forma segura com outros serviços Google Cloud. Crie uma conta de serviço dedicada e conceda as autorizações específicas indicadas nas secções seguintes para garantir a segurança e a eficiência operacionais.

Crie uma conta de serviço do Cloud Run

Antes de executar quaisquer comandos gcloud, certifique-se de que tem a autenticação feita. Execute o comando seguinte para iniciar sessão na sua Google Cloud conta:

gcloud auth login

Crie uma conta de serviço especificamente para a instância do serviço A2A implementada. 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.

Configure funções IAM para o agente A2A

Atribua as seguintes funções do IAM à sua conta de serviço com base nos Google Cloud serviços com os quais o seu agente A2A interage:

Acesso ao Gestor Secreto para credenciais seguras

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

  • Finalidade: permite que a conta de serviço do Cloud Run obtenha em segurança segredos, como credenciais da base de dados, do Secret Manager.

    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 ao modelo da Vertex AI para capacidades de IA

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

  • Finalidade: obrigatório para que a conta de serviço do Cloud Run invoque APIs de previsão em modelos do 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 AlloyDB para armazenamento persistente (se aplicável)

  • Funções: 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 o armazenamento de tarefas persistente, o que é fundamental para os 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"

Prepare o agente A2A 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, garantindo um funcionamento seguro, eficiente e escalável na nuvem.

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 Configurar segredos no Cloud Run.

Por exemplo, crie e faça a gestão de segredos de palavras-passe e utilizadores de bases de dados no Google Secret Manager através da gcloudCLI. Para mais informações, consulte o artigo Crie um segredo.

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"

Crie um Dockerfile para a 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.

Segue-se um exemplo de um Dockerfile para a implementação de um 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"]

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, o que simplifica o processo de contentorização.

O que se segue?