Hospedar um agente de A2UI com o Cloud Run

Neste tutorial, explicamos como implantar um agente de comunicação entre agentes (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 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
/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 com as ferramentas.
deploy.sh Script para criar e implantar o agente no Cloud Run.
examples/ Diretório que contém exemplos de modelos de componentes.
gemini_enterprise_composite_catalog.json Catálogo de componentes que define os componentes padrão do Material Design e personalizados do Gemini Enterprise.
main.py O ponto de entrada principal do aplicativo (app FastAPI).
prompt_builder.py Assistente 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 amostra que contém o layout e os dados simulados 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 do Gemini Enterprise. Para criar um, 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 seguintes APIs no 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 Manager (IAM)

Ativar 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 de 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 : ID do projeto.
  • PROJECT_NUMBER: o número do projeto do Google Cloud .

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 o ID do Google Cloud e um nome para o novo serviço. Também é possível especificar o modelo do Gemini a ser usado.

O script executa 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: ID do projeto.
  • MODEL_NAME: opcional. Esse é o terceiro argumento para o 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 é concluído, ele imprime 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 foi implantado, você precisa 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": "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 número do projeto do Google Cloud .
  • 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 número do projeto do Google Cloud .
  • 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 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 você precisa do 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 console Google Cloud , 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 e compartilhe-o 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 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, use 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, como mostrado no exemplo a seguir:

Exemplo de tabela de pedidos recentes