创建智能体应用

本指南将介绍如何完成创建基本智能体应用的步骤，该应用可以回答用户提出的天气相关问题。

准备工作

请务必先完成设置说明，然后再按照本指南操作。

创建智能体应用

创建代理应用和根代理：

  1. 打开 CX Agent Studio 控制台。
  2. 选择您的项目。
  3. 点击创建代理或新建代理。
  4. 提供“天气应用”作为代理名称。
  5. 点击创建。如果您是首次为项目创建代理应用，则创建过程可能需要 1-2 分钟。 系统会显示智能体构建工具，并为您创建根智能体。

创建代理层次结构

此代理应用将使用三个代理：

  • 根代理，用于问候用户并委托给其他子代理。
  • 天气智能体，用于回答与天气相关的问题。
  • 向代理告别以结束对话。

根代理已创建，但您应更新此代理的设置：

  1. 点击根代理的标题栏。
  2. 您可以选择性地更改智能体的名称。
  3. 输入说明：“处理简单的问候语并委托给其他代理”。
  4. 点击保存，然后关闭设置面板。

创建天气代理：

  1. 点击根代理底部的 + 按钮。
  2. 点击添加新的分代理。
  3. 点击新代理的标题栏。
  4. 将名称更改为“天气代理”。
  5. 输入说明：“处理用户提出的任何与天气相关的问题”。
  6. 点击保存，然后关闭设置面板。

以类似方式，创建根代理的另一个分代理，名为“Farewell agent”，描述为“Handles user farewells and goodbyes”。

代理层次结构的屏幕截图

创建天气工具

工具用于将代理连接到外部系统或提供给代理的内嵌代码。 这样一来，智能体就可以与其他系统交互，以提取、更新、分析信息或为信息设置格式。

在此步骤中，您将创建一个天气工具，用于获取天气信息。 为了便于说明，本指南中使用的工具具有针对用户的模拟响应。 在实际的天气应用中，此工具会访问外部服务器以获取信息。

创建天气工具：

  1. 点击代理构建器右侧的工具按钮。
  2. 点击 + 为代理应用创建新工具。
  3. 点击 Python code（Python 代码）。

  4. 粘贴以下代码：

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. 点击创建。

现在，您需要将此工具添加到天气代理：

  1. 点击天气智能体标题栏中的 + 按钮。
  2. 点击添加工具。
  3. 选择天气工具。

创建智能体指令

每个代理都有一组指令，用于定义代理应执行的操作。

在提供引用代理的指令时，请使用 {@AGENT: Agent name} 语法。对于引用工具，请使用 {@TOOL: tool_name}。

为每个代理创建指令：

  1. 点击根代理的标题栏中的 + 按钮。
  2. 点击添加说明。

  3. 输入以下指令：

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. 点击创建。

  5. 以类似方式，为天气代理添加以下指令：

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. 以类似的方式，为告别代理添加以下指令：

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

测试代理

您的代理应用现已准备就绪，可以使用模拟器进行互动：

  1. 在控制台屏幕的左下角，点击预览代理栏以展开窗口（如果尚未展开）。
  2. 输入“hello”，然后按 Enter 键。 代理会使用通用问候语做出响应。
  3. 输入“纽约的天气怎么样？”，然后按 Enter 键。 代理会回答天气信息。
  4. 输入“goodbye”，然后按 Enter 键。 客服人员结束对话。

使用变量

变量用于存储和检索运行时对话数据。 这让智能体能够记住不同对话轮次之间的信息，从而实现更具情境感的互动。 对于此代理，您将创建一个用于捕获用户名的变量。

如需创建变量，请执行以下操作：

  1. 点击代理构建器右侧的“变量”按钮。
  2. 点击创建变量或 +。
  3. 输入“username”作为变量名称。
  4. 将类型保留为文本。
  5. 点击创建。

现在，您已定义变量，接下来需要定义一个工具，让代理能够更新该变量：

  1. 点击代理构建器右侧的工具按钮。
  2. 点击 + 为代理应用创建新工具。
  3. 点击 Python code（Python 代码）。

  4. 粘贴以下代码：

    from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name"""
  set_variable("username", username)

  5. 点击创建。

将此工具添加到根代理：

  1. 点击根代理的标题栏中的 + 按钮。
  2. 点击添加工具。
  3. 选择 update_username 工具。

在根代理说明中添加以下句子，该句子使用 {variable_name} 语法引用了变量：

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

您可以再次测试代理，以验证变量使用情况：

  1. 点击模拟器标题栏中的发起新对话。
  2. 输入“Hello, my name is Frank”。
  3. 输入“您的信息有多准确？”。

请注意，智能体现在会在每次回答时使用您的名字。 您还可以展开模拟器对话的步骤部分，在其中验证工具执行情况等。

控制如何结束会话

默认情况下，每个智能体都配置为使用 end_session system tool，不过，您可以通过创建明确的指令来提高会话结束方式的可靠性和控制力。

点击每个代理中工具旁边的 x，从根代理和天气代理中移除 end_session 工具。 这样可确保只有告别代理会结束会话。

将以下内容添加到告别智能体的指令中：

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

使用回调在会话结束时强制显示静态消息

回调提供了一种机制，可使用 Python 代码挂接到特定代理的执行流程中。借助它们，您可以在特定预定义的时间点观察、自定义甚至控制智能体的行为。

您可以利用各种回调类型，每种回调类型都在对话轮次的特定时间点执行。

在本教程中，请在结束会话时将静态消息附加到模型响应中：

  1. 点击告别代理的标题栏。
  2. 点击添加回调。
  3. 选择 After LLM。

  4. 输入以下代码：

    SURVEY_MESSAGE = "Click here to take our post call survey."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. 点击完成。

  6. 点击保存。

您可以再次测试代理，以验证会话结束行为：

  1. 点击模拟器标题栏中的发起新对话。
  2. 输入“Hello”。
  3. 输入“再见”。

请注意，代理现在会使用您附加的消息进行回复。

设置指令结构

为了改进代理行为，您可以采用自由格式的 XML 格式来构建所有代理指令，这种格式非常适合模型处理。针对每个代理执行以下操作：

  1. 打开代理的说明面板。
  2. 点击右上角的结构按钮。
  3. 点击保存。

部署

在获得可正常运行的代理后，您有多种部署选项。