从对话Demo到可演进Agent平台：能力骨架与落地实践

从 AI 对话 Demo 起步做 Agent 平台这件事我前后折腾了快一年。最开始只是想做一个能连大模型 API、能闲聊、能记住几轮上下文的聊天示例后来发现光有对话远远不够因为真实业务需要的是“能干活”的 Agent查数据、调接口、操作工具、处理多步任务并且出了问题还能定位、能回滚、能迭代。这篇文章就是我这个演进过程的开篇总结我会把从 Demo 到可演进 Agent 平台的关键设计思路、最小能力清单、实操代码和踩坑记录一起拆开讲希望能给正在做 Agent 开发的同学一点参考。1. 为什么大多数对话 Demo 走不到平台这一步1.1 先分清“Demo 能做”和“平台能扛”的差距很多团队拿到大模型 API 之后第一反应都是先跑一个对话 Demo。输入框、发送按钮、流式输出、Markdown 渲染界面一亮相看起来确实像那么回事。但 Demo 和平台之间的差距恰好藏在这些不起眼的地方Demo 只要展示“模型能回答”平台必须回答“这个回答靠不靠谱”。Demo 只要把用户问句转给模型平台必须把意图拆解成步骤并决定每一步调用什么工具。Demo 的上下文只存在于一次会话里平台的记忆要贯穿多轮、多任务、多用户。Demo 挂了就重启进程平台挂了得有日志、监控、告警和回放。所以我在做架构设计时给自己定了一条原则先按可演进平台去搭骨架哪怕第一版只实现一个最小闭环。这个思路比一开始就追求功能多要重要得多因为后续加工具、加模型、加策略的时候如果底层结构不支持那所有新增都是在打补丁。1.2 定义 Agent 的三种角色助手、执行者、协调者开始动手前我建议先想清楚你要做的 Agent 到底是哪种角色。我自己整理了三种最常见定位第一类是对话助手型核心是回答问题比如客服机器人、知识库问答。第二类是任务执行型核心是调用工具完成操作比如查天气、订会议、写周报并发送。第三类是协调者型核心是拆解复杂目标并调度多个子 Agent 协作完成。这三种定位不是互斥的但优先级必须明确。我的项目选择的是“任务执行型为主、对话辅助型为辅”因为这类 Agent 更容易展示真实业务价值也更能暴露框架层的问题。如果你刚开始做 Agent 平台我也建议先聚焦到某一个角色上不要一开始就想做一个万能智能体。1.3 自主开发还是基于 Agent 框架二次封装现在开源的 Agent 框架已经不少有偏向工作流编排的有偏向 ReAct 循环的有自带生态工具的。当时我在“直接用框架”和“自研最小内核”之间纠结了很久最后选了折中方案调研框架但不依赖框架核心决策循环自己写外围能力参考成熟设计。原因有三点。第一Agent 平台的灵魂是执行循环、工具协议和上下文管理这些点如果直接用框架封装出问题之后排查成本很高。第二开源框架迭代快、接口变动也快平台一旦深度绑定后续升级会非常被动。第三自己写一遍核心循环之后再去看各种 Agent 框架的源码理解深度完全不同。这算是我个人一个比较实用主义的建议框架可以查、可以抄思路、可以作为对照实现但生产级平台的核心路径不要外包给黑盒。2. 可演进 Agent 平台的最小能力骨架2.1 模型接入层别把自己绑死在一个模型上对话 Demo 阶段可以直接在代码里写死modelgpt-4o之类的参数但平台级设计不行。模型迭代速度太快今天的最优模型可能三个月后就过时了一旦业务全部绑死换模型的成本会高到让你不愿意换。我在模型层做了一次抽象定义了统一的 ChatClient 接口核心方法只有几个chat()、chat_stream()、tool_call_supported()。所有模型适配器都实现这个接口上层业务只依赖接口不依赖具体模型。这样后面接入新模型或者做模型路由时只需要新增适配器不用改业务逻辑。模型接入层还要考虑几件容易被忽略的事超时和重试策略尤其是流式响应场景下的超时处理。token 上限和计费逻辑避免一个长任务把预算耗光。敏感信息过滤在请求发出前和响应返回后都要做校验。这些能力 Demo 阶段可以不做平台阶段必须做。2.2 工具层统一协议比工具数量更重要Agent 平台的核心价值在于工具调用能力。第一版我接了十几个工具后来发现工具数量多并不代表能力强关键是工具协议是否统一、调用是否可控、失败是否可恢复。我最后定的工具协议非常简单每个工具只需要暴露三样东西name全局唯一的工具名。description给模型看的自然语言说明包括什么场景下用、参数含义、返回值格式。parametersJSON Schema 格式的参数定义。这个设计参考了函数调用标准里最常见的协议形式好处是把工具注册逻辑和工具实现逻辑解耦。工具实现者只需要写一个普通函数然后通过装饰器或注册表挂载到平台上即可。工具层的权限边界是另一个必须考虑的问题。Agent 一旦能调用外部 API 或操作系统命令就一定要有审批、限流、审计。我的方案是给工具分了三类只读工具、可执行工具、高风险工具。只读工具可以直接调用可执行工具需要记录审计日志高风险工具需要人工二次确认。这样既保证了效率又控制了风险。2.3 记忆层上下文管理和业务记忆要分开做多轮对话的时候我发现很多新手会把所有聊天记录一股脑塞进上下文结果 token 很快用完回答质量也急剧下降。正确做法是把记忆分两层第一层是运行时上下文只放当前任务相关的信息包括用户最近几轮输入、Agent 最近几步动作、工具返回结果摘要。这一层会在任务结束后按策略清理不能无限累积。第二层是业务记忆指跨会话需要长期保留的实体信息比如用户偏好、项目状态、历史决策等。业务记忆要存到外部存储通过记忆检索接口按需加载而不是全部塞给模型。我当时用了一个非常朴素但有效的策略运行时上下文用滑动窗口管理窗口外的内容自动做摘要压缩业务记忆用键值存储加向量检索按相关性召回 Top K 条。这个方案省掉了不少 token 成本并且记忆召回准确率也不差。2.4 编排层Agent 执行循环和终止条件Agent 不是一次性调用模型就结束而是一个循环往复的过程模型规划 - 调用工具 - 观察结果 - 再规划直到满足终止条件或者达到最大轮数。这个循环的精确控制直接决定了平台的稳定性。我实现的执行循环里有几个关键控制点max_iterations最大迭代次数防止 Agent 陷入无限循环。stop_condition终止条件通常是“模型返回最终回答”或“工具结果满足目标要求”。error_handler异常处理工具报错时要重新反馈给模型让它调整策略。human_interrupt人工介入点当 Agent 连续失败或操作高风险动作时暂停等待人工确认。没有这套控制机制之前我的 Agent 经常出现“反复调用一个失败工具”的傻循环浪费 token 不说用户体验也很差。加上控制点之后整个系统才算真正“可控”。3. 实操落地搭一个能向平台演进的原型3.1 架构分层与目录组织我建议第一版原型不要搞微服务就用单进程多模块的方式。只要模块边界清晰后续拆服务也就是搬代码的事。我的目录结构大致如下agent-platform/ ├── app/ │ ├── main.py # 入口负责启动服务和初始化 │ ├── agents/ # Agent 定义与执行循环 │ │ ├── base.py # Agent 基类 │ │ ├── loop.py # 核心执行循环 │ │ └── executor.py # 工具执行器 │ ├── llm/ # 模型接入层 │ │ ├── client.py # 统一 ChatClient 接口 │ │ ├── openai_adapter.py # OpenAI/兼容协议适配器 │ │ └── local_adapter.py # 本地模型适配器 │ ├── tools/ # 工具注册与实现 │ │ ├── registry.py # 工具注册表 │ │ └── builtin/ # 内置工具集 │ ├── memory/ # 记忆层 │ │ ├── context.py # 上下文窗口管理 │ │ └── store.py # 业务记忆存储 │ ├── api/ # HTTP 接口 │ │ └── routes.py │ └── schemas/ # Pydantic 模型定义 ├── tests/ # 自动化测试 ├── config.yaml # 配置文件 └── requirements.txt这个结构的核心思想是各层单向依赖agents依赖llm和toolstools不依赖agentsmemory可以被agents和tools共同使用。单向依赖保证了你改工具实现时不会影响执行循环改模型适配器时不会影响工具层。3.2 核心执行循环实现执行循环是整个平台的心脏。我用 Python 写了一个最小实现去掉业务细节后大概长这样import asyncio from dataclasses import dataclass, field from typing import Callable, Optional dataclass class AgentConfig: max_iterations: int 10 temperature: float 0.2 dataclass class AgentRuntime: history: list field(default_factorylist) config: AgentConfig AgentConfig() tool_registry: Optional[Callable] None async def run(self, user_input: str): self.history.append({role: user, content: user_input}) for step in range(self.config.max_iterations): response await self.llm_step() tool_calls parse_tool_calls(response) if not tool_calls: return self.history[-1][content] for call in tool_calls: result await self.execute_tool(call) self.history.append({ role: tool, tool_call_id: call[id], content: result }) return 已达最大迭代轮数任务终止。 async def llm_step(self): # 在这里完成模型调用返回结构化响应 pass async def execute_tool(self, call): # 在这里完成工具查找、参数校验和执行 pass这个循环的逻辑很直观先把用户输入加入上下文然后让模型决定下一步是调用工具还是直接回答。如果模型决定调用工具就解析出工具名和参数执行之后把结果追加到上下文再回到模型。只有当模型不再调用工具时才结束或者达到最大轮数。这里有个细节值得注意history中同时保存了用户、助手、工具三种角色。工具结果返回给模型时必须带上tool_call_id这样才能把结果和这次的工具调用请求准确对应起来特别是在并发工具调用的场景下。3.3 工具注册和函数调用的具体实现工具注册表我用了一个装饰器就搞定了使用起来非常顺手。# tools/registry.py from typing import Callable, Dict, Any import inspect TOOL_REGISTRY: Dict[str, Dict[str, Any]] {} def tool(name: str, description: str, parameters: dict): def decorator(func: Callable): TOOL_REGISTRY[name] { name: name, description: description, parameters: parameters, func: func } return func return decorator def execute_tool(name: str, arguments: dict): if name not in TOOL_REGISTRY: raise ValueError(f工具 {name} 不存在) tool_info TOOL_REGISTRY[name] func tool_info[func] # 实际项目中应该用 JSON Schema 做参数校验 return func(**arguments)然后一个内置工具的示例# tools/builtin/weather.py from tools.registry import tool tool( nameget_weather, description查询指定城市的当前天气情况, parameters{ type: object, properties: { city: {type: string, description: 城市名称如北京} }, required: [city] } ) def get_weather(city: str): # 这里替换成真实天气 API 调用 return f{city} 当前天气晴25 摄氏度东南风 2 级。这个设计好在模型侧的接入成本极低。给大模型的函数调用接口传参时直接把TOOL_REGISTRY里每个工具的name、description、parameters组装成一个数组即可。模型返回工具调用请求后我们用execute_tool去执行再把返回结果追加到上下文里。工具实现者不需要关心模型协议细节只需要写普通业务函数。3.4 可观测性与 Agent 评估从 Demo 走向平台的标志之一就是把“黑盒对话”变成“可回放、可评估、可打点”的过程。我在每个 Agent 步骤里都埋了结构化的运行日志包含这些字段{ session_id: xx-xx-xx, step: 3, input_text: 查一下北京的天气, model_response: ..., tool_calls: [ {name: get_weather, arguments: {city: 北京}} ], tool_result: 北京 当前天气晴..., duration_ms: 245, token_usage: {prompt: 123, completion: 45} }这些日志的价值在于当 Agent 在线上出了问题你可以完全回放它的每一步思维过程、工具调用和模型决策。比起看着最终错误结果瞎猜这种回放能力能省下大量排查时间。评估方面我先把重心放在三个最基础的指标上任务成功率、平均轮数、token 消耗。任务成功率看效果平均轮数看效率token 消耗看成本。三个指标一起看才能避免“效果变好但成本翻倍”这种隐形退化。每次改动执行循环或提示词我都会跑一遍回归测试集确保提升不是偶然。4. 常见问题与排查技巧实录4.1 工具调用反复失败、死循环怎么处理这是我遇到最多的第一类问题。Agent 在执行一个工具时报错模型没有选择换一种思路而是不断用类似参数重试直到把最大迭代轮数耗尽。出现这种情况我先检查三件事第一工具描述是否足够清晰。如果描述里没有说清参数边界和错误场景模型就会瞎猜。第二错误信息是否回传。如果工具执行失败后没有把错误信息反馈给模型那模型根本不知道发生了什么只能盲目重试。第三是否配置了动态重试策略。我在框架里加了一个简单逻辑连续两次调用同一工具且参数相同就判断为无效重复直接中断并让模型换一种思路。后来我还在一轮对话前加了一条系统提示如果某个工具连续失败两次主动说明失败原因并建议其他方法。这个提示词配合上面的动态重试判断死循环问题基本绝迹了。4.2 上下文被撑爆回答质量下降工具一多、轮数一长上下文很快就爆了。我最初把工具返回值完整塞进上下文结果一个查询接口返回几十条数据模型注意力被分散后续回答质量明显变差。我的解法是三层策略同时上第一层工具返回值摘要。工具实现里增加一个summary方法返回给模型的不是完整原始数据而是一段精炼摘要。第二层运行时上下文窗口。超过窗口长度的历史消息自动压缩成摘要然后再作为一条 summary 消息放回上下文。第三层关键信息显式提取。如果任务需要精确数据单独通过记忆检索接口按需读取不依赖完整历史。这三层叠加之后token 消耗大概下降了百分之三四十回答稳定性提升更明显。4.3 Agent 评估怎么落地最后聊一下评估这是我从 Demo 转向平台过程中最痛苦的部分。Agent 的输出是开放式的很难像普通分类模型那样简单判对错。我做评估时先放弃了“自动打分”这种一步到位方案而是用了一套分步走的方法前期人力评估为主所有测试用例都设计成有明确语义目标的任务比如“查杭州明天的天气并给出穿衣建议”。只要 Agent 最终回答里包含了指定城市、指定天气、合理穿衣建议就判定通过。这种评估虽然粗糙但能快速抓住明显回归。中期开始积累测试集把线上收集到的真实成功案例和失败案例都沉淀成测试用例。每轮改动后跑一遍回归看通过率变化。有了失败的 case 之后再逐条分析是哪一步决策错误是提示词问题、工具问题还是上下文问题。再往后我会尝试引入 LLM 作为评估器让大模型对有标准答案的任务做二级判定配合抽检人工确认。但直到现在我依然坚持人工复核核心 case因为我发现自动评估器偶尔会“嘴软”对错误答案给出过高评价。下面是我整理的常见问题速查表问题现象常见原因排查顺序与建议Agent 反复调用同一工具错误信息未回传或工具描述不清先看运行日志里工具结果是否正常再检查工具 description 是否有歧义上下文 token 快速耗尽工具返回数据未压缩历史无窗口给工具返回值增加摘要实现上下文滑动窗口工具名称/参数频繁解析失败模型输出格式不稳定统一使用标准函数调用协议增加格式校验与重试纠错多轮后记忆混淆占用信息与业务记忆未分离运行时上下文只保留当前任务长期信息走记忆检索一次任务耗时过长工具串行执行太多支持并行工具调用为工具调用加超时和并发控制线上问题无法定位缺少步骤级日志为每一步增加结构化日志包含输入、输出、耗时、token 用量5. 一些小经验总结我个人在实际操作中最深的一点体会是Agent 平台的建设不要追求一步到位但要保证每一步都能往前走。第一版原型哪怕只支持五个工具、一种模型、单用户访问只要执行循环、工具协议、记忆分层和日志埋点这些核心骨架是干净清晰的后续的功能迭代都只是往骨架上填肉而已。还有一点想重点提醒在给 Agent 配置工具权限的时候要多留个心眼。Agent 调用工具越方便越要确保有审计和审批机制。我见过不少项目因为图一时方便让 Agent 直接执行高权限操作最后出了问题连责任人都找不到。安全机制看着拖慢效率其实是平台能不能长期跑下去的前提。最后再分享一个设计上的小技巧把所有 Agent 的系统提示词、工具描述和运行参数都做成可配置的外部文件不要硬编码在代码里。这样产品和运营同学调提示词时不需要发版你调试不同策略时也方便做对比。对我来说这个调整带来的灵活性远超那点配置文件管理成本。这算是开篇后续我会继续拆解工具协议设计、记忆策略、评估体系建设等更细的模块。