跳到主要内容

第 1.6.2 节：把函数接口写成模型能稳定调用的工具契约

函数接口不能只停留在口头约定，还需要落实为字段、校验和失败处理。完成本节后，你应该能够把函数接口落成字段表、校验规则、错误处理和验收样例。

任务卡内容
本节任务把业务动作拆成工具名称、用途、输入、输出、错误和日志字段。
你会产出一张“工具函数契约表”。
使用场景查订单状态、查售后政策、创建客服工单、发起退款审批。
完成标准至少 3 个工具有明确输入来源、输出字段、错误状态和审计字段。

工具契约不是代码语法，它是团队共识。模型看到契约后知道什么时候申请工具；后端看到契约后知道要校验什么；前端看到契约后知道怎样展示结果；日志系统看到契约后知道要记录哪些字段。

一份合格的工具契约至少包含 6 类信息：

契约项要回答的问题客服例子
工具名称这个工具叫什么，是否只做一件事？query_order_status
使用条件什么用户请求下才应该申请它？用户要查询自己的订单或物流。
输入字段需要哪些字段，字段来自哪里？user_id 来自会话，order_id 来自用户选择。
输出字段工具返回什么结构化结果？订单状态、物流摘要、是否可售后。
错误状态失败时返回哪些可处理状态？未登录、无权限、无数据、超时。
日志字段复盘时需要记录什么？trace_id、tool_name、status、error_code。

工具契约越模糊，模型越容易误选工具，系统越难做权限和失败处理。

实现步骤或决策流程​

  1. 从第 1.6.1 节的判断表里挑出“需要工具”的动作。
  2. 给每个动作起一个动词明确的工具名，避免“customer_tool”这种万能入口。
  3. 写清输入字段，并标出字段来源：用户输入、会话系统、订单系统、知识库或系统生成。
  4. 写清输出字段，并说明哪些字段可以展示给用户。
  5. 写清错误状态，保证失败时模型不能自由编造。
  6. 写清日志字段，为第 1.6.4 节的审计表做准备。

可复制模板​


## 工具函数契约表

| 工具名称 | 业务动作 | 使用条件 | 输入字段与来源 | 输出字段 | 错误状态 | 日志字段 |
| --- | --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |  |

示例填写​

工具名称业务动作使用条件输入字段与来源输出字段错误状态日志字段
query_order_status查询订单状态用户询问自己的订单、物流或是否可售后user_id：会话；order_id：用户选择；trace_id：系统生成order_status、shipping_summary、after_sale_availableNOT_LOGIN、ORDER_NOT_FOUND、NO_PERMISSION、TIMEOUTtrace_id、user_id、tool_name、status、error_code
create_support_ticket创建客服工单用户确认要提交投诉、售后或咨询工单user_id：会话；issue_summary：Agent 总结后用户确认；order_id：可选ticket_id、ticket_status、next_stepMISSING_CONFIRMATION、NO_PERMISSION、DUPLICATE_REQUEST、TIMEOUTtrace_id、user_id、ticket_id、tool_name、status
create_refund_review发起退款审批用户申请退款且规则需要人工审核user_id：会话；order_id：订单系统；refund_reason：用户确认review_id、review_status、required_materialsNO_PERMISSION、POLICY_NOT_MATCHED、DUPLICATE_REVIEWtrace_id、user_id、order_id、review_id、status

新手自查清单​

  • 我有没有把一个万能工具拆成多个单一职责工具？
  • 每个输入字段有没有写清来源，而不是默认相信用户原话？
  • 输出字段有没有区分“系统内部使用”和“可以展示给用户”？
  • 错误状态是否能被系统处理，而不是只返回“失败”？
  • 日志字段是否能串起用户请求、工具调用和最终回答？

本节交付物与面试讲法​

本节交付物是一张“工具函数契约表”。合格标准是至少写出 3 个工具，并覆盖输入、输出、错误、日志和使用条件。

面试时可以这样讲：

我会先从业务动作判断表里挑出需要工具的动作，再把每个动作写成单一职责工具。工具契约会明确字段来源，例如 user_id 只能来自会话，order_id 需要校验归属；工具返回也必须是结构化状态，失败时返回错误码，避免模型编造业务结果。

继续学习​