很多人以为Agent开发就是调接口，但实际上从Demo到产品，中间隔着巨大的工程鸿沟。这篇文章通过实战经验揭示，真正决定Agent成败的，是接口之外那95%的系统工程挑战。
智能速览
调接口只占Agent开发工作量的5%
工具设计和错误处理比想象中复杂得多
多步骤任务的错误传播概率超过70%
上下文窗口管理直接影响Agent可靠性
生产环境与实验室测试性能差距达37%
精华内容
从看似简单的调接口开始，逐步深入真实场景下的工程挑战，每一个坑都是开发者必经的成长之路。
工具集成陷阱
接真实API远比Demo复杂。光是处理微软Graph的OAuth认证，就需要研究权限模型、处理重定向、安全存储token等整套流程。API分页返回、速率限制等问题，Agent根本无法理解错误含义，只能瞎猜原因。而且每家服务的认证体系和API设计都不同，工作量呈乘法增长。阿里云数据显示，生产级Agent系统中，70%的工作都是工具工程。
Tool设计平衡
Tool设计的粒度拿捏是个难题。设计得太死板，用户需求覆盖不全；设计得太宽泛，模型又不知道该填什么参数。Berkeley测试发现，Llama 3.1 8B在46个工具时全军覆没，19个工具时才能正常工作。Tool的描述文本同样关键，好的描述能让调用准确率天差地别。这不仅是代码实现，更像是给模型写说明书。
错误传播效应
复杂任务的多步骤执行中，错误会被不断放大。即使最好的模型工具调用准确率也只有77.5%，一个五步任务全部正确的概率不到28%。第一步的小错误会引发连锁反应，比如时间解析错误导致后续所有操作都建立在不正确的基础上。需要在每步之间加入校验逻辑和回滚机制，这些都没有API文档会教你。
成本控制难题
当真实用户使用时，账单会成为噩梦。每天几百个请求，每个请求平均四五轮tool call，每月可能烧掉几千块。简单查询其实不需要用最强模型，但任务路由机制本身又是个新挑战。用大模型判断复杂度要花钱，用规则引擎总有漏洞，用小模型做分类器又增加了维护成本。省下的token钱可能还不够付多模型适配的人力成本。
上下文管理
长任务执行时Agent会"走偏"，这就是"Agentic Amnesia"。研究表明，多轮对话中所有模型性能平均下降39%。上下文窗口有限，每一步工具调用都在消耗空间，模型会忘记原始任务。Spotify团队发现Agent在填满上下文后会"迷失方向"。动态决定模型能看到什么、该忘掉什么，是门精深的内存管理学问。
Agent开发的本质不是调接口，而是一门新的工程学科。从Demo到产品，需要建立完整的可靠性、可观测性、上下文管理和错误恢复体系。波士顿咨询调研显示，企业Agent项目中不到20%达到预期ROI，这门新学科还有很长的路要走。
关键评论
开源模型在企业级Agent应用上性能仍有差距
Agent工程中最难的是eval和权限设计问题
实时性要求高的业务场景下，推理模型速度无法满足预期
作者描述的坑非常真实，实际开发中确实都遇到了
