做 AI Agent 这件事，最容易被带偏的地方不是技术难度，而是起步姿势。我见过太多人一上来就选一个功能齐全的编排框架，装完依赖、看完几十页文档、配好一堆抽象层，然后卡在“第一个能跑通的 demo”上，两周过去连一次完整的工具调用都没闭环。所以当我准备做一系列 AI Agent 小项目时，第一条原则就是：先做一个“小到能在一晚上跑通、又完整到能直接改造成生产雏形”的智能体。这篇就聊聊我在这个方向上踩过的坑、做过的取舍，以及一套可以直接参考复现的实现路径。所谓“小项目”，指的不是玩具，而是把大模型、工具调用、循环控制、上下文管理这几个关键部件压缩到最小可运行单元，让整条链路清晰可见——你随时能指着某一行动手改，而不是在一堆隐藏的抽象层里猜它到底干了什么。适合正在观望 Agent 怎么落地的人，也适合已经用过现成产品、想自己拆开看看里面长什么样的开发者。我会从整体设计思路一直讲到具体的代码骨架、参数选择、成本核算和排障清单，中间穿插一些只有真跑过才会知道的细节。

1. 从“能不能跑通”倒推项目边界

1.1 为什么我坚持先做单 Agent 而不是多智能体

新手最容易犯的错，是一上手就设计一个“研究员 + 程序员 + 审核员”的多智能体协作系统。听起来很美，实际跑起来你会同时面对三个以上不可控变量：谁在什么时候说话、消息怎么路由、失败怎么回滚、成本怎么归因。一旦结果不对，你连是哪个环节出问题都定位不了。

单 Agent 的价值就在于它是可观测的。整个系统只有一个决策者，一次循环里的“思考—行动—观察”三步是串行的，日志一打出来，你立刻能看清它为什么调这个工具、参数从哪来、返回了什么、下一步为什么这么走。这个可观测性在调试阶段的价值，远大于多智能体带来的那点结构美感。

我的建议是把项目切成清晰的阶段：第一阶段只做单 Agent 加两三个工具，跑通闭环；第二阶段加记忆和结构化输出；第三阶段才考虑多 Agent 或复杂编排。每一阶段结束都有一个“能用的东西”，而不是攒一个永远不完整的宏大架构。

1.2 一个最小 Agent 到底由哪几块组成

抛开各种框架的包装，一个能干活的 Agent 就是四件事的组合，我用一个生活化的类比说明：

• 大脑：大模型本身，负责理解和决策。它不存记忆，每次都是“失忆状态”下看一遍你给的完整上下文。
• 手脚：一组可调用的函数，也就是工具。模型不能真的执行任何操作，它只能输出“我想调用某某工具，参数是这些”，真正的执行由你的代码完成。
• 记事本：上下文窗口。里面装着系统提示词、历史对话、每次工具调用的结果。这个记事本是有限的，而且是唯一的信息来源。
• 循环控制器：你自己写的调度逻辑。判断模型是想继续干活还是已经给出最终答案，决定循环几次、什么时候强制收尾。

很多人觉得 Agent 神秘，是因为把它当成了一个“会自己思考的程序”。其实它就是一个 while 循环：把上下文喂给模型，模型返回一个动作，执行动作，把结果追加进上下文，再喂一遍。所谓智能，来自模型对上下文的解读能力；所谓工程，全部集中在你怎么组织这个上下文、怎么定义工具、怎么控制循环。

1.3 框架选型：三个层级的取舍

工具选型这块我试过三条路线，各自的适用场景差别挺大：

我个人的选择是：第一个项目用原生裸写，第二个项目再用轻量编排库。理由很直接——你不先用裸写跑一遍，就看不懂轻量库在帮你做什么；等你看懂了，用库才用得安心，出了问题也知道往哪查。至于全功能框架，它更适合已经明确需求、需要多人协作的阶段，拿它做学习入口反而增加认知负担。

提示：如果你所在团队对可维护性要求高，哪怕选框架，也一定要确保它能让你看到“最终发给模型的那段完整上下文”。看不到这一层，后面所有排障都是盲猜。

1.4 项目定位：先选一个“结果可验证”的任务

小项目的任务选择非常关键，我踩过最亏的一次坑，是拿“帮我写行业分析”当第一个 Agent 任务。问题在于结果没法自动验证——你不知道它写得好不好，不知道是提示词的锅还是模型的锅，调优完全靠感觉，最后陷入无休止的玄学调整。

后来我把任务换成资料整理：给定一批本地文本文件，让 Agent 自己去检索、摘取关键信息、按固定结构输出一份摘要。这个任务的好处是：结果有明确结构，对错可以肉眼判断甚至写脚本校验；工具调用路径短，通常两到四轮就能收敛；出错时能清楚区分“检索错了”还是“总结错了”。对练手来说，这种“可验证的窄任务”比“开放式的宽任务”有价值得多。

2. 四个核心部件的落地细节

2.1 系统提示词：把“人设”写成“操作规程”

新手写系统提示词，容易写成岗位描述：“你是一位资深分析师，擅长……”。这类写法对 Agent 帮助很有限，因为模型不知道具体该怎么做。Agent 的系统提示词，本质是一份操作规程，要写清楚四件事：任务目标、可用工具及其使用时机、输出格式、遇到异常怎么办。

我常用的结构大致是这样：

你是资料整理助手，任务是根据用户问题，从给定资料中提取信息并输出结构化摘要。 可用工具： 1. search_docs(query) —— 在资料库中检索相关段落。当你不确定答案所在位置时调用。 2. read_section(doc_id, section) —— 读取指定文档的某一节完整内容。当检索结果片段不足时调用。 工作流程： - 先检索，再判断片段是否足够回答；不足则继续检索或读取完整章节。 - 最多检索 4 次，超过后必须基于已有信息作答。 输出格式： 严格输出 JSON，字段为 summary（字符串）、evidence（字符串数组）、confidence（0-1 之间的小数）。 异常处理： - 若检索结果为空，直接返回 summary 为“未在资料中找到相关内容”，confidence 为 0。 - 不要编造资料中不存在的事实。

这里每一段都有明确用途。“工作流程”这一节极其重要，因为它把原本需要模型自由发挥的规划过程收敛成了一条固定路径，大幅降低了跑偏概率。“最多检索 4 次”这种硬约束，是防止后面要讲的死循环的第一道闸门。

心得：提示词里凡是出现“尽量”“适当”“酌情”这类模糊副词，基本都是隐患。能量化的地方全部量化，能写死的地方全部写死。模型的自由发挥空间只应留在真正需要创造力的地方。

2.2 工具定义：函数签名就是一份契约

工具是 Agent 唯一能改变外部世界的手段，所以它的定义质量直接决定成功率。我的经验是：工具描述要写给“一个完全不了解你代码库的人”看，因为模型就是那个人。

一个反例是参数名为q、描述为“查询”的工具。模型看到这个，只能靠猜——猜该传关键词还是完整句子，猜要不要加引号。正例是参数名query，描述写清“自然语言查询语句，包含核心名词即可，不需要完整句子，长度控制在 20 字以内”。后者能把参数错误率降一个量级。

几条硬规矩我基本不破：

• 一个工具只做一件事。把“检索并总结”合成一个工具，等于把决策权交还给了工具内部，模型就失去了调整空间。
• 参数尽量用基础类型。嵌套对象和数组会让模型在生成 JSON 时更容易出错，能用字符串和数字解决的就别上复杂结构。
• 返回值要有长度上限。工具返回几万字原文，等于直接把上下文撑爆。我一般在工具内部就做截断，返回前 800 到 1500 字，并标注“已截断，如需更多请缩小范围”。
• 错误信息要可读。工具抛异常时不要只返回一个 traceback，而是返回一句人能看懂的话，比如“文件不存在，可用文件列表为：a.txt, b.txt”。模型看到这句，下一轮往往能自己纠正。

这条最后一点特别值得展开。工具报错其实是 Agent 自我修正的最好机会，但前提是错误信息以模型能理解的方式回传。我见过不少实现，工具一出错就整个流程崩掉，白白浪费了模型的纠错能力。

2.3 上下文管理：别让对话变成一锅粥

上下文窗口是 Agent 最稀缺的资源，也是最容易被忽视的地方。一个跑了七八轮的任务，上下文里会堆积大量中间结果，其中很多已经没用了——比如早期一次失败检索返回的空结果。

我用的策略是分层保留：系统提示词永远保留在最前；每一轮的“思考”文本可以压缩甚至丢弃，只保留工具调用和结果；工具结果按时间做滑动窗口，只保留最近 N 条完整内容，更早的替换成一句话摘要（比如“第 2 轮：检索‘成本核算’，返回 3 条片段”）。

这样做的好处是上下文占用可控，而且模型看到的都是有效信息。坏处是可能丢掉早期关键线索，所以我在摘要里会保留关键词，让模型知道“这件事我查过，查的是什么”。

另一个坑是重复内容累积。如果模型连续三次用几乎相同的参数检索，上下文里就会有三份高度相似的结果，既浪费 token 又干扰判断。我的做法是在工具层加一个简单的缓存：相同参数在同一个任务内只真正执行一次，后续直接返回缓存结果，并注明“该查询已执行过，结果同上”。这一招对成本和延迟的改善非常明显。

2.4 输出解析：给模型的自由加上护栏

让模型输出结构化数据，是 Agent 落地到业务系统的必经之路，但也是翻车高发区。模型很可能会在 JSON 外面裹一层 ```json 代码块，可能会在前后加一句“好的，以下是结果”，也可能少个引号。

我的处理是三层防御：

1. 提示词层：明确写“只输出 JSON，不要任何解释文字，不要使用代码块标记”。这能解决八成问题。
2. 解析层：先用宽松方式剥离可能的代码块标记和前后缀，再尝试解析。解析失败不直接抛错。
3. 修复层：解析失败时，把错误信息和原始输出一起回传给模型，让它自己修一次。实测这一次修复的成功率相当高，通常能到七成以上。

如果三层都失败，才走兜底逻辑——返回一个带parse_error标记的结构，把原始文本塞进去，交给人工或下游处理。这里的关键认知是：不要指望模型 100% 输出合法 JSON，要假设它一定会出错，然后设计出错之后的路径。

3. 实操：搭一个能跑的资料整理 Agent

3.1 环境准备与最小依赖

我倾向于把依赖压到最少，第一个项目只装两样东西：一个 HTTP 请求库和一个环境变量管理库。不需要 Web 框架，不需要数据库，不需要向量库——资料量小的时候，直接用关键词匹配检索完全够用，先跑通流程再谈优化。

python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install requests python-dotenv

环境变量里只放两样：接口地址和密钥。这里不写具体厂商，因为不同平台的接口形态差异不小，但对话接口的请求体结构大同小异，都是消息数组加若干参数。

# .env LLM_BASE_URL=https://your-endpoint.example.com/v1/chat LLM_API_KEY=your_key_here

import os from dotenv import load_dotenv load_dotenv() BASE_URL = os.getenv("LLM_BASE_URL") API_KEY = os.getenv("LLM_API_KEY")

注意：密钥永远不要写进代码，也不要在日志里打印完整请求头。排查问题时打印前六位加长度就够了，这个习惯能省掉很多麻烦。

3.2 工具层：三个函数撑起整个能力边界

第一个项目我只定义三个工具，够用且不臃肿：列文件、检索、读章节。

import os, json, glob DOC_DIR = "./docs" def list_docs(): """列出资料库中所有可用文件名。""" files = [os.path.basename(p) for p in glob.glob(os.path.join(DOC_DIR, "*.txt"))] if not files: return "资料库为空。" return "可用文件：" + ", ".join(files) def search_docs(query: str, top_k: int = 3): """按关键词在资料库中检索，返回最相关的若干片段。""" if not query or len(query) > 50: return "查询语句无效，请提供 50 字以内的关键词。" hits = [] for path in glob.glob(os.path.join(DOC_DIR, "*.txt")): with open(path, encoding="utf-8") as f: text = f.read() for para in text.split("\n\n"): if query.lower() in para.lower(): hits.append({"file": os.path.basename(path), "text": para[:600]}) if not hits: return f"未检索到与「{query}」相关的内容。" return json.dumps(hits[:top_k], ensure_ascii=False) def read_section(doc_name: str, keyword: str): """读取指定文档中包含关键词的完整段落。""" path = os.path.join(DOC_DIR, doc_name) if not os.path.exists(path): return f"文件 {doc_name} 不存在。{list_docs()}" with open(path, encoding="utf-8") as f: text = f.read() blocks = [b for b in text.split("\n\n") if keyword in b] if not blocks: return f"在 {doc_name} 中未找到包含「{keyword}」的段落。" result = "\n\n".join(blocks) if len(result) > 1500: result = result[:1500] + "\n[内容已截断，请用更具体的关键词缩小范围]" return result

三个函数都不复杂，但每个都埋了前面说的那几条规矩：查询长度校验、结果数量上限、文本截断、错误信息可读。特别是read_section里文件不存在时顺手把可用文件列表返回去，模型下一轮基本能自己改对文件名，这个小细节减少了我很多次手动介入。

工具定义还要转成模型能理解的描述格式，也就是一份 JSON Schema：

TOOLS = [ { "type": "function", "function": { "name": "search_docs", "description": "在资料库中按关键词检索相关段落。不确定信息位置时优先调用。", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "检索关键词，20 字以内，优先用名词"}, "top_k": {"type": "integer", "description": "返回条数，默认 3"} }, "required": ["query"] } } }, # list_docs 与 read_section 同理，此处略 ]

描述文案里的每一个字都算数。“不确定信息位置时优先调用”这句话，比写十遍“请谨慎使用工具”都管用。

3.3 主循环：ReAct 骨架的极简实现

核心循环其实就是个 while，但写得糙和写得稳，差别在细节上。

import requests, json, time MAX_TURNS = 8 TIMEOUT = 30 def call_llm(messages, tools=TOOLS): for attempt in range(3): try: resp = requests.post( BASE_URL, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json={"messages": messages, "tools": tools, "temperature": 0.2}, timeout=TIMEOUT ) resp.raise_for_status() return resp.json() except Exception as e: if attempt == 2: raise time.sleep(2 ** attempt) # 指数退避：1s, 2s def run_agent(question: str): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": question} ] trace = [] for turn in range(MAX_TURNS): result = call_llm(messages) msg = result["choices"][0]["message"] messages.append(msg) # 没有工具调用，说明模型给出了最终答案 if not msg.get("tool_calls"): return msg["content"], trace for call in msg["tool_calls"]: name = call["function"]["name"] try: args = json.loads(call["function"]["arguments"]) except json.JSONDecodeError: messages.append({ "role": "tool", "tool_call_id": call["id"], "content": "参数 JSON 解析失败，请检查格式后重试。" }) continue fn = {"list_docs": list_docs, "search_docs": search_docs, "read_section": read_section}.get(name) output = fn(**args) if fn else f"未知工具：{name}" trace.append({"turn": turn, "tool": name, "args": args, "output": output[:200]}) messages.append({ "role": "tool", "tool_call_id": call["id"], "content": output }) # 轮次耗尽，强制收尾 messages.append({"role": "user", "content": "已达到最大轮次，请基于现有信息直接输出 JSON 结果。"}) final = call_llm(messages, tools=[]) return final["choices"][0]["message"]["content"], trace

这段代码里有几个值得说的设计点。

温度设为 0.2。Agent 任务要的是稳定和守规矩，不是文采。温度调高会让模型在参数生成上更“活泼”，也更容易瞎编参数值。做工具调用，低温几乎是标配。

指数退避重试。网络抖动和接口限流是常态，一次失败就崩掉太脆。1 秒、2 秒的退避简单有效，加上三次上限，基本能覆盖大部分瞬时故障。

参数解析失败也要回传。模型偶尔会生成不合法 JSON，这时候如果直接抛异常，整个流程就死了。把错误当作一次工具结果塞回上下文，模型通常下一轮就能改对。

轮次耗尽后的强制收尾。这是很多人会忘的一步。如果不加，Agent 跑到最大轮次后会直接返回空或者抛错，前面的工作全废。我的做法是追加一条指令，并且这次调用不再给工具——断了它继续折腾的念想，逼它立刻总结。

全程留 trace。每一轮的工具有哪些参数、返回了什么（截断到 200 字），全部记下来。这份 trace 在排障时的价值，比任何日志框架都大。

3.4 参数调优：几个必须手动算一算的数

最大轮次 MAX_TURNS怎么定？我的算法是：典型任务需要的最少工具调用次数乘以 2，再加 2。资料整理任务一般两到四次工具调用能收敛，所以 8 是比较舒服的上限——既给了纠错空间，又不会让跑偏的任务无限烧钱。

单次请求超时设 30 秒。这个数字跟模型的输出长度有关，长文本生成会更久，但 Agent 场景里每轮输出通常很短（就是一次工具调用），30 秒足够。超时设太长的代价是故障时用户干等，体验更差。

工具返回长度控制在 600 到 1500 字之间。这个量级能覆盖一个完整段落的信息量，又不至于几轮就把上下文塞满。如果你的任务是长文档分析，就得配合前面说的滑动窗口策略。

成本粗算。假设系统提示词 800 token，每轮工具结果 500 token，模型每轮输出 200 token，跑 5 轮：

• 输入大致累加：第 1 轮 1000，第 2 轮 1700，第 3 轮 2400，第 4 轮 3100，第 5 轮 3800，合计约 12000 token
• 输出合计约 1000 token

注意这个累加特性——上下文的成本是平方级增长的，因为每一轮都要把历史全带上。这就是为什么轮次上限和结果截断不是可选项，而是成本控制的核心手段。一个失控的 20 轮任务，成本可能是正常任务的十倍以上。

4. 排障实录：那些只有跑起来才会遇到的问题

4.1 死循环与工具调用风暴

最常见的故障是 Agent 反复调用同一个工具，参数几乎不变，五六轮过去还在原地。触发原因通常有两类：一是检索确实没找到答案，模型不甘心；二是它在两个工具之间来回横跳，A 说信息不足去查 B，B 说去查 A。

我的处理分三层。提示词层设定明确的次数上限并声明“超过后必须作答”，这是第一道闸门。代码层做一个简单的重复检测：如果连续两轮的工具名和参数完全一致，直接在返回内容里加一句“该查询已执行过，结果与上次相同，请换一个思路或直接作答”。最后一层是 MAX_TURNS 兜底。

实测下来，第二层效果最好。因为模型看到“你已经查过这个了”这句话，往往会意识到自己陷入了循环，转而尝试别的路径。

4.2 参数幻觉：模型编造了不存在的值

典型场景：文件明明叫report_2023.txt，模型传了report.txt；日期参数要求YYYY-MM-DD，它传了“上个月”。这类问题的根因是模型手里没有准确信息，只能靠猜。

两个应对办法配合使用效果最好。第一，在系统提示词里明确“调用工具前若不确定文件名，先调用 list_docs 获取列表”。第二，也是更重要的，工具的错误返回值要带上正确的候选值——就像前面read_section里做的那样，把可用文件列表直接塞回去。模型看到列表，下一轮基本能挑对。

如果某个参数取值空间很小（比如只有三种状态），直接把它写成枚举塞进工具描述里，比让模型自由生成靠谱得多。

4.3 上下文被撑爆的三种表现

上下文超限不一定报错，它有几种很隐蔽的表现形式。第一种是中间部分的信息被“遗忘”——模型明明前面查到了答案，后面却说没找到。第二种是输出质量突然下降，开始胡言乱语。第三种才是接口直接返回长度超限错误。

排查方法很朴素：把每次请求的 messages 打印出来数一下字符数。如果发现某一轮突然从 3000 字跳到 15000 字，基本就是某个工具返回了超长内容。

对策按优先级排：先缩短工具返回值，这是治本；再精简系统提示词，删掉那些“以防万一”的冗余段落；最后才考虑滑动窗口和摘要压缩。我见过不少人一上来就搞复杂的上下文压缩算法，其实把工具返回截断一下问题就没了。

4.4 常见问题速查表

4.5 一个容易被忽略的坑：工具描述与实现不一致

我踩过一次很隐蔽的坑：工具描述里写“返回最相关的前三条”，实现里因为改代码忘了同步，变成了返回全部。结果上下文被瞬间撑大，模型开始丢信息，排查了半天才发现是文档和实现脱节。

从那以后我养成一个习惯：工具的描述文案和实现放在同一个文件里，改实现必须看到描述。同时给每个工具写一个最小单元测试，测返回长度是否超限、错误路径是否返回了可读信息。这几个测试写起来十分钟，能省掉几小时的迷茫。

5. 跑通之后才开始的功课

5.1 评估集：先建一个能重复跑的对照组

第一个版本跑通后，很容易陷入“改一版提示词，手动试一下，感觉好像好点了”的循环。这种凭感觉调优效率极低，因为你没法判断改动到底是真提升还是随机波动。

我的做法是攒一个二十条左右的评估集，覆盖正常路径和各类边界：正常问题、资料里没有答案的问题、需要多跳检索的问题、文件名容易混淆的问题、超长文档的问题。每条写清楚预期行为，比如“应当返回 confidence 为 0”或者“必须引用具体文件”。

每次改提示词或换参数，跑一遍这二十条，人工看一眼通过率。这个流程土，但极其有效。我印象最深的一次是某个“看起来更清晰”的提示词改版，评估集一跑，边界场景通过率从 16/20 掉到了 11/20，及时拦住了。

5.2 日志字段：留下能复现的现场

日志不要只记“成功/失败”，那样出了问题根本没法复现。我至少要记这几个字段：任务 ID、轮次、工具名、完整参数、返回内容长度（不是内容本身，避免日志爆炸）、本次调用的输入 token 和输出 token、耗时。

有了这些，任何一次异常都能还原出完整执行路径。特别是参数和返回长度这两个，前者定位幻觉，后者定位上下文膨胀，几乎覆盖了七成以上的问题。

心得：日志里一定要有任务 ID 并贯穿始终。单次调试时觉得多余，一旦并发跑起来或者做批量评估，没有它就完全没法把散落的记录拼回一次会话。

5.3 扩展方向：从能跑到好用

这套骨架跑顺之后，扩展路径其实很清晰，我大致按投入产出比排了个序。

第一优先级是换掉朴素检索。现在是关键词完全匹配，稍微换个说法就查不到。可以先用更宽松的匹配策略，比如分词后按命中词数排序，成本几乎为零，效果提升却很直接。

第二优先级是加一层结果缓存。同样的工具调用参数不要重复执行，尤其在调试阶段反复跑同一批问题时，缓存能省掉大量时间和调用成本。

第三优先级才是换更好的模型或者上向量检索。这两件事都需要额外投入，等你的评估集显示瓶颈确实在这里再做，别一上来就堆料。

至于多 Agent 协作，我的看法是：当你发现单 Agent 的提示词已经长到你自己都维护不动，或者它需要同时具备两种互相冲突的行为模式时，才考虑拆分。拆分之前一定要确保单 Agent 版本的评估集跑得足够稳，否则你只是把一个可控问题变成了三个不可控问题。

我自己在这几个小项目里最深的体会是，Agent 的工程质量，八成取决于你喂给模型的那段上下文有多干净、工具的错误信息有多友好、循环的边界设得有多明确。模型能力当然重要，但它更像是给这套框架加的一个乘数，而不是让它跑起来的那个基底。把基底打牢，换哪个模型都能跑得不错；基底是虚的，模型再强也救不回来。