在 Agent Studio 中设计智能体

本页面简要介绍了如何在Cloud de Confiance 控制台中使用 Agent Studio。

Agent Studio 是 Cloud de Confiance 控制台中的一款低代码视觉设计器，可简化智能体开发。您可以直观地规划智能体工作流、实时测试回答，并在部署或过渡到代码之前尝试不同的配置。

本文档简要介绍了 Agent Studio，并说明了如何设置环境、创建和测试智能体，以及如何将智能体直接部署到生产运行时。

设置环境

在使用 Agent Studio 之前，请先设置Cloud de Confiance by S3NS。

获取所需的角色

如需获得使用 Agent Studio 所需的权限，请让您的管理员为您授予项目的 Agent Platform User (roles/aiplatform.user) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建代理

您可以在 Agent Studio 中使用提示或流程构建器创建代理。

使用提示创建代理

如需使用提示创建代理，请按以下步骤操作：

  1. 在 Cloud de Confiance 控制台中，前往代理页面。

    前往“代理”

  2. 点击创建代理，打开 Agent Studio 画布，创建新代理。

  3. 在对话框中，输入描述代理用途和预期行为的提示。

  4. 点击 。

  5. 根据您的提示，系统会执行以下操作之一：

    • 成功：流程构建器会立即更新，显示智能体的实时预览，并且对话会提供所做修改的摘要。系统会自动保存所有更改。

    • 需要澄清：如果您的提示不明确，助理会在对话中提出澄清性问题，以便更好地了解您想要构建的内容。

    • 错误：如果助理无法应用您的提示，系统会显示一条出错提示，提示您重新表述请求。

  6. 您可以继续使用提示或流程构建器来更新代理。

  7. 如需保存代理，请点击画布标题中的保存，然后按照提示操作。如需了解详情，请参阅保存代理。

  8. 在构建智能体时，如需测试智能体的功能和回答，请点击预览标签页，然后与智能体对话。

限制

使用提示创建代理时，存在以下限制：

能力 限制
知识 无法向代理添加知识。您可以使用流程构建器界面向代理添加知识。

使用流程构建器创建代理

请按照以下步骤使用流程构建器设计和测试智能体：

  1. 在 Cloud de Confiance 控制台中，前往代理页面。

    前往“代理”页面

  2. 点击创建代理，打开 Agent Studio 画布，以创建新代理。

  3. 在 Agent Studio 画布中设计并保存智能体。您可以创建主代理并添加子代理。主代理始终是本地代理。 子智能体可以是本地智能体，也可以是 Agent Registry 智能体：

    • 本地智能体：一种智能体，其指令、模型和工具直接在 Agent Studio 画布中编写和配置。
    • Agent Registry 代理：已在 Agent Registry 中注册并发布的代理。您可以在主代理的流程中使用这些代理作为远程子代理。

    在设计时，您可以在以下流程和预览标签页之间切换：

    Flow

    使用智能体工作流和控制逻辑的直观表示形式创建主代理和子代理。

    1. 点击某个代理，打开该代理的详细信息面板。您也可以点击添加子智能体 (+) 来添加子智能体。

    2. 在详细信息面板中配置主代理和子代理：

      对于主代理和本地子代理：

      1. 名称：添加一个名称，以便识别代理。
      2. 说明：对代理用途的总结。
      3. 指令：添加指令来引导智能体。
      4. 模型：选择要为智能体提供支持的模型。
      5. 工具：点击添加工具 (+) 以添加可让智能体完成任务的工具。如需了解详情，请参阅设置和添加工具。

      对于子智能体（本地或来自智能体注册表）：

      1. 子代理来源：选择子代理的来源：

        • 本地：直接在画布上创作子代理的指令、模型和工具。
        • Agent Registry：从 Agent Registry 中选择已注册的代理作为远程子代理。此选项仅在您保存代理后可用。如需了解详情，请参阅保存代理。

        选择已注册的代理后，系统会从注册表中导入其名称和说明，并在画布上将其设为只读。父智能体根据子智能体的智能体卡片将任务路由至该子智能体。

        如需运行或部署父智能体，父智能体的身份必须具有发现和调用 A2A 子智能体的权限。权限对话框会自动处理此操作。如果您需要手动管理权限，请参阅授予代理到代理 (A2A) 委托的访问权限。

    3. 如需保存代理，请点击画布标题中的保存，然后按照提示操作。如需了解详情，请参阅保存代理。

    预览

    在预览窗格中与您的代理 Chat，以测试其功能和回答。

    • 如需预览已保存的智能体，Agent Studio 会验证智能体的身份权限。如果缺少必需的角色，系统会显示通知。点击管理以打开权限对话框并管理智能体身份权限。
    • 您可以检查每次代理运行中的事件，以调试代理的行为。 如需了解详情，请参阅检查代理事件。

  4. 点击获取代码即可查看您的代理代码。如果您想在其他地方继续开发智能体，可以复制代码并将其粘贴到您选择的代码编辑器中。

    如果您的代理使用 Agent Registry 中的远程子代理，则生成的 Python 代码会包含对 AgentRegistry.get_remote_a2a_agent 的调用，以便在运行时动态解析子代理。

智能体构建完成后，您可以直接从 Agent Studio 进行部署。 如需了解详情，请参阅从 Agent Studio 部署代理。

使用 Studio 提示中的“智能体”模式切换开关创建智能体

您可以直接从 Agent Studio 欢迎提示开始构建智能体，只需切换到智能体模式即可。启用后，直接提交提示会在代理设计工具画布中启动代理构建器。

请按照以下步骤，通过 Studio 提示构建代理：

  1. 在 Cloud de Confiance 控制台中，前往 Agent Studio。

  2. 在欢迎工作区的主提示输入区域中，找到模式切换开关。

  3. 将切换开关切换到代理模式。

  4. 输入提示，描述您要设计的代理的用途、工作流和行为。

  5. 点击 。

Agent Studio 会直接在智能体设计工具画布中启动智能体构建器工作，并根据您的提示预先填充智能体流程和配置。然后，您可以继续编辑指令、选择模型以及添加工具或子智能体。

检查代理事件

检查事件有助于您调试智能体的行为，并排查问题和跟踪智能体的推理过程和模型请求。

您可以在 Agent Studio 的预览标签页中检查智能体事件，从而调试智能体执行。此操作可让您诊断智能体在运行期间生成的各个事件中的问题。

如需检查代理事件，请按以下步骤操作：

  1. 在 Agent Studio 画布中打开代理，然后打开预览标签页。
  2. 在预览窗格中与智能体开始对话，以启动运行。

  3. 选择对话中的某个事件，即可打开其详细信息。可用的详细信息取决于事件，可能包括以下内容：

    • 作者：生成事件的代理或子代理。使用作者来标识在多代理工作流中执行某一步骤的子代理。
    • 请求和响应：发送给模型的载荷和返回的响应。
    • 工具调用：在智能体执行期间传递给工具的参数。
    • 元数据：其他诊断信息，例如模型名称、令牌使用情况和时间戳。

如果代理在预览期间返回错误，该错误会显示在预览标签页中，以便您诊断问题。

保存智能体

您必须先保存智能体，然后才能预览、部署或上传知识文件，因为未保存的智能体还没有身份。此要求也适用于 Agent Registry 子代理。

此外，您还必须先保存代理，然后才能将 Agent Registry 中发布的 MCP 服务器添加为节点级工具。

如需首次保存代理，请执行以下操作：

  1. 在 Agent Studio 画布中，点击保存。

  2. 在保存代理对话框中，输入代理名称。

  3. 点击保存。

首次保存后，Agent Studio 会自动保存您所做的任何后续更改。如果您在保存新智能体之前尝试离开画布，Agent Studio 会提示您先保存。

更新智能体

请按照以下步骤更新代理：

  1. 在 Cloud de Confiance 控制台中，前往代理页面。

    前往“代理”页面

  2. 在要更新的代理上，点击 ，然后点击修改。

  3. 使用提示或流程构建器更新智能体。

Agent Studio 会自动保存您所做的更改。

在 Agent Studio 中设置和添加工具

您可以为智能体配置以下工具：

  • Google 搜索：让智能体能够使用 Google 搜索执行网页搜索。 默认处于开启状态。

  • 网址上下文：让模型能够分析发送给代理的提示中的网址。 默认处于开启状态。

  • 来自 Agent Registry 的 MCP 服务器：将 Agent Registry 中发布的 MCP 服务器附加为节点级工具。此选项仅在您保存代理后可用。如需了解详情，请参阅保存代理。

    1. 点击来自 Agent Registry 的 MCP 服务器旁边的添加 (+)。
    2. 位置：选择要过滤已注册工具的区域。
    3. MCP 服务器：从列表中选择已注册的 Google MCP 服务器。
    4. Auth 配置：选择无，以使用通过 IAM 绑定解析的标准服务访问权限。
    5. 点击 Add（添加）。
    6. 如果您是首次保存代理，请点击画布标题中的保存。后续更改会自动保存。

    您的智能体可以使用已连接的 MCP 服务器中的所有工具。

迁移旧版工具

为了通过 Agent Registry 强制执行安全措施并标准化工具管理，Agent Studio 弃用了与 Vertex AI Search 数据存储区和直接 Model Context Protocol (MCP) 服务器的直接集成。

对于现有代理，这些已弃用的工具处于只读状态。为保持完整功能，请迁移到 Agent Registry 中的 MCP 服务器。

从旧版 Vertex AI Search 数据存储区迁移

如果您的代理使用已弃用的 Agent Platform Search 数据存储区工具，请迁移到 Agent Registry 中提供的 Agent Search MCP 服务器。此工具在代理注册表中显示为 discoveryengine.googleapis.com。

连接 Agent Search MCP 服务器时，您必须在代理的指令中定义目标服务配置。此外，代理身份需要访问权限。

如需迁移，请按以下步骤操作：

  1. 在 Agent Studio 画布中打开您的代理。
  2. 在工具面板中找到 Vertex AI Search 数据存储区工具。
  3. 记下该工具的设置，例如项目 ID、位置和数据存储区 ID。
  4. 创建新代理并保存。
  5. 向代理身份授予 Discovery Engine Viewer (roles/discoveryengine.viewer) 角色。我们建议直接在目标数据存储区或搜索应用上授予此角色。不过，出于问题排查目的，您可以在项目上授予此权限。如需查找代理的身份主体并授予角色，请参阅手动管理角色。代理还需要 MCP Tool User 角色 (roles/mcp.toolUser)，权限对话框会自动授予该角色。
  6. 在工具面板中，点击来自 Agent Registry 的 MCP 服务器旁边的添加 (+)。
  7. 指定下列内容：
    1. 位置：选择工具注册所在的区域。
    2. MCP 服务器：从已注册的 MCP 服务器列表中选择 Agent Search 或 discoveryengine.googleapis.com。
    3. 身份验证配置：选择无。访问权限通过标准 IAM 绑定进行解析。
    4. 点击 Add（添加）。

  8. 在新代理的指令中，使用您在第 3 步中记下的值指定目标投放配置。例如：

    Use the search tool to answer questions about YOUR_TOPIC.
When using the search tool, use this servingConfig:
projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search

    对于搜索应用，请将 dataStores/DATA_STORE_ID 替换为 engines/APP_ID。如需了解支持的格式和实参，请参阅 MCP 工具参考文档：discoveryengine.googleapis.com。

从旧版直接 MCP 服务器迁移

如果您的代理使用端点网址直接连接到 MCP 服务器，您必须先在 Agent Registry 中注册 MCP 服务器目录。

如需迁移工具，请按以下步骤操作：

  1. 确保您的 MCP 服务器已在 Agent Registry 中注册。
  2. 在 Agent Studio 中更新代理：
    1. 在 Agent Studio 画布中打开您的代理。
    2. 找到并移除旧版直接 MCP 服务器连接。
    3. 点击来自 Agent Registry 的 MCP 服务器 旁边的添加 (+)。
    4. 从列表中选择已注册的 MCP 服务器。
    5. 点击 Add（添加）。
    6. 如果您是首次保存代理，请点击画布标题中的保存。后续更改会自动保存。

使用知识文件作为智能体的依据

在 Agent Studio 中上传静态参考文档，以便为智能体的回答提供依据：

  1. 在画布上选择要附加参考文件的父智能体节点。请注意，您无法将知识文件附加到子代理。
  2. 在节点的详细信息面板中，找到知识部分。只有在您首次保存代理后，系统才会显示知识部分。如需了解详情，请参阅保存代理。
  3. 点击文件上传组件，然后浏览并选择参考文件。 每个代理最多可附加 10 个文件。文件大小不得超过 2 兆字节 (2 MB)。上传画布支持以下文件类型：
    • PDF
    • 纯文本

  4. 如果您是首次保存智能体，请点击画布标题中的保存，将文件存储在专用 Cloud Storage 存储桶中，路径前缀与父智能体的 AGENT_ID 匹配。后续更改会自动保存。

    权限对话框会向代理在存储桶上的身份授予 Storage Object Viewer 角色 (roles/storage.objectViewer)。

  5. 前往预览标签页，提交测试查询，验证智能体是否使用文件内容作为回答依据，而不会产生幻觉。

  6. 可选：您可以点击获取代码来复制生成的 Python 代码 (agent.py) 并检查基础文件配置。 您可以跳过此步骤。

管理代理身份权限

Agent Studio 中的每个智能体都有一个唯一身份，该身份充当 IAM 主账号，用于访问其他 Cloud de Confiance by S3NS 资源。

主账号格式为：

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

替换以下内容：

  • ORGANIZATION_ID：您组织的数字 ID。
  • PROJECT_NUMBER：您的Cloud de Confiance by S3NS 项目的项目编号。
  • LOCATION：智能体的部署区域。
  • REASONING_ENGINE_ID：推理引擎的资源 ID。

如需详细了解智能体身份，请参阅创建具有智能体身份的智能体和智能体身份概览。

权限对话框行为

当您点击部署或打开已保存代理的预览标签页时，Agent Studio 会自动检查代理的身份是否具有成功运行所需的 IAM 角色集。如果权限设置错误，某些缺失的权限可能会导致您的智能体运行失败。为智能体身份授予这些权限，有助于确保其按预期正常运行。

如果系统检测到任何权限问题，权限对话框会显示一条出错提示。

  • 缺少角色：如果缺少必需的角色，系统会显示一个对话框，其中列出了详细的角色。在对话框中点击全部授予，即可通过一次操作自动向代理的身份授予所有必需的角色。如需在不授予角色的情况下预览或部署智能体，请点击仍然继续。
  • 已授予所有角色：如果已授予所有必需的角色，则不会显示权限对话框。
  • 未保存的智能体：未保存的智能体尚无身份。在您保存代理之前，系统不会显示权限对话框，并且预览标签页和部署选项处于停用状态。

所需的角色

权限对话框会自动授予以下角色列表：

  • roles/storage.objectViewer：如果代理使用上传的文件，则此参数为必需参数。必须针对代理文件所在的特定 Cloud Storage 存储桶（例如 {projectNumber}_{location}_agent_studio_files）授予此角色。
  • roles/mcp.toolUser：如果智能体使用 Agent Registry MCP 工具，则此字段为必填字段。
  • roles/agentregistry.viewer：如果代理使用 Agent Registry MCP 工具或子代理，则为必需项。
  • roles/iamconnectors.user：如果 Agent Registry MCP 工具指定了 authProviderName，则此字段为必填字段。
  • roles/aiplatform.viewer：如果智能体通过 Agent-to-Agent (A2A) 委托调用远程子智能体，则必须提供此信息。

在 Cloud de Confiance 控制台中手动管理角色

权限对话框会自动授予所需角色。不过，如果您想手动管理角色或需要排查权限问题，请按以下步骤操作：

  1. 复制代理的唯一身份主体。在 Agent Studio 画布标题中，点击代理名称旁边的下拉菜单，然后复制主账号字符串。

    主账号格式如以下示例所示：

    principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

  2. 在 Cloud de Confiance 控制台中，前往 IAM：

    转到 IAM

  3. 在主账号列表中搜索代理身份主账号。您可以使用主体字符串末尾的特定 REASONING_ENGINE_ID 进行搜索。如需获取代理身份主账号，您可以选择以下任一选项：

    • 如果代理身份主账号已列出，请点击代理身份旁边的 修改主账号。
    • 如果未列出代理身份主账号，请点击授予访问权限以将其添加为新的主账号。

  4. 为您的配置添加或修改所需角色，例如 roles/storage.objectViewer 或 roles/mcp.toolUser。

  5. 点击保存。

根据您的配置，您可能需要手动授予权限对话框不会自动处理的其他角色。例如，如果注册的 MCP 工具访问其他 Cloud de Confiance by S3NS 资源（例如查询 BigQuery 中的数据），您必须手动向代理的身份授予必要的角色，例如 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色。

通过 Agent Studio 部署智能体

创建并预览智能体后，您可以将其部署到正式版环境中。如需从 Agent Studio 部署智能体，请按以下步骤操作：

  1. 在代理列表页面中，点击要部署的代理。 系统会显示所选代理的“代理详情”页面。

  2. 点击部署，打开部署到 Agent Runtime 实例对话框。

    如果代理的身份缺少所需权限，系统会显示权限对话框并自动处理此操作。如果您需要手动管理权限，请参阅管理智能体身份权限和为智能体到智能体 (A2A) 委托授予访问权限。

  3. 在部署配置窗口中，配置以下选项：

    • 显示名称和说明：修改显示名称，并根据需要为代理添加说明。
    • 作为 A2A 部署：选中此复选框可将智能体部署为其他智能体可以重复使用的 Agent-to-Agent (A2A) 资源。对于独立应用，请勿勾选该复选框，以将代理打包为标准 ADK 应用。

  4. 从可用区域列表中选择一个部署区域，然后点击确定。

  5. 点击部署。

部署会创建新的运行时实例，最多可能需要五分钟才能完成。成功后，Agent Studio 画布的流程标签页中会显示一条消息。您的智能体现在已可用于生产用途，并且可以安全地与外部应用集成。

查看已部署的智能体

如需查看已部署的智能体，请执行以下操作：

  1. 在 Cloud de Confiance 控制台中，前往 Agent Platform 部署页面。

    前往“部署”页面

  2. 使用区域列表按部署区域进行过滤。

  3. 属于所选项目的已部署代理会显示在列表中。

  4. 点击指定代理的名称。系统会打开相应代理的指标页面。

  5. 选择试用区标签页，测试您的智能体。

  6. 在对话窗格中输入测试查询，验证代理是否成功运行。

如需详细了解代理的可用指标，请参阅查看已部署代理的指标。