Agent 工具调用 Prompt：把能不能调用交给规则

# 错误示范：参数用途模糊，缺少调用条件
tools:
  - name: get_order
    description: 查询订单信息
    parameters:
      order_id:
        type: string
        description: 订单编号
      customer_id:
        type: string
        description: 客户 ID

# 正确做法：明确参数来源和调用条件
tools:
  - name: get_order
    description: |
      查询单笔订单的详细信息。仅在用户明确提及某笔订单时使用。
    parameters:
      order_id:
        type: string
        description: |
          订单编号，必须来自用户明确提供的编号或对话上下文中已确认的订单号。
          禁止自行构造或猜测订单编号。
      customer_id:
        type: string
        description: |
          客户 ID，仅用于服务端权限校验，由系统自动注入。
          Agent 不得主动传入此参数。
    required_conditions:
      - 用户必须提供明确的订单编号，或对话上下文中已有确认的订单号
      - 如果用户只问「我的订单」但未指定具体编号，先追问而非调用
    forbidden:
      - 禁止使用 customer_id 批量查询用户所有订单
      - 禁止在用户未提及订单时主动调用此工具

operation_levels:
  read:
    description: 查询、搜索、获取信息
    confirmation: 不需要确认，可直接调用
    examples: [search_orders, get_user_info, list_tasks]
  
  write:
    description: 创建、更新、删除资源
    confirmation: |
      调用前必须向用户确认以下信息：
      1. 列出将要执行的操作和影响的资源
      2. 列出从用户输入中推断出的参数值，请用户确认
      3. 明确标注哪些字段是推断的、哪些是用户原文
    examples: [create_task, update_order, delete_comment]
  
  critical:
    description: 发送消息、支付、批量操作、不可逆操作
    confirmation: |
      必须逐字展示将要发送的内容或执行的 SQL，
      等待用户明确回复「确认」后才能调用。
    examples: [send_email, process_payment, bulk_delete]

failure_handling:
  general_rules:
    - 工具调用失败时，不得编造、猜测或使用训练数据中的信息来替代工具返回结果
    - 必须明确告知用户工具调用未成功，并说明已知的原因
    - 如果是临时性错误（超时、网络），可以建议用户稍后重试
    - 如果是参数错误，分析可能的原因并请求用户补充信息
  
  response_template: |
      [工具名称] 调用未能成功。
      原因：[从错误信息中提取的具体原因，如「请求超时」「参数格式错误」]
      建议：[可操作的下一步，如「请检查订单号是否正确」「建议稍后重试」]
    
  escalation:
    - 同一工具连续失败 2 次后，停止重试并建议用户联系人工客服
    - 失败事件必须记录：工具名称、输入参数、错误类型、时间戳

# ❌ 模糊：模型不知道什么时候该用、什么时候不该用
- name: search_users
  description: 搜索用户
  parameters:
    query:
      type: string
 
# ✅ 精确：边界清晰，模型能做正确判断
- name: search_users
  description: |
    根据姓名或邮箱搜索平台注册用户。
    仅用于用户主动要求查找特定用户时使用。
    禁止用于批量导出或遍历用户列表。
  parameters:
    query:
      type: string
      description: |
        搜索关键词，必须是用户明确提供的姓名或邮箱片段。
        最小长度 2 个字符，禁止传空字符串或通配符。
    limit:
      type: integer
      default: 10
      maximum: 20
      description: 返回结果数量上限，不可超过 20。

# ❌ 危险：模型收到「帮我退款」就直接调用了
- name: process_refund
  description: 处理退款
  parameters:
    order_id:
      type: string
    amount:
      type: number
 
# ✅ 安全：工具描述里内嵌确认要求
- name: process_refund
  description: |
    处理订单退款，属于 critical 级别操作。
    调用前必须：
    1. 向用户展示退款金额和受影响的订单
    2. 获得用户明确的「确认退款」回复
    3. 确认退款原因已记录
    禁止在用户未明确确认的情况下调用。
  parameters:
    order_id:
      type: string
      description: 必须是用户明确提及的订单编号
    amount:
      type: number
      description: 退款金额，不得超过订单实付金额
    reason:
      type: string
      enum: [商品问题, 物流问题, 用户主动取消, 其他]
      description: 必须从用户描述中推断或追问得到

# ❌ 没有失败处理，模型可能编造结果
- name: check_inventory
  description: 查询库存
 
# ✅ 工具描述里包含失败行为约束
- name: check_inventory
  description: |
    查询指定 SKU 的实时库存数量。
    
    调用约束：
    - sku_id 必须来自对话上下文中已确认的商品信息
    - 如果工具返回错误或超时，必须如实告知用户「库存查询暂时不可用」
    - 绝对禁止编造库存数字或引用历史数据代替实时查询结果
    - 失败时建议用户稍后重试或联系客服

# ❌ 工具规则散落在 Prompt 各处，模型容易遗漏
system: |
  你是一个客服助手。
  你可以查询订单、创建工单、发送邮件。
  调用工具时要注意参数正确。
  如果失败了告诉用户。
  重要操作要确认。
 
# ✅ 结构化分段，规则优先级清晰
system: |
  ## 身份与权限
  你是客服助手，可访问以下工具：订单查询、工单创建、邮件发送。
  你的权限等同于普通客服角色，无法执行管理员操作。
  
  ## 工具调用规则
  按以下分级执行确认策略：
  - read（查询）：直接调用，无需确认
  - write（创建/更新）：展示参数后请用户确认
  - critical（发送/删除/支付）：逐字展示内容，等待用户回复「确认」
  
  ## 参数约束
  - 所有 ID 类参数必须来自用户输入或对话上下文，禁止自行构造
  - 枚举类参数必须使用定义中的值，禁止自由发挥
  - 参数缺失时先追问，不要用默认值填充业务字段
  
  ## 失败处理
  - 工具失败时如实告知用户，禁止编造结果
  - 记录失败的工具名、参数、错误类型
  - 连续失败 2 次后建议转人工