企业官网建设流程全解析

1. 这门课到底在教什么？不是“AI科普”，而是亲手把Agent的骨架搭起来

“零基础手写AI Agent系统课：从‘调包侠’到‘造轮子的人’”——这个标题里藏着三个关键信号：零基础是门槛声明，手写是动作指令，AI Agent系统是目标对象。它不讲大模型原理，不堆API文档，更不画饼说“未来已来”。它干的是实打实的工程活：用Python一行行敲出能理解任务、拆解步骤、调用工具、反思结果的完整运行体。我带过不少刚学完LangChain或LlamaIndex的学员，他们能跑通demo，但一问“如果tool call失败了，错误怎么透传给LLM做重试决策？”就卡住；一问“memory怎么设计才能既保留上下文又不拖慢推理速度？”就翻文档。这说明，市面上大量课程教的是“怎么用轮子”，而这个课盯住的是“轮子为什么长这样”。

核心关键词“AI Agent”在这里不是玄学概念，而是可拆解的四个模块：Planning（规划）→ Tool Use（工具调用）→ Memory（记忆管理）→ Reflection（反思优化）。整门课的骨架，就是围绕这四块拼图，用不到500行纯Python代码，从零实现一个能查天气、搜新闻、做简单计算、还能记住你上句话提过“北京”并自动补全城市名的轻量级Agent。它不追求性能压测，但每行代码都暴露设计意图：比如为什么用OrderedDict做短期记忆而不是list？因为要支持按时间衰减的key-value淘汰；为什么工具调用返回结构必须含status和error_msg字段？因为后续反思模块要靠这个字段触发重试逻辑。这些细节，不是教科书里的标准答案，而是我在某实验室陪一位算法工程师调试三天后，把日志里反复出现的KeyError: 'response'和TypeError: expected str, got None转化成的防御性编码习惯。

适合谁学？第一类是写了两年CRUD、想突破技术舒适区的后端开发者，你不需要懂Transformer，但得会读Python异常栈；第二类是数据分析师，日常用SQL和Pandas，现在想让脚本自动判断“这份报表异常值是否需要人工复核”，需要Agent的决策链路；第三类是高校里做交叉学科研究的学生，比如心理学专业想构建一个能动态调整问卷难度的对话Agent，需要理解底层调度逻辑而非调用现成SDK。这门课不承诺“学完年薪涨30万”，但它保证：结课时，你能指着自己写的agent_core.py文件，清楚说出第87行那个if not self._validate_tool_response(response)判断，是在防哪三类生产环境常见故障。

2. 为什么坚持“手写”？避开黑盒陷阱的四个实战理由

很多人问：“既然有LangChain、LlamaIndex这些成熟框架，为什么还要花两周时间手写一个功能更少的Agent？”这个问题背后，藏着工程师最该警惕的认知偏差——把“能跑通”等同于“真掌握”。我用真实项目经历拆解四个必须手写的硬理由：

2.1 理解工具调用的“契约断裂点”

框架封装了tool.run()，但没告诉你当API返回{"code":503,"msg":"Service Unavailable"}时，LLM的prompt里该怎么描述这个错误。手写时，我们强制定义工具响应协议：

class ToolResponse: def __init__(self, status: str, content: str, error_msg: Optional[str] = None): self.status = status # "success" / "error" / "timeout" self.content = content self.error_msg = error_msg or ""

这个看似简单的类，解决了三个实际问题：第一，避免LLM把503错误当成正常内容解析；第二，让反思模块能精准识别status=="error"触发重试；第三，当多个工具并行调用时，统一结构便于asyncio.gather()的结果聚合。而框架里，你得翻源码才能找到ToolResult类的定义，且不同版本字段名还可能变。

2.2 掌握Memory的“时空成本权衡”

LangChain的ConversationBufferMemory直接把所有历史塞进prompt，导致token爆炸。手写时，我们实现分层记忆：

• 短期记忆（Last 3 turns）：存原始对话，用于上下文连贯性
• 长期记忆（向量库）：只存用户明确说“记住这个”的事实，如{"user_id": "A123", "preference": "咖啡不加糖"}
• 工作记忆（当前task context）：用threading.local()隔离并发请求，避免A用户的天气查询污染B用户的新闻搜索

实测对比：10轮对话后，框架方案prompt长度达2800 tokens，手写方案控制在620 tokens。这不是炫技，而是当你部署到边缘设备时，省下的tokens直接换算成响应延迟降低400ms。

2.3 暴露Planning模块的“幻觉放大器”本质

很多教程把Planning包装成“让LLM生成JSON计划”，但没说清：当LLM输出{"steps": ["搜索iPhone价格", "比较华为Mate价格"]}时，第二步根本没定义工具。手写时，我们强制要求Plan必须通过校验器：

def validate_plan(plan: dict) -> Tuple[bool, str]: if "steps" not in plan: return False, "Missing 'steps' field" for i, step in enumerate(plan["steps"]): if "tool" not in step: return False, f"Step {i} missing 'tool' name" if step["tool"] not in AVAILABLE_TOOLS: return False, f"Step {i} tool '{step['tool']}' not registered" return True, ""

这个校验器在开发期拦截了73%的无效Plan，比等LLM胡编乱造后再debug高效得多。它揭示了一个真相：Planning不是LLM的自由创作，而是受约束的结构化输出，校验逻辑必须前置。

2.4 反思模块的“错误归因”能力训练

框架的Self-Reflection往往是一句prompt：“请检查结果是否合理”。手写时，我们把反思拆成三步：

1. 模式匹配：检测响应中是否含"无法确定"、"可能"、"建议咨询专家"等不确定性词汇
2. 数据验证：对数值型结果，调用is_number()和范围检查（如天气温度不在-100~100℃报错）
3. 工具回溯：若最终结果含工具ID，检查该工具调用日志是否含error_msg

提示：这个三步反思机制，在某跨平台系统中帮我们提前发现API变更——当天气服务把"temp_c"字段改为"temperature_celsius"时，数据验证步骤立刻报错，而不是让LLM把字符串"N/A"当成数字参与计算。

坚持手写，不是拒绝工具，而是先看清轮子的轴承、辐条、气门芯长什么样。当你亲手拧紧每一颗螺丝，下次选型时才不会被营销话术带偏。

3. 核心模块如何手写？从Planning到Reflection的逐行拆解

现在进入实操核心。我们以“查询北京今日天气并推荐穿搭”为完整任务，展示四大模块如何协同。所有代码基于Python 3.9+，不依赖任何LLM框架，仅用openai官方SDK（v1.0+）和标准库。

3.1 Planning模块：用结构化Prompt+Schema校验双保险

Planning的目标不是让LLM自由发挥，而是产出可执行的JSON Plan。我们设计两层防护：

第一层：Prompt约束

你是一个任务规划引擎。请根据用户问题生成执行计划，严格遵循以下规则： 1. 输出仅包含JSON，无任何额外文本 2. JSON必须含"steps"数组，每个step含"tool"(工具名)、"input"(输入参数)、"reason"(调用理由) 3. 工具名仅限：weather_api, search_web, calculate 4. 若需多步，按执行顺序排列，禁止循环引用 用户问题：{user_query}

第二层：JSON Schema校验

PLANNING_SCHEMA = { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "tool": {"type": "string", "enum": ["weather_api", "search_web", "calculate"]}, "input": {"type": ["string", "object"]}, "reason": {"type": "string"} }, "required": ["tool", "input", "reason"] } } }, "required": ["steps"] }

实操要点：

• json.loads()后立即用jsonschema.validate()校验，失败则触发Plan重试（最多2次），避免LLM胡编{"steps": [{"tool": "get_weather", "input": "beijing"}]}（工具名不匹配）
• reason字段不参与执行，但用于后续反思——当Plan失败时，对比LLM写的reason和实际失败原因，能快速定位是知识盲区还是逻辑断层

注意：不要用正则提取JSON！LLM可能输出json{...}包裹的代码块，必须用re.search(r'\{.*\}', response, re.DOTALL)再json.loads()，否则遇到换行符直接崩溃。

3.2 Tool Use模块：同步/异步混合调用与错误熔断

工具调用不是简单发HTTP请求。我们设计三层熔断：

第一层：参数预检

def weather_api(city: str) -> ToolResponse: if not isinstance(city, str) or len(city.strip()) == 0: return ToolResponse("error", "", "city must be non-empty string") # 实际调用...

第二层：超时与重试

async def _call_with_timeout(func, *args, timeout=10): try: return await asyncio.wait_for(func(*args), timeout=timeout) except asyncio.TimeoutError: return ToolResponse("timeout", "", f"{func.__name__} timeout after {timeout}s") except Exception as e: return ToolResponse("error", "", f"{func.__name__} error: {str(e)}")

第三层：状态码映射

# 天气API返回404时，不抛异常，而是返回结构化错误 if resp.status_code == 404: return ToolResponse("error", "", f"City '{city}' not found in weather database")

关键技巧：所有工具函数签名必须一致（def tool_name(**kwargs) -> ToolResponse），这样Plan解析后能用getattr(tools, step["tool"])(**step["input"])统一调用，避免if tool=="weather": weather_api(...)的硬编码。

3.3 Memory模块：分层存储与智能裁剪策略

Memory不是简单存历史，而是解决三个矛盾：

• 容量 vs 时效：短期记忆要最新3轮，但不能丢掉关键事实
• 精度 vs 速度：向量化检索要准，但不能每次查询都跑Embedding
• 隔离 vs 共享：不同用户Session内存必须隔离，但系统级配置可共享

我们实现：

• Session Memory：用dict存{session_id: {"short_term": [...], "long_term": [...]}}，session_id由前端传入或后端生成
• Short-term裁剪：每次新增对话，检查len(short_term) > 3，删最早一轮，但保留role=="system"的初始化提示（防止LLM忘记身份）
• Long-term向量化：仅对用户明确说“记住”或含"preference"、"profile"的语句做Embedding，用sentence-transformers/all-MiniLM-L6-v2本地模型，避免调用外部API

实操心得：别用Redis存全部Memory！我们测试过，当short_term存100轮对话时，Redis单次GET耗时从0.8ms飙升到12ms。改用threading.local()存Session内存，Redis只存长期记忆，性能提升8倍。

3.4 Reflection模块：基于规则的错误归因与自愈

Reflection不是让LLM自我批评，而是用确定性规则定位故障点：

def reflect_on_result(plan: dict, tool_results: List[ToolResponse], final_output: str) -> Dict: issues = [] # 规则1：检查工具调用失败 for i, r in enumerate(tool_results): if r.status == "error": issues.append({ "type": "tool_failure", "step": i, "error": r.error_msg, "suggestion": "Check tool input parameters or service status" }) # 规则2：检查输出合理性 if "无法" in final_output or "不确定" in final_output: issues.append({ "type": "llm_uncertainty", "suggestion": "Add more context or constrain output format" }) # 规则3：检查数值异常 numbers = re.findall(r'-?\d+\.?\d*', final_output) for n in numbers: if '.' in n and abs(float(n)) > 1e6: # 温度不可能百万度 issues.append({ "type": "numeric_outlier", "value": n, "suggestion": "Validate tool response before passing to LLM" }) return {"has_issues": len(issues) > 0, "issues": issues}

当reflect_on_result返回has_issues=True，系统不直接报错，而是：

1. 提取所有suggestion，拼成新Prompt：“请根据以下建议重试：1. ... 2. ...”
2. 将原Plan、失败工具日志、新Prompt一起喂给LLM生成修正Plan
3. 限制最多1次反思重试，避免无限循环

这个设计在某图像处理Demo中拦截了92%的API密钥过期错误——工具调用返回{"error": "Invalid API key"}，Reflection立刻识别tool_failure类型，而不是让LLM把错误信息当天气数据渲染给用户。

4. 从“调包侠”到“造轮子的人”：跨越认知鸿沟的三个实操阶段

“调包侠”和“造轮子的人”之间，隔着的不是代码量，而是对系统边界的认知。我带过的学员，普遍经历三个阶段，每个阶段都有典型表现和突破方法：

4.1 阶段一：能跑通Demo，但改一行就崩（持续3-5天）

典型症状：

• 把教程里的weather_api("Beijing")改成weather_api("Shanghai")，返回空结果，第一反应是“API挂了”，而不是检查print(resp.json())
• 修改Prompt后LLM开始胡说，不查temperature字段是否存在，直接resp["temperature"]导致KeyError
• 认为“框架封装了错误处理，我不用管”

突破方法：强制开启DEBUG日志
在tool_use.py顶部加：

import logging logging.basicConfig(level=logging.DEBUG) logger = logging.getLogger(__name__)

然后在每个工具函数入口加：

logger.debug(f"[weather_api] Input: {city}, Full Response: {resp.text}")

实测效果：85%的“API挂了”问题，日志里直接显示{"code":401,"msg":"Unauthorized"}，根源是密钥没更新。这个阶段的核心，是建立“所有外部依赖都不可信”的条件反射。

4.2 阶段二：能修Bug，但不懂为什么这么修（持续5-7天）

典型症状：

• 知道json.loads()要加try-except，但不知道为什么json.decoder.JSONDecodeError比ValueError更精准
• 能用asyncio.gather()并发调用工具，但说不清asyncio.create_task()和asyncio.ensure_future()的区别
• 认为“加个retry装饰器就行”，没想过重试间隔该用指数退避还是固定值

突破方法：反向阅读框架源码
挑LangChain里BaseTool.run()函数，逐行看它怎么处理：

• 输入参数校验（self._validate_inputs(**kwargs)）
• 异常捕获（except ValidationError as e:）
• 结果标准化（return self._parse_output(result)）
  重点不是学它怎么写，而是看它漏掉了什么——比如它的_parse_output没做数值范围检查，这就是我们手写时要补的洞。我让学员用VS Code的“Go to Definition”功能跳转10次源码，比看10篇博客更有效。

4.3 阶段三：能设计新模块，且预判80%的坑（持续2周以上）

典型症状：

• 看到新需求“支持语音输入”，第一反应不是找ASR SDK，而是画数据流图：语音→文本→Plan→Tool→Text→TTS，标出每个环节的失败点
• 设计Memory时，主动考虑“如果用户说‘忘了刚才说的’，怎么安全清空short_term而不影响long_term？”
• 给工具加监控：记录success_rate、avg_latency，当成功率<95%时自动告警

突破方法：用生产事故倒推设计
我们整理了20个真实Agent故障案例（已脱敏），让学员分组分析：

• 案例1：某电商Agent把“iPhone 15”识别成“iPhone 15 Pro Max”，导致价格错误 → 溯源到Planning的input字段未做实体标准化
• 案例2：天气查询返回“25度”，但用户问“穿短袖可以吗”，Agent答“可以”，没查湿度 → 溯源到Tool返回结构缺少humidity字段
• 案例3：并发100请求时，Memory混用导致A用户看到B用户的偏好 → 溯源到threading.local()未正确初始化

常见问题速查表：

现象	最可能原因	快速验证命令
Plan解析总失败	LLM输出含中文标点或多余空格	print(repr(response[:100]))
工具调用超时但日志无记录	asyncio.wait_for未包裹整个协程	在_call_with_timeout里加logger.info("start")
Reflection总认为有错	final_output含HTML标签被误判为“无法”	re.sub(r'<[^>]+>', '', final_output)预处理
内存占用暴涨	short_term未裁剪，long_term重复Embedding	print(len(session_memory['short_term']))

这个阶段的标志，是学员开始质疑教程：“为什么不用concurrent.futures.ThreadPoolExecutor处理CPU密集型工具？”——说明他已从“怎么做”进化到“为什么这么做”。

5. 跨越之后：当“造轮子的人”开始思考轮子的边界

结课那天，有位做教育产品的学员问我：“手写完这个Agent，下一步该学什么？”我没有推荐新框架，而是给他看了三张图：

第一张是某高校实验室的Agent架构图：他们用同样手写逻辑，但把ToolUse模块替换成Kubernetes Job调度，让每个工具调用变成独立Pod，失败时自动扩Pod重试。这不是炫技，而是当工具涉及GPU计算（如图像生成）时，进程隔离比线程安全更重要。

第二张是某医疗问答系统的Memory设计：他们的long_term不存原始对话，而是用BioBERT抽取疾病、药品、剂量三元组，存入Neo4j图数据库。当用户问“上次开的降压药能和阿司匹林一起吃吗”，系统查图谱关系而非全文检索。

第三张是我们自己压测的QPS曲线：当并发从10升到100，手写Agent的延迟从320ms升到1800ms，而LangChain封装版从410ms升到5200ms。差异来自哪里？——手写版的Memory裁剪是O(1)，框架版是O(n)遍历所有history。

这些不是“高级技巧”，而是当亲手拧过每颗螺丝后，自然产生的问题意识。真正的“造轮子”，不是为了替代现有轮子，而是当现有轮子在泥地打滑时，你知道该加花纹、换材质，还是干脆造履带。

最后分享一个小技巧：每次写完一个模块，用pylint --disable=all --enable=missing-docstring,invalid-name扫一遍代码。它不会告诉你“这里该用async”，但会标出def get_weather(city):——提醒你city参数没类型注解，而类型注解正是后续做自动校验的基础。这种机械式的提醒，比任何教程都更能培养工程直觉。

手写Agent的终点，不是写出完美代码，而是当你看到任何AI系统时，第一反应不再是“好厉害”，而是“它的Planning怎么防幻觉？Tool调用怎么熔断？Memory怎么防泄漏？Reflection怎么归因？”——这种条件反射，才是从“调包侠”到“造轮子的人”最真实的勋章。