使用 Cloud Run 托管 A2UI 代理

本教程介绍了如何将使用智能体开发套件 (ADK) 和 A2UI 扩展程序构建的 Agent-to-Agent (A2A) 智能体部署到 Cloud Run。您还将学习如何向 Gemini Enterprise 注册已部署的代理。

此示例使用公开提供的示例代码。本教程的示例代码具有以下文件夹结构。

教程文件夹结构

该项目具有以下文件夹结构：

文件/目录 说明
/samples/community/agent/adk/gemini_enterprise/v0_9 包含本教程的示例配置和数据的目录。
__init__.py 将目录标记为 Python 软件包。
__main__.py 在本地运行智能体的入口点。
agent.py 定义智能体、其技能和行为。
agent_executor.py 管理执行流程和工具交互。
deploy.sh 用于构建智能体并将其部署到 Cloud Run 的脚本。
examples/ 包含组件模板示例的目录。
gemini_enterprise_composite_catalog.json 定义标准 Material 和自定义 Gemini Enterprise 组件的组件目录。
main.py 主应用入口点 (FastAPI 应用)。
prompt_builder.py 用于为模型构建提示的辅助工具。
pyproject.toml 项目配置和依赖项。
examples/0.9/material_table_orders.json 示例界面模板，其中包含近期订单演示的布局和模拟数据。
tools.py 定义智能体可以使用的工具（函数）。

准备工作

在开始之前，请确保满足以下条件：

  • Discovery Engine Admin 角色。

  • 现有的 Gemini Enterprise 应用。如需创建应用，请参阅创建应用。

  • 克隆代码库并前往 v0_9 示例目录：

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

启用 API

为您的项目启用以下 API：

控制台

启用以下 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) API

启用 API

REST

您可以通过 Google Cloud 控制台或使用以下 gcloud CLI 命令启用这些 API：

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

授予权限

向 Cloud Run Invoker (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"

替换以下内容：

  • PROJECT_ID：您的项目的 ID。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。

部署智能体

deploy.sh 脚本可自动执行部署过程。如需部署代理，请在项目目录中运行脚本，并提供 Google Cloud ID 和新服务的名称。您还可以选择指定要使用的 Gemini 模型。

该脚本会执行以下操作：

  1. 根据源代码构建容器映像。
  2. 将映像推送到 Artifact Registry。
  3. 将映像部署到 Cloud Run。
  4. 设置环境变量，包括 MODEL 和服务本身的公共 AGENT_URL。
chmod +x deploy.sh
./deploy.sh PROJECT_ID a2ui-demo-agent MODEL_NAME

替换以下内容：

  • PROJECT_ID：您的项目的 ID。
  • MODEL_NAME：可选。这是脚本的第三个参数。支持的值包括 gemini-2.5-pro 和 gemini-2.5-flash。 如果未提供，脚本会默认使用 gemini-2.5-flash。

脚本完成后，会输出已部署代理的服务网址。您在下一步中需要此服务网址。

向 Gemini Enterprise 注册代理

部署代理后，您需要向 Gemini Enterprise 注册该代理，以便其可被检测到。

运行以下 curl 命令，将占位符替换为您自己的值：

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\"]}"
    }
}'

替换以下内容：

  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION：数据存储区的多区域：global、us 或 eu
  • ENGINE_ID：您要向其注册智能体的应用的 ID。
  • AGENT_URL：已部署智能体的服务网址。

取消注册代理（可选）

如果您想取消注册代理，请运行以下 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

替换以下内容：

  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • LOCATION：数据存储区的多区域：global、us 或 eu
  • ENGINE_ID：代理注册到的应用的 ID。
  • AGENT_ID：要删除的智能体的 ID。

在 Gemini Enterprise Web 应用中使用代理

创建并注册代理后，您可以在 Gemini Enterprise Web 应用中开始使用该代理并与之互动。

获取 Web 应用网址

如需使用代理，您首先需要获取 Web 应用网址。Gemini Enterprise 管理员可以按照以下步骤获取和分享 Web 应用网址：

  1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

    Gemini Enterprise

  2. 点击您向其注册了代理的应用的名称。

  3. 点击集成 (Integrations)。

  4. 复制指向您的 Web 应用的链接：，并将其分享给组织中的用户。

使用智能体

如需使用代理并与之互动，请执行以下操作：

  1. 在新浏览器标签页中打开该 Web 应用网址。
  2. 在 Web 应用导航菜单中，点击代理。
  3. 前往来自您的组织部分，然后点击您创建的代理。
  4. 系统会打开智能体的对话界面。开始提问并与智能体互动

例如，您可以使用 Show me the recent orders table 等提示来获取有关抽样数据中近期订单的信息。智能体从 material_table_orders.json 检索订单信息，并使用自定义界面组件在对话中呈现列表，如以下示例所示：

近期订单表示例