很多人以为 Agent 是一种更聪明的模型。不是。Agent 不是某个模型，也不是一次 API 调用，而是一种让模型按"思考—行动—观察"循环反复运转的工作方式。本文用一个最小例子讲透这个分界线，再定下手搓路线的接入层设计。
心智模型：从会聊天到会办事
聊天机器人是"文本进、文本出"，像被关在屋子里博览群书但不能出门的人——递纸条提问，递纸条回答，没有手。Agent 解决的就是"长出手"。
最小例子：查北京今天的气温，再算和上海的温差。这句话对纯聊天模型是死结——训练数据里没有今天的实时天气。Agent 接到后会拆步：搜北京气温、搜上海气温、相减、报回；某个城市查不到还会换关键词重试。关键差异在于：不是一次性把答案吐出来，而是先想、再动、看结果再想、再动，直到任务完成。
公式翻译：五个部件加一个循环
社区共识公式 Agent = LLM + Memory + Tools + Planning + Action 太名词化，翻译成人话：大脑负责理解和决策；记事本记住本轮对话和跨会话知识；手脚扩展能力边界（搜索、计算、读文件）；任务拆解把大目标切成小步骤；执行把工具调用真的发出去并喂回结果。
但五个部件串不起来就还不是 Agent。更本质的判据一句话：调一次对话接口是"会聊天"；让它自己决定调工具、看见结果、再决定下一步，才是 Agent。判断标准只有一条：模型是否在一次任务里自主地、多次地决定"下一步做什么"并真的执行了外部动作。
三个场景自测：输入回车得回答——聊天机器人；说"订明天的机票"，它查航班、比价、问偏好、下单——Agent；问"1 到 100 的和"直接答 5050——模型自身能力，除非它真的调了计算器工具。
2026 的演进：从五要素到 Harness
工程实践把这个公式推进了一步。"模型之外、支撑 Agent 跑起来的整套编排系统"被命名为 Harness——模型是马，Harness 是套在马身上让它拉车的东西。它在五要素之上叠加四件事：工作流循环（思考、行动、观察回路的工程化）、评估体系（自动判断每步对错）、权限控制（删文件花钱要不要人确认）、持久化状态（崩了能续跑）。主流编码 Agent 的内核都是这个结构。
接入层设计：模型无关是唯一原则
手搓路线的第一步不是写循环，是打通"模型能对话"这条最短路。接入层封一个 LLMClient，OpenAI、DeepSeek、通义、OpenRouter 的 Chat Completions 格式一致，差异只在 base_url 和模型名——换模型内核零改动。
流式解析是核心难点。SSE 的每个 data: 行是一个增量片段，结尾发 [DONE]。解析循环有三个必踩坑：缓冲区拼接（最后一次 decode 要带 stream: true）、坏行容错（buffer 尾部不完整的行留到下一轮）、结束标记判断。错误分支统一抛业务异常，不让底层 fetch 错误裸奔。
两个真实环境坑
坑一：DeepSeek 的 base_url 不带 /v1。官方兼容地址和 OpenAI 官方路径结构不同，配错返回 401，报错信息还不指向根因。
坑二：dotenv 默认不覆盖已存在的环境变量。终端或 CI 已注入同名变量时，.env 里的配置被静默忽略，请求实际打到别的 Key 上——表现为 API 返回 key 无效，排查方向完全跑偏。入口用 override: true 让本地配置优先。
验证标准
接入层验收三组证据：单元测试覆盖四个分支（非流式解析、非 2xx 抛错、SSE 增量拼接、坏行容错），不依赖真实网络；类型检查零错误，strict 模式把索引越界拦在编译期；无密钥守卫——没配 Key 时安全退出并提示，不带空 Key 打请求。当前这一步还是"用户说、模型答"的单向补全，没有循环。下一课补上思考、行动、观察的回路——那是 Agent 与高级补全之间的真正分水岭。
评论0