把 Agent 接进业务:工具调用的错误处理
工具调用出错时的处理方式,决定了 Agent 是「优雅降级」还是「彻底卡死」。一个只在成功路径上跑通的工具链,接到生产上第一个带异常的接口就会崩。
工具要返回结构化的失败
工具执行失败时,应该返回一个结构化的错误结果给模型({"error": "..."}),而不是抛异常中断整个请求。让模型自己决定是重试还是换条路。
文本透传是最简单的路径,工具调用才是检验一个网关成色的地方。
因为工具调用涉及结构化参数的生成、解析、聚合和回传,任何一环处理得不严谨,模型就会收到一段语法错误的 JSON,然后开始胡说八道。
工具描述要写清楚边界
description 里应该写清楚这个工具什么时候该用、什么时候不该用、参数含义、返回格式。模型对工具的判断力,取决于你描述得有多清楚。
网关在转换时应该把这类工具补齐成合法的 JSON Schema,并明确 strict = false。
否则模型收到的工具描述是残缺的,生成的参数结构也就不可靠。
网关侧还有一道 observe / block 防线
工具调用的识别、记录与放行应该分层:默认观察不执行,明确配置的才放行。这样即使上游被诱导输出恶意调用,最坏结果也只是「没执行」。
更安全的默认是「观察」:把工具调用识别出来、记录下来、但不放行;只有明确配置为放行的工具才真正执行。
这样即使上游模型被诱导输出恶意工具调用,最坏结果也只是「没执行」,而不是「被执行了」。
Agent 的额度要单独设
Agent 循环里没有最大轮数,加上没有 Key 级额度上限,一次跑飞就能吃掉整天预算。这两道闸门都要有。
如果没有 Key 级限流,一个写错循环的脚本就能把共享池子的额度全部吃掉,其他用户跟着受影响。
实现上,调用明细按 (request_id, usage_id) 做唯一约束,避免结算重试导致重复落库。
实操:单轮工具调用的最小闭环,先跑通再加 Agent 框架。
把工具失败也走一遍 return 分支,你会立刻发现设计漏洞。
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["GATEWAY_API_KEY"],
base_url="https://aiminis.info/v1")
TOOLS = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
messages = [{"role": "user", "content": "杭州今天天气怎么样?"}]
resp = client.chat.completions.create(
model="gpt-6-sol", messages=messages, tools=TOOLS,
)
msg = resp.choices[0].message
if msg.tool_calls:
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = my_weather_func(args["city"]) # 你的业务逻辑
messages.append(msg) # 模型发出的调用
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result, ensure_ascii=False),
})
final = client.chat.completions.create(
model="gpt-6-sol", messages=messages, tools=TOOLS,
)
print(final.choices[0].message.content)
几个容易踩的坑
- 自定义工具没写
properties,模型收到的工具描述是残缺的。 - 工具结果和普通文本混在同一条消息里时,按「一轮只有一个工具」来解析。
- 把工具的原始参数写进请求日志,日志成了数据泄露源。
- 在流式下把分片参数直接拼成字符串当 JSON 解析,遇到被转义的引号就炸。
小结
把配置项和凭据都外置,是成本最低、收益最持久的一个工程习惯。
文中的配置和示例都能在 https://aiminis.info/ 直接跑一遍,接入文档在 https://aiminis.info/docs/api-integration。
- 点赞
- 收藏
- 关注作者
评论(0)