[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Human-in-the-loop, Confirmation Tool

Ask User Tool

一句话定义

Ask User Tool 是一种特殊工具，让 Agent 能够主动向用户提问以获取缺失信息。Agent 发现参数不足时，不是猜测，而是直接问用户。

核心原理

使用场景

用户: "帮我查一下最近的销售数据"
Agent: 缺少时间范围 → 调用 ask_user("请问查哪个时间范围？")
用户: "最近一周"
Agent: 调用 query_database(date_range="last_week")

Python 实现

ask_user_tool = Tool(
    name="ask_user",
    description="向用户提问以获取缺失信息。当你不确定用户的意图或缺少必要参数时使用。",
    parameters={
        "type": "object",
        "properties": {
            "question": {
                "type": "string",
                "description": "要问用户的问题"
            },
            "options": {
                "type": "array",
                "items": {"type": "string"},
                "description": "可选的选项（让用户选择而不是自由输入）"
            }
        },
        "required": ["question"]
    },
    handler=ask_user_handler,
)

前端渲染

function AskUserCard({ question, options }) {
  return (
    <div className="ask-user-card">
      <p>{question}</p>
      {options ? (
        <div className="options">
          {options.map(opt => (
            <button key={opt} onClick={() => respond(opt)}>{opt}</button>
          ))}
        </div>
      ) : (
        <form onSubmit={handleSubmit}>
          <input type="text" />
          <button type="submit">发送</button>
        </form>
      )}
    </div>
  );
}

常见坑

1. 不提供选项: 用户需要自由输入，体验差
2. 问题太模糊: “请提供更多信息”不知道要什么
3. 不做超时: 用户不回答 Agent 永远等待

参考资料

• Human-in-the-loop
• Confirmation Tool