用户模拟¶

Supported in ADKPython v1.18.0

在评估对话式智能体时，使用固定的用户提示集并不总是可行的，因为对话可能会以意想不到的方式进行。例如，如果智能体需要用户提供两个值来执行任务，它可能会一次请求一个值或一次请求两个值。为了解决这个问题，ADK 可以使用生成式 AI 模型动态生成用户提示。

要使用此功能，你必须指定一个 ConversationScenario，它规定了用户在与智能体对话中的目标。你还可以指定你希望用户遵守的用户人物设定（User Persona）。

一个 ConversationScenario（对话场景）由以下组件组成：

starting_prompt：用户启动与智能体对话时应使用的固定初始提示语。
conversation_plan：用户必须实现的高级目标指南。
user_persona：用户特性的定义，如技术专长或语言风格。

以下是一个针对 hello_world 智能体的对话场景示例：

{
  "starting_prompt": "What can you do for me?", // 用户的起始提示
  "conversation_plan": "要求智能体掷一个 20 面的骰子。得到结果后，要求智能体检查它是否为质数。" // 对话计划
}

LLM 使用 conversation_plan 结合对话历史来动态生成用户提示。

你还可以通过以下方式指定预定义的 user_persona（用户人物设定）：

{
  "starting_prompt": "What can you do for me?",
  "conversation_plan": "要求智能体掷一个 20 面的骰子。得到结果后，要求智能体检查它是否为质数。",
  "user_persona": "NOVICE"
}

虽然对话计划规定了必须完成的任务，但人物设定（Persona）则规定了模型如何表达其查询以及如何对智能体的响应做出反应。

在 Colab 中尝试

在模拟用户对话以动态评估 ADK 智能体的交互式笔记本中亲自测试整个工作流。你将定义一个对话场景，进行“演练”以检查对话，然后执行全面评估以对智能体的响应进行评分。

用户人物设定 (User Personas)¶

用户人物设定（User Persona）是模拟用户在对话中扮演的角色。它由一组行为（behaviors）定义，这些行为规定了用户如何与智能体交互，例如他们的沟通风格、提供信息的方式以及对错误的反应。

一个 UserPersona 对象包含以下字段：

id：该人物设定的唯一标识符。
description：关于用户是谁以及他们如何与智能体交互的高层级描述。
behaviors：定义特定特性的 UserBehavior 对象列表。

每个 UserBehavior（用户行为）包括：

name：行为的名称。
description：预期行为的摘要。
behavior_instructions：给模拟用户（LLM）的关于如何行动的具体指令。
violation_rubrics：由评估器用来确定用户是否遵循了该行为。如果其中任何评分标准被满足，评估器应判定该行为未被遵循。

预置人物设定¶

ADK 提供了一组由常见行为组成的预置人物设定。下表总结了每个人物设定的行为：

行为	EXPERT（专家）人物设定	NOVICE（新手）人物设定	EVALUATOR（评估员）人物设定
推进 (Advance)	细节导向（主动提供细节）	目标导向（等待被要求提供细节）	细节导向
回答 (Answer)	仅限相关问题	回答所有问题	仅限相关问题
纠正智能体错误	是	否	否
排查智能体错误	一次	从不	从不
语调 (Tone)	专业	对话式	对话式

示例：通过对话场景评估 `hello_world` 智能体¶

要将包含对话场景的评估案例添加到新的或现有的 EvalSet 中，你需要首先创建一份对话场景列表来测试智能体。

尝试将以下内容保存到 contributing/samples/core/hello_world/conversation_scenarios.json：

{
  "scenarios": [
    {
      "starting_prompt": "What can you do for me?", // 起始提示
      "conversation_plan": "要求智能体掷一个 20 面的骰子。得到结果后，要求智能体检查它是否为质数。", // 对话计划：掷骰子并检查质数
      "user_persona": "NOVICE" // 用户人物设定：新手
    },
    {
      "starting_prompt": "Hi, I'm running a tabletop RPG in which prime numbers are bad!", // 起始提示
      "conversation_plan": "说明你不在乎具体数值，只想让智能体告诉你点数是好是坏。一旦智能体同意，要求它掷一个 6 面的骰子。最后，要求智能体用 2 个 20 面的骰子做同样的操作。", // 对话计划：复杂逻辑指示
      "user_persona": "EXPERT" // 用户人物设定：专家
    }
  ]
}

你还需要一个包含评估期间所用信息的会话输入文件。尝试将以下内容保存到 contributing/samples/core/hello_world/session_input.json：

{
  "app_name": "hello_world", // 应用程序名称
  "user_id": "user" // 用户 ID
}

然后，你可以将对话场景添加到 EvalSet 中：

# (可选) 创建一个新的 EvalSet
adk eval_set create \
  contributing/samples/core/hello_world \
  eval_set_with_scenarios

# 将对话场景作为新的评估案例添加到 EvalSet 中
adk eval_set add_eval_case \
  contributing/samples/core/hello_world \
  eval_set_with_scenarios \
  --scenarios_file contributing/samples/core/hello_world/conversation_scenarios.json \
  --session_input_file contributing/samples/core/hello_world/session_input.json

默认情况下，ADK 使用需要指定智能体预期响应的指标运行评估。由于动态对话场景并非如此，我们将使用一个 EvalConfig 以及一些替代支持的指标。

尝试将以下内容保存到 contributing/samples/core/hello_world/eval_config.json：

{
  "criteria": {
    "hallucinations_v1": {
      "threshold": 0.5, // 阈值
      "evaluate_intermediate_nl_responses": true // 评估中间自然语言响应
    },
    "safety_v1": {
      "threshold": 0.8 // 阈值
    }
  }
}

最后，你可以使用 adk eval 命令运行评估：

adk eval \
    contributing/samples/core/hello_world \
    --config_file_path contributing/samples/core/hello_world/eval_config.json \
    eval_set_with_scenarios \
    --print_detailed_results

用户模拟器配置¶

你可以覆盖默认的用户模拟器配置，以更改模型、内部模型行为以及用户与智能体交互的最大次数。下面的 EvalConfig 显示了默认的用户模拟器配置：

{
  "criteria": {
    # 与之前相同
  },
  "user_simulator_config": {
    "model": "gemini-flash-latest",
    "model_configuration": {
      "thinking_config": {
        "include_thoughts": true, // 是否包含思考过程
        "thinking_budget": 10240 // 思考预算
      }
    },
    "max_allowed_invocations": 20 // 允许的最大调用次数
  }
}

model：支撑用户模拟器的模型。
model_configuration：一个控制模型行为的 GenerateContentConfig。
max_allowed_invocations：在对话被强制终止前允许的最大用户-智能体交互次数。这应该设置为大于 EvalSet 中最长的合理用户-智能体交互次数。
custom_instructions：（可选）覆盖用户模拟器的默认指令。指令字符串必须包含以下使用 Jinja 语法的格式占位符（不要提前替换值！）：
- {{ stop_signal }}：当用户模拟器判定对话结束时要生成的文本。
- {{ conversation_plan }}：用户模拟器必须遵循的对话总体计划。
- {{ conversation_history }}：至今为止用户和智能体之间的对话记录。
- 你还可以通过 {{ persona }} 占位符访问 UserPersona 对象。

自定义人物设定¶

你可以通过在 ConversationScenario 中提供一个 UserPersona 对象来定义自己的自定义人物设定。

自定义人物设定定义示例：

{
  "starting_prompt": "I need help with my account.", // 起始提示
  "conversation_plan": "要求智能体重置你的密码。", // 对话计划
  "user_persona": {
    "id": "IMPATIENT_USER", // 标识符：没有耐心的用户
    "description": "A user who is in a rush and gets easily frustrated.", // 描述：赶时间且容易感到沮丧的用户
    "behaviors": [
      {
        "name": "Short responses", // 行为：简短回应
        "description": "The user should provide very short, sometimes incomplete responses.", // 描述：用户应提供非常简短、有时不完整的回应
        "behavior_instructions": [
            "将你的回应保持在 10 个词以内。", // 回应保持在 10 个词以内
            "省略礼貌用语。" // 省略礼貌用语
        ],
        "violation_rubrics": [
            "用户回应超过 10 个词。", // 违规标准：回应超过 10 个词
            "用户回应过于礼貌。" // 违规标准：回应过于礼貌
        ]
      }
    ]
  }
}

通过用户模拟生成评估案例¶

手动编写评估案例可能耗时且无法覆盖所有可能的故障模式。ADK 提供了一条命令，可以使用 Agent Platform Eval SDK 根据智能体的定义自动生成多样且逼真的对话场景。

前置条件：Agent Platform 凭据

生成评估案例使用 Vertex Gen AI 评估服务 API。你必须拥有一个已启用 Agent Platform API 的 Google Cloud 项目，并在环境中配置有效的应用程序默认凭据 (ADC)。

命令语法¶

adk eval_set generate_eval_cases \
    <AGENT_MODULE_FILE_PATH> \
    <EVAL_SET_ID> \
    --user_simulation_config_file=<PATH_TO_CONFIG_FILE>

配置文件格式¶

--user_simulation_config_file 需要一个匹配 ConversationGenerationConfig schema 的 JSON 文件：

{
  "count": 5,
  "generation_instruction": "生成用户要求在不同条件下控制家居设备的场景。",
  "environment_context": "可用设备：device_1（灯光）、device_2（恒温器）。",
  "model_name": "gemini-flash-latest"
}

配置字段¶

count（必填）：要生成的对话场景数量。
generation_instruction（可选）：引导要测试的特定场景类型或目标的自然语言提示。
environment_context（可选）：描述智能体工具可访问的后端数据或状态的上下文。这有助于生成器创建基于真实数据的查询（例如有效的设备 ID）。
model_name（必填）：用于生成的 Gemini 模型（例如 gemini-flash-latest）。