用户模拟¶

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": "Ask the agent to roll a 20-sided die. After you get the result, ask the agent to check if it is prime." // 对话计划
}

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

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

{
  "starting_prompt": "What can you do for me?",
  "conversation_plan": "Ask the agent to roll a 20-sided die. After you get the result, ask the agent to check if it is prime.",
  "user_persona": "NOVICE"
}

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

在 Colab 中尝试

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

示例：使用对话场景评估 `hello_world` 智能体¶

用户人物设定 (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` 智能体¶

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

{
  "scenarios": [
    {
      "starting_prompt": "What can you do for me?", // 起始提示
      "conversation_plan": "Ask the agent to roll a 20-sided die. After you get the result, ask the agent to check if it is prime.", // 对话计划：掷骰子并检查质数
      "user_persona": "NOVICE" // 用户人物设定：新手
    },
    {
      "starting_prompt": "Hi, I'm running a tabletop RPG in which prime numbers are bad!", // 起始提示
      "conversation_plan": "Say that you don't care about the value; you just want the agent to tell you if a roll is good or bad. Once the agent agrees, ask it to roll a 6-sided die. Finally, ask the agent to do the same with 2 20-sided dice.", // 对话计划：复杂逻辑指示
      "user_persona": "EXPERT" // 用户人物设定：专家
    }
  ]
}

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

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

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

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

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

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

尝试将以下内容保存到 contributing/samples/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/hello_world \
    --config_file_path contributing/samples/hello_world/eval_config.json \
    eval_set_with_scenarios \
    --print_detailed_results

用户模拟器配置¶

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

{
  "criteria": {
    # same as before // 与之前相同
  },
  "user_simulator_config": {
    "model": "gemini-2.5-flash", // 用户模拟器使用的模型
    "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": "Ask the agent to reset your password.", // 对话计划
  "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": [
            "Keep your responses under 10 words.", // 回应保持在 10 个词以内
            "Omit polite phrases." // 省略礼貌用语
        ],
        "violation_rubrics": [
            "The user response is over 10 words.", // 违规标准：回应超过 10 个词
            "The user response is overly polite." // 违规标准：回应过于礼貌
        ]
      }
    ]
  }
}

用户模拟¶

示例：使用对话场景评估 hello_world 智能体¶

用户人物设定 (User Personas)¶

预置人物设定¶

示例：使用对话场景评估 hello_world 智能体¶

用户模拟器配置¶

自定义人物设定¶

示例：使用对话场景评估 `hello_world` 智能体¶

示例：使用对话场景评估 `hello_world` 智能体¶