构建你的第一个 AI Agent：从 0 到 1 实战路线

Agent 教程要么太理论（论文解读），要么太框架（调 API 三行代码）。这篇走中间路线：从零写一个能跑的 Agent，理解每一块拼图，最后再谈框架。

01 先明确：你的 Agent 要完成什么任务

新手第一个 Agent 的最佳选题：具体、可验证、步骤在 3-8 步之间。例如「监控某个 GitHub 仓库的 release，有新版时抓取 changelog 并发到群里」。反例是「做一个全能助理」——没有边界的 Agent 无法评估，注定失败。

02 拼图一：规划循环

Agent 的骨架就是一个循环：模型拿到任务 → 输出下一步动作（调用工具或给答案）→ 执行并返回结果 → 结果拼进对话 → 继续下一轮，直到给出最终答案。自己用 50 行代码写这个循环（系统提示词 + while + 工具分发），比直接上框架更能建立直觉。

03 拼图二：工具定义

工具 = 名称 + 描述 + 参数结构 + 执行函数。关键在描述：模型靠描述决定何时、如何使用工具。写描述的技巧是像给新同事写交接文档：这个工具干什么、什么场景该用、参数什么含义、会返回什么。两个工具起步足够，贪多必乱。

04 拼图三：控制与止损

没有止损的 Agent 会无限循环烧 token。三条保险丝：最大轮数（比如 15 轮强制结束）、单步超时、连续相同动作检测（连续 3 次调同一个工具就暂停）。生产环境的 Agent 失控事故，九成缺的就是这三行代码。

05 拼图四：记忆与上下文

短任务靠对话历史就够；跨会话的任务加一层文件或数据库存储（读写也做成工具）。不要一上来就上向量库——多数个人 Agent 的记忆需求，一个 JSON 文件就能满足。

从手写到框架的时机

自己写过一遍循环、踩过失控和上下文超限的坑之后，再换框架（LangGraph、官方 SDK 等）。此时框架是提效工具；跳过手写直接用框架，框架就是黑盒。

06 验收清单

• 任务成功率：跑 20 次统计成功比例，低于 70% 先修提示词；
• 平均轮数：异常多轮说明规划提示词有问题；
• 成本：单次任务 token 消耗是否可控。

Agent 不神秘，它是「循环 + 工具 + 止损」的工程组合。今晚就可以写下第一个工具定义，明晚让它跑起来。