Hospedar um agente de 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) e a extensão A2UI, no Cloud Run. Você também vai aprender a registrar o agente implantado no Gemini Enterprise.

Este exemplo usa um exemplo de código disponível publicamente. O exemplo de código para este 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
/samples/community/agent/adk/gemini_enterprise/v0_9 Diretório que contém configurações e dados de exemplo para este tutorial.
__init__.py Marca o diretório como um pacote Python.
__main__.py O ponto de entrada para executar o agente localmente.
agent.py Define o agente, as habilidades e o comportamento dele.
agent_executor.py Gerencia o fluxo de execução e as interações da ferramenta.
deploy.sh Script para criar e implantar o agente no Cloud Run.
examples/ Diretório que contém exemplos de modelo de componente.
gemini_enterprise_composite_catalog.json Catálogo de componentes que define componentes padrão do Material e personalizados do Gemini Enterprise.
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.
examples/0.9/material_table_orders.json Modelo de interface de exemplo que contém o layout e os dados de simulação para a demonstração de pedidos recentes.
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 Gemini Enterprise. Para criar um app, consulte Criar um app.

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

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

Ativar APIs

Ative as APIs a seguir para seu projeto:

Console

Ative as APIs a seguir:

  • API Vertex AI
  • 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 PROJECT_ID a2ui-demo-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 vai usar gemini-2.5-flash como padrão.

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 pelos seus 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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"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.

Cancelar o registro do agente (opcional)

Se você quiser cancelar o registro do agente, execute o seguinte comando curl:

curl -X DELETE -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/AGENT_ID

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 o agente está registrado.
  • AGENT_ID: o ID do agente que você quer excluir.

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.

Receber o URL do app da Web

Para usar o agente, primeiro é necessário receber o URL do app da Web. Um administrador do Gemini Enterprise pode receber 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 seu 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ção do agente. Comece a fazer perguntas e interagir com o agente.

Por exemplo, você pode usar um comando como Show me the recent orders table para receber informações sobre pedidos recentes que fazem parte dos dados de amostra. O agente recupera as informações do pedido de material_table_orders.json e renderiza a lista no chat usando componentes UI personalizados, conforme mostrado no exemplo a seguir:

Exemplo de tabela de pedidos recentes