工具调用是 Agent 与真实系统的边界。工具越多,越要把名称、参数、权限、超时和错误编码成稳定契约,而不是依赖提示词中的自然语言约定。
核心概念
将工具分为只读、可写和高风险三类。只读工具可自动执行;可写工具要有幂等键;高风险工具必须返回待确认状态。错误应区分输入错误、权限错误、依赖暂时不可用和业务拒绝。
可运行示例
from dataclasses import dataclass
@dataclass(frozen=True)
class SearchArgs:
query: str
limit: int = 10
def validate(args: SearchArgs) -> None:
if not args.query or len(args.query) > 120:
raise ValueError('invalid query')
if not 1 <= args.limit <= 50:
raise ValueError('invalid limit')
def tool_result(ok: bool, code: str, data: dict | None = None) -> dict:
return {'ok': ok, 'code': code, 'data': data}
操作步骤
- 为每个工具写一份版本化 schema,明确必填字段和最大长度。
- 将 schema 校验放在模型输出解析之后、实际调用之前。
- 为写操作计算幂等键,重复请求返回第一次结果而不重复副作用。
- 把工具错误映射成模型可理解的短代码,同时把详细堆栈留在受限日志。
适用场景
适用于 CRM 查询、库存读取、内部知识搜索和需要审批的变更流程。
常见问题
schema 改动如何兼容? 新增可选字段,重大变更使用新工具名或版本。
工具超时怎么办? 返回明确的 temporary_unavailable,限制重试次数。
是否要把所有错误交给模型? 只返回必要信息,权限和内部路径不可泄露。
官方参考
OpenAI Function Calling;OpenAI Structured Outputs。
最后核对日期:2026-11-16。版本、接口和安全边界以链接的官方资料为准;本文不虚构性能或费用结论。
