Hospedar um agente A2UI com o Cloud Run

Este tutorial explica como implantar um agente de agente para agente (A2A, na sigla em inglês), criado com o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) do Google e a extensão A2UI, no Cloud Run. Você também vai aprender a registrar o agente implantado no Gemini Enterprise.

O exemplo de código deste tutorial tem a seguinte estrutura de pastas.

Estrutura de pastas do tutorial

O projeto tem a seguinte estrutura de pastas:

Arquivo/diretório Descrição
examples/0.8/ Diretório que contém configurações ou dados de exemplo.
__init__.py Marca o diretório como um pacote Python.
agent.py Define o agente, as habilidades e o comportamento dele.
agent_executor.py Gerencia o fluxo de execução e as interações de ferramentas.
contact_data.json Dados de amostra usados pelo agente (por exemplo, contatos de simulação).
deploy.sh Script para criar e implantar o agente no Cloud Run.
main.py O ponto de entrada principal do aplicativo (app FastAPI).
prompt_builder.py Auxiliar para criar comandos para o modelo.
pyproject.toml Configuração e dependências do projeto.
tools.py Define as ferramentas (funções) que o agente pode usar.

Antes de começar

Antes de começar, certifique-se de ter:

  • O papel de administrador do Discovery Engine.

  • Um app do Gemini Enterprise. Para criar um app, consulte Criar um app.

  • Clone o repositório e navegue até o diretório de amostra cloud_run:

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Ativar APIs

Ative as seguintes APIs para seu projeto:

Console

Ative as APIs a seguir:

  • API Agent Platform
  • API Cloud Build
  • API Artifact Registry
  • API Cloud Run
  • API Cloud Logging
  • API Discovery Engine
  • API Cloud Storage
  • API Identity and Access Management (IAM)

Ative as APIs

REST

É possível ativar essas APIs no Google Cloud console ou usando o seguinte comando da CLI gcloud:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Conceder permissões

Conceda permissão ao papel Invocador do Cloud Run (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Substitua:

  • PROJECT_ID : o ID do projeto.
  • PROJECT_NUMBER: o número do seu Google Cloud projeto.

Implantar o agente

O script deploy.sh automatiza o processo de implantação. Para implantar o agente, execute o script no diretório do projeto com seu Google Cloud ID e um nome para o novo serviço. Você também pode especificar o modelo do Gemini a ser usado.

O script realiza as seguintes ações:

  1. Cria uma imagem de contêiner com base no código-fonte.
  2. Envia a imagem para o Artifact Registry.
  3. Implanta a imagem no Cloud Run.
  4. Define variáveis de ambiente, incluindo o MODEL e o AGENT_URL público do próprio serviço.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Substitua:

  • PROJECT_ID: o ID do projeto.
  • MODEL_NAME: opcional. Esse é o terceiro argumento do script. Os valores aceitos são gemini-2.5-pro e gemini-2.5-flash. Se não for fornecido, o script será definido como gemini-2.5-flash.

Quando o script for concluído, ele vai imprimir o URL de serviço do agente implantado. Você vai precisar desse URL de serviço na próxima etapa.

Registrar o agente no Gemini Enterprise

Agora que o agente está implantado, é necessário registrá-lo no Gemini Enterprise para que ele possa ser descoberto.

Execute o seguinte comando curl, substituindo os marcadores de posição pelos seus próprios valores:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Substitua:

  • PROJECT_NUMBER: o Google Cloud número do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu.
  • ENGINE_ID: o ID do app em que você quer registrar o agente.
  • AGENT_URL: o URL de serviço do agente implantado.

Usar o agente no app da Web do Gemini Enterprise

Depois que um agente é criado e registrado, você pode começar a usá-lo e interagir com ele no app da Web do Gemini Enterprise.

Acessar o URL do app da Web

Para usar o agente, primeiro é necessário acessar o URL do app da Web. Um administrador do Gemini Enterprise pode acessar e compartilhar o URL do app da Web seguindo estas etapas:

  1. No Google Cloud console, acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome do app em que você registrou o agente.

  3. Clique em Integrations.

  4. Copie o Link para o app da Web app e compartilhe com os usuários da organização.

Usar o agente

Para usar e interagir com o agente, faça o seguinte:

  1. Abra o URL do app da Web em uma nova guia do navegador.
  2. No menu de navegação do app da Web, clique em Agentes.
  3. Acesse a seção Da sua organização e clique no agente que você criou.
  4. Isso abre a interface de conversa do agente. Comece a fazer perguntas e interagir com o agente.

Por exemplo, você pode pedir ao agente para listar todos os contatos. O agente usa a ferramenta list_contacts para recuperar os contatos de contact_data.json e renderiza a lista no chat usando elementos de UI personalizados, conforme mostrado no exemplo a seguir:

Exemplo de agente de contatos