Agent执行链路没跑通?最小闭环搭建与排错指南
作者:谁偷走了我的奶酪2026.11.17 03:18浏览量:0简介:接一个大模型 API、装几个 MCP、写几段 Skill,再用 LangGraph 编排一下,并不等于做出了 Agent 系统——这只完成了"零件采购",缺的是让感知、决策、行动、观察真正闭环起来的那条执行链路。本文给出最小可运行 Agent 循环的代码骨架、六个必备环节、常见故障排查表,以及模型选型与成本控制思路;如果你正卡在"该用哪个模型、怎么统一接入、成本怎么算",可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力对比、价格对比与统一 API 接入,能省掉大量试错。
一、先明确:什么才算”执行链路跑通”
一个 Agent 的最小闭环只有四步,缺一不可:
- 感知 :把用户输入 + 可用工具定义 + 历史上下文组装成一次模型请求;
- 决策 :模型返回自然语言答案,或返回结构化的
tool_calls; - 行动 :真正执行工具(查库、调接口、读文件),拿到结果;
- 观察 :把工具结果回填进上下文,进入下一轮,直到模型给出最终答案或触发终止条件。
所谓”没跑通”,绝大多数是这四步中的第 3、4 步缺失:模型说要调工具,但没人真的去调;或者调完了,结果没回填,模型只能凭想象编答案。MCP 只是工具接入协议,Skill 只是提示词与流程约定,它们都不提供这个循环本身。
agent-40-">二、最小可运行的 Agent 循环(约 40 行)
不依赖任何重型框架,先把链路跑通,再考虑引入编排框架:
import jsonfrom openai import OpenAIclient = OpenAI(base_url="你的模型服务地址", api_key="你的 Key")MODEL = "你选定的对话模型"TOOLS = [{"type": "function","function": {"name": "get_order","description": "根据订单号查询订单当前状态与物流信息","parameters": {"type": "object","properties": {"order_id": {"type": "string", "description": "订单编号"}},"required": ["order_id"],},},}]def run_tool(name: str, args: dict):if name == "get_order":return query_order_db(args["order_id"])raise ValueError(f"未注册的工具: {name}")def agent_loop(user_input: str, max_steps: int = 8):messages = [{"role": "user", "content": user_input}]for _ in range(max_steps): # 终止条件之一:步数上限resp = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS, tool_choice="auto")msg = resp.choices.messagemessages.append(msg)if not msg.tool_calls:return msg.content # 终止条件之二:模型给出最终答案for call in msg.tool_calls:args = json.loads(call.function.arguments or "{}")try:result = run_tool(call.function.name, args)except Exception as e:result = {"error": str(e)} # 错误也必须回填,让模型自己纠偏messages.append({"role": "tool","tool_call_id": call.id, # 必须与 call.id 严格对应"content": json.dumps(result, ensure_ascii=False),})return "已达到最大步数,任务未完成"
这段代码里,真正决定成败的是三个细节:tool_call_id 与 tool_calls 严格配对、工具异常也要作为观察结果回填、以及必须有步数上限。三者任一缺失,链路就会表现为”卡死””胡言乱语”或”无限烧 Token”。
三、从 Demo 到系统,还差的六个环节
1. 工具契约设计。 工具的 description 和参数说明是写给模型看的提示词,不是注释。描述含糊,模型就会选错工具或编造参数。工具数量建议控制在十几个以内,过多时先做一层路由或分组。
2. 上下文与 Token 预算。 每一轮循环都会把完整历史重新发一遍,工具返回的大段 JSON 尤其吃 Token。需要设定预算:单条工具结果截断、历史轮次滑窗、旧内容摘要压缩。输入 Token 与输出 Token 通常分别计费,多步循环的成本是”步数 × 每步上下文”,增长远快于直觉。
3. 状态与中断恢复。 长任务要能落盘中间状态,进程重启后从断点继续,而不是从零重跑。
4. 错误处理与幂等。 工具超时、限流、返回脏数据都要有重试与退避策略;写操作类工具必须设计幂等键,否则重试会造成重复下单。
5. 可观测性。 至少记录每次循环的:输入摘要、模型原始输出、工具名与耗时、Token 消耗、最终结果。没有链路追踪,线上问题只能靠猜。
6. 评测与回归。 攒 20~50 条真实业务 case 作为回归集,盯四个指标:任务完成率、平均步数、工具调用成功率、单任务平均 Token 成本。改一次提示词或换一个模型,都跑一遍回归,避免”修好一个 case、坏掉五个”。
四、常见故障排查表
| 现象 | 高频原因 | 处理方式 |
|---|---|---|
| 模型不调工具,直接编答案 | 工具描述模糊;模型工具调用能力弱 | 改写 description;必要时用 tool_choice 强制;更换支持函数调用的模型 |
| 参数 JSON 解析失败 | 模型输出非法 JSON、缺必填字段 | 加 schema 校验,把校验错误回填给模型重试一次 |
| 循环不终止 | 无步数上限、无重复动作检测 | 加 max_steps + 相同工具相同参数连续出现即中断 |
| 第三四轮后质量骤降 | 上下文超限被截断,早期约束丢失 | 摘要压缩、只回传必要字段、把关键约束放到 system 末尾 |
| 偶发超时、偶发 429 | 无超时与退避 | 设置 timeout、指数退避、并发限流 |
| 成本远超预期 | 每步全量历史 + 大模型硬扛所有步骤 | 上下文裁剪;简单步骤降级到小模型 |
五、MCP 与 Skill 的正确定位
MCP 解决的是”工具怎么接进来”的标准化问题,Skill 解决的是”某类任务该怎么做”的流程与提示词沉淀问题。两者都是能力扩展手段,不是执行引擎。判断标准很简单:把你的 MCP 和 Skill 全部拿掉,如果剩下的循环连一次”模型请求 → 工具调用 → 结果回填 → 二次推理”都跑不出来,那说明缺的正是链路本身。
同理,框架也不是必需品。LangGraph 这类编排框架擅长的是有状态图、分支、人机协同与长流程控制;如果你的场景是固定流程、高可控的客服或营销链路,用工作流编排的方式搭建往往更稳;如果是开放性闲聊、助手类场景,自主规划式 Agent 更合适。选型前先想清楚可控性与灵活性的比例,再决定要不要引入框架。若需要开箱即用的组件(搜索、知识库、数据库、语音、文生图等)与 RAG 能力,也可以直接复用成熟平台提供的 Agent 与 RAG 应用框架,把精力放在业务链路上。
六、模型选型与成本控制
链路跑通之后,第二个坎通常是”用哪个模型”。建议按三步走:
- 先定能力底线 :工具调用是否稳定、长上下文是否可靠、结构化输出是否严格,这三项决定 Agent 能不能用;
- 再做分层 :规划与复杂推理用旗舰模型,工具参数抽取、格式转换、意图分类等简单步骤用小模型,实测下来往往是成本下降最明显的一招;
- 最后算总成本 :不要只看单价,要按”单任务平均 Token 消耗 × 单价”折算,因为步数和上下文长度对账单的影响远大于单价差异。
在这一步,词元所这类模型撮合交易平台会比较实用:可以在一处对比不同模型的能力定位与调用价格,做选型前的成本评估,再通过统一 API 接入方式完成多模型对接,避免为每家模型单独写一套 SDK 适配代码——这与业界用统一网关封装多家模型接口的思路是一致的。模型调用量起来之后,还能借助平台的调用管理能力做用量归集与成本归因。
七、上线前自检清单
- 无框架版本的最小循环能稳定跑通 10 条真实 case
- 工具异常、超时、参数非法都有回填与重试路径
- 有步数上限、重复动作检测、上下文预算三重保护
- 每次循环都有日志与 Token 记录,可按 request_id 追溯
- 有回归评测集,换模型/改提示词后指标可对比
- 单任务成本已折算,并做过模型分层优化
把这份清单全部勾上,你手里才是一个能上线、能运维、能持续迭代的 Agent 系统;在此之前,接 API、装 MCP、写 Skill 都只是准备工作。

登录后可评论,请前往 登录 或 注册