tool-calling

工具调用设计：schema、幂等、超时、错误处理和人工审批

补充说明

工具调用（function calling）让模型输出结构化参数，由应用执行真实操作。模型只负责“选工具、填参数”，不负责鉴权、事务和副作用控制；这些必须在应用层完成。工具设计的好坏，直接影响 Agent 的可靠性、成本和安全性。

一个可用的工具要有：清晰的名称和描述、严格的参数 schema、明确的返回值、错误语义、超时/重试策略、幂等键和高风险操作审批。工具越少越聚焦，模型越不容易选错；工具太多会撑爆上下文并增加误调用。

常用示例

{
  "type": "function",
  "function": {
    "name": "get_order_status",
    "description": "按订单号查询物流状态；只读，不会修改订单。",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {"type": "string", "pattern": "^[A-Z0-9-]{6,32}$"}
      },
      "required": ["order_id"],
      "additionalProperties": false
    }
  }
}

# 处理模型返回的 tool_calls
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)
for call in resp.choices[0].message.tool_calls or []:
    name = call.function.name
    args = json.loads(call.function.arguments)
    validate_schema(name, args)          # 参数校验
    result = execute_tool(name, args)    # 超时、重试、幂等
    messages.append({
        "role": "tool", "tool_call_id": call.id,
        "content": json.dumps(result, ensure_ascii=False),
    })

# 高风险工具：人工审批 + 幂等键
if tool_name in {"send_email", "delete_record", "run_shell"}:
    approval = request_approval(user, tool_name, args)
    if not approval.approved:
        return {"error": "approval_denied"}
result = execute_idempotent(tool_name, args, idempotency_key=call.id)

易错点与排错

• 描述含糊：模型不知道何时用、参数含义是什么；描述要写清用途、边界和返回。
• schema 太松：additionalProperties 未关闭、参数无类型/范围；模型会传错或注入额外字段。
• 直接信任参数：工具参数来自模型，可能被注入；服务端必须重新校验和鉴权。
• 没有超时：工具卡住会拖死整个 Agent；设置超时、重试上限和熔断。
• 重试导致重复副作用：发邮件/扣款等操作要用幂等键，重试前先查状态。
• 错误信息直接回传：堆栈/内部路径泄露给模型和用户；返回结构化错误码和安全消息。
• 工具太多：上下文膨胀、选择困难；按场景分组或做工具路由。
• 工具输出被当指令：工具返回的网页/文档可能含注入；按不可信数据处理。
• 并行调用顺序问题：有依赖的工具不要并行；明确先后和失败回滚。

相关命令

• openai-agents-sdk — Agent SDK 的工具调用。
• langgraph — 有状态工作流与工具节点。
• pydantic-ai — 类型安全的 Agent 工具。
• mcp-server — 用 MCP 暴露工具。
• mcp — MCP 协议与客户端。

参考链接

• OpenAI Function Calling
• Anthropic Tool Use
• JSON Schema

读完自测

合上页面，先回答，再展开对照。

1. 模型在工具调用中负责什么？不负责什么？
2. 为什么高风险工具需要幂等键？
3. 工具返回的内容为什么要按不可信数据处理？