文章目录一、为什么你需要这张地图二、先分清 5 个概念三、Agent 的 7 个核心模块一个判断标准四、三条学习路线路线 A工程落地方向路线 B研究与算法方向路线 C求职作品方向五、框架怎么选六、前 7 天实战计划Day 1建立边界Day 2手写最小 Agent LoopDay 3工具设计Day 4上下文工程Day 5评测集Day 6项目化包装Day 7复盘与简历表达一周结束后继续做什么七、高质量资源筛选清单GitHub 项目筛选教程筛选论文筛选项目是否值得写进简历8 条准则推荐优先资源列表九、常见问题解答FAQQ1我完全没接触过 LLM 编程能不能直接学 AgentQ2LangChain 和 LangGraph 到底什么关系该学哪个Q3到底什么时候该用 Agent什么时候用普通 workflow 就够了Q4没有 GPU能不能做 Agent 开发Q5学了 7 天之后如果效果不好怎么办十、总结一、为什么你需要这张地图很多人学 Agent 会卡在两个地方一是把 Agent 当成更长的 prompt二是看了一堆框架教程却没有可验证的产出。Anthropic 的工程实践给出的建议很朴素先从最简单的方案开始只有当固定 workflow 不足以覆盖任务分支时再引入更自主的 agent loop。本文目标就一个用最短路径建立 AI Agent 的全局认知并把学习推进到“能做项目、能评测、能写进简历”的程度。二、先分清 5 个概念在动手写代码之前你必须能精准区分以下几类系统——错误的概念边界会导致架构层面的偏差。概念核心特征典型例子什么时候用Chatbot单轮或多轮对话主要输出文本FAQ、客服问答任务只需要回答不需要行动Workflow固定流程LLM 是某些步骤的组件分类 → 检索 → 生成 → 审核步骤清晰、成功标准明确Agent模型自主选择下一步动作研究助手、代码修复助手任务开放需要多步探索Multi-Agent多个角色协作带协调器或消息协议研究员 编写者 审稿人单个角色职责过宽需要分工Computer-Use Agent操作浏览器、桌面、终端或文件系统WebArena、OSWorld、coding agent任务必须进入真实软件环境关键判断不要一上来就追求全自动通用 Agent。更稳的闭环是先做 workflow固定步骤再加 agent loop让模型在有限步数内决定下一步工具调用最后才考虑 multi-agent 的分工协作。三、Agent 的 7 个核心模块一个真正可交付的 Agent 系统不是接个 API 然后写个 while True 循环调用工具那么简单。你需要对以下 7 个模块有清晰的答案模块你要能回答的问题常见坑Goal任务成功是什么样失败边界是什么只写帮我完成任务没有验收标准State当前任务状态、历史、工作区文件放哪里只依赖聊天历史长任务一压缩就丢线索Context哪些信息进入模型顺序和格式是什么把所有资料塞进上下文导致干扰和成本暴涨Tools工具有哪些schema、权限、错误如何描述工具名含糊、返回值太长、没有分页和重试Loop最大步数、停止条件、反思、恢复怎么做无限循环或过早停止Guardrails哪些动作需要确认哪些输入不可信让模型自己决定安全边界Eval怎么证明它真的完成任务只有演示视频没有可重复评测集一个判断标准只要你的系统会让模型调用工具你就要同步设计评测和安全边界。没有eval的 Agent 是 demo没有权限边界的 Agent 是风险源没有trace的 Agent 很难调试。四、三条学习路线根据你的目标不同Agent 学习存在三条差异化的路线。选错路线 用研究型方法做工程交付或者用工程型方法发论文。路线 A工程落地方向目标是做出能交付的 Agent 应用。重点学LangGraph的状态、持久执行和 human-in-the-loopOpenAI Agents SDK的 handoff、guardrail、tracingPydantic AI的类型约束、结构化输出和依赖注入Promptfoo、DeepEval、Inspect这类 eval harness评测工具OWASP LLM Top 10、MCP Top 10最小权限和审计日志适合项目旅行规划 Agent、企业知识库 Agent、客服流程 Agent。路线 B研究与算法方向目标是理解 Agent 为什么成功或失败。重点学ReAct、Plan-and-Solve、Reflection、Tree Search等推理范式WebArena、OSWorld、GAIA、SWE-bench等 benchmarkTool-use 数据集、轨迹评分、LLM-as-judge 校准RAG / multimodal RAG / memory 的消融实验Agent RL、过程奖励、失败轨迹复盘适合项目论文研读 Agent、Web Agent 评测、RAG 检索策略对比。路线 C求职作品方向目标是做出能写进简历、能在面试里讲清楚的项目。重点不是用了什么框架而是用户是谁任务为什么需要 Agent工具如何设计权限如何分级上下文如何管理成本如何控制评测集怎么构造失败原因是什么项目如何部署别人能否 clone 运行适合项目projects/01-paper-agent、projects/02-travel-agent、projects/03-web-agent。五、框架怎么选市场上 Agent 框架百花齐放但每个框架都有自己的设计哲学和适用边界。下面的选型策略基于最小依赖 场景匹配原则场景首选理由学 agent loop 基础原生 API 50 行工具循环能看清 observe → act → observe复杂状态流LangGraph状态图、持久执行、恢复、人类审核都比较成熟OpenAI 生态OpenAI Agents SDKhandoff、guardrails、tracing 是一等概念类型安全 Python 应用Pydantic AIPydantic 风格结构化输出和依赖注入舒服多角色协作 demoAutoGen / CrewAI快速搭建 planner、executor、reviewer 分工数据密集 RAGLlamaIndex数据连接器、索引、检索和 workflow 生态较完整重要提示初学者不要一上来就装 LangChain / AutoGen先从原生 API 手写 loop开始这样才能真正理解 Agent 的本质。六、前 7 天实战计划这不是收藏 100 个链接的计划而是一周内做出最小 Agent 项目骨架的执行清单。Day 1建立边界目标区分 chatbot、workflow、agent、multi-agent。阅读Agent 学习地图、Anthropic: Building effective agents。产出写一页笔记你的目标项目为什么需要 Agent而不是普通 workflow。画出最小流程输入、工具、输出、失败边界。Day 2手写最小 Agent Loop目标理解 observe → think → act → observe 循环。任务只接 2 个工具search_notes(query)、write_summary(text)。限制最大 5 步。每一步写入 JSONL tracestep、thought_summary、tool、args、observation、cost_estimate。验收能处理 5 条固定任务。出错时不崩溃返回可读失败原因。# 最小 Agent Loop 示意框架非完整可运行代码# 完整示例参见 examples/ 目录importjson MAX_STEPS5defagent_loop(task:str,tools:dict,max_steps:intMAX_STEPS):trace[]context{task:task,history:[]}forstepinrange(max_steps):thoughtthink(context)# 模型推理tool_name,argsdecide(thought)# 选择工具和参数observationtools[tool_name](**args)# 执行工具trace.append({step:step,thought_summary:thought[:200],tool:tool_name,args:args,observation:observation[:500],cost_estimate:estimate_cost(thought)})ifis_task_complete(observation,task):breakwithopen(trace.jsonl,a)asf:forentryintrace:f.write(json.dumps(entry,ensure_asciiFalse)\n)returntraceDay 3工具设计目标让工具变得模型友好。阅读Anthropic: Writing effective tools for agents。任务给每个工具补名称、使用场景、参数 schema、返回结构、错误码、示例。增加分页、截断、重试和 timeout。把高风险工具标成requires_confirmation。验收工具返回不超过模型真正需要的内容。错误信息能指导下一步动作。Day 4上下文工程目标控制什么进入模型而非无脑塞入所有资料。任务把 context 分成 5 层system、task、memory、retrieved evidence、recent trace。做一个 context builder把每层内容结构化输出。对长工具结果只保留摘要和可追溯引用。验收同一任务重复运行时prompt 结构稳定。不把完整日志、完整网页、完整 PDF 直接塞进模型。Day 5评测集目标从感觉能用变成可测量。任务写 20 条 eval case10 条正常任务、5 条边界任务、5 条安全/失败任务。每条包含输入、期望行为、禁止行为、评分方式。记录通过率、平均步数、失败原因、人工修复建议。可选工具Promptfoo适合 prompt、RAG、agent 回归测试和红队测试。DeepEval适合 pytest 风格的 LLM/Agent 单元测试。Inspect适合更严肃的模型能力与安全评测。Day 6项目化包装目标让别人能 clone、运行、理解你的项目。任务写README.md项目目标、架构、安装、运行、测试、限制。写eval_report.md评测数据、失败类型、改进计划。写demo_script.md面试或路演时怎么演示。验收新机器按 README 能跑通最小 demo。面试官能从 README 看出你做的不只是 API wrapper。Day 7复盘与简历表达目标把项目变成可讲述的工程经验。任务做一次失败归因工具失败、检索失败、模型误判、权限不足、上下文污染分别占多少。写一段简历 bullet包含架构、场景、指标。简历 bullet 模板构建面向 X 场景的 Agent 系统采用 ReAct loop 工具注册表 分层 context builder接入 N 个外部工具并对高风险动作设置 human-in-the-loop设计 20 条端到端 eval case任务成功率达到 X%通过工具结果截断和模型路由将平均成本降低 X%。一周结束后继续做什么做论文方向 → 进入 Paper Agent 项目蓝图做生活/业务方向 → 进入 Travel Agent 项目蓝图做浏览器方向 → 进入 Web Agent 项目蓝图做资料型项目 → 进入多模态 RAG 资源七、高质量资源筛选清单Agent 资料非常多但真正值得花时间的资源通常有共同的信号特征可运行、可验证、可追溯、能解释失败。GitHub 项目筛选维度高质量信号低质量信号可运行性有明确安装、环境变量、demo、测试命令只有截图和口号维护状态最近仍有 commit / issue / release长期无人维护依赖版本锁死架构透明README 解释 agent loop、工具、状态、eval只写multi-agent powered by GPT工具边界工具 schema 清晰权限和错误处理明确工具直接执行任意 shell/API评测有 benchmark、eval case、失败分析只有单次 demo 成功安全有 sandbox、human approval、secret 管理要求把高权限 key 放进 prompt 或前端可复用模块化能替换模型和工具所有逻辑堆在一个 notebook教程筛选优先读这些官方文档OpenAI Agents SDK、LangGraph、Pydantic AI、MCP工程博客解释为什么这样设计而不只是贴代码可运行 cookbook有完整依赖、输入、输出和测试方式论文配套代码能复现实验或至少提供数据/脚本谨慎对待这些10 分钟实现 AutoGPT但没有失败处理生产级 Agent但没有 trace、eval、权限分级全自动赚钱/投递/下单但没有法律和安全边界只堆框架名不解释 trade-off论文筛选问题为什么重要任务定义是否清楚Agent 论文很容易把开放任务写得漂亮但不可复现环境是否可复现Web、OS、工具 API 会变化benchmark 必须控制漂移指标是否只看最终成功率还要看步数、成本、延迟、错误类型、人工介入次数是否有消融实验没有消融就很难知道是模型强还是框架设计有效是否报告失败案例Agent 的失败模式比成功样例更有学习价值是否开源代码/数据不能复现就只能当思路参考项目是否值得写进简历8 条准则满足下面 8 条中的6 条就值得继续打磨有明确用户和业务场景有至少 3 个真实工具不是 mock 全流程有可追踪 trace 或日志有 20 条以上 eval case有失败类型统计有权限/安全设计有部署或一键运行说明有对比实验比如有无 RAG、有无 rerank、有无 memory推荐优先资源列表Agent 架构Anthropic: Building effective agentsOpenAI Agents SDKLangGraphPydantic AIMicrosoft AutoGen工具与协议Model Context ProtocolOpenAI SwarmAnthropic: Writing effective tools for agents评测与安全PromptfooDeepEvalInspectOWASP Top 10 for LLM ApplicationsOWASP MCP Top 10多模态与文档处理DoclingMinerURAG-AnythingColPali paper一句话判断好资源会让你更快回答为什么这么设计、失败时怎么查、指标怎么证明差资源只会让你复制更多样板代码。九、常见问题解答FAQQ1我完全没接触过 LLM 编程能不能直接学 Agent建议先完成以下前置条件再进入 Agent 学习能调用一次 LLM API 完成单轮对话能写出带 system prompt 和 user prompt 的基础请求理解 temperature、max_tokens、function calling 等基础概念如果你还不会以上内容先去跑通一个调用 GPT/Claude API 回答问题的最小 demo然后回到本文的 Day 1。Q2LangChain 和 LangGraph 到底什么关系该学哪个LangChain 是一个高度封装的 LLM 应用框架强调用链式调用快速搭建应用。LangGraph 是 LangChain 生态下的状态图执行引擎专注解决Agent 的状态管理、持久执行和人类审核问题。如果你要做 Agent直接学 LangGraph 就好LangChain 的那套 Chain 抽象在 Agent 场景下反而容易变成阻碍。Q3到底什么时候该用 Agent什么时候用普通 workflow 就够了Anthropic 的实践指南给出了很实用的判断标准如果任务的分支逻辑是固定的如分类 → 检索 → 生成用 workflow只有当任务本身不可预测、需要模型自主探索多步时才引入 Agent loop。一个简单的自测方法你能不能提前画出任务执行的完整决策树能 → workflow不能 → 考虑 Agent。Q4没有 GPU能不能做 Agent 开发可以。Agent 开发的核心不是训练模型而是编排模型调用、管理工具执行、设计评测和安全边界。大多数练习只需要一台能调用 API 的普通电脑模型推理走云端 API 即可。Q5学了 7 天之后如果效果不好怎么办Day 7 的复盘就是为了应对这种情况。按失败类型做归因统计工具失败 → 改善工具描述、错误处理和分页检索失败 → 调整 embedding、chunk 策略、rerank模型误判 → 优化 prompt、补充 few-shot 示例权限不足 → 补 guardrail 和确认机制上下文污染 → 实现分层 context builder每一次失败归因都是一次系统性的工程进步而不是盲目的 prompt 调参。十、总结本文系统梳理了 Agent 学习的全链条概念辨析Chatbot ≠ Workflow ≠ Agent ≠ Multi-Agent ≠ Computer-Use Agent这是所有后续决策的起点。七大核心模块Goal、State、Context、Tools、Loop、Guardrails、Eval——缺任何一项你的 Agent 都只是 demo。三条学习路线工程落地能交付、研究算法能解释、求职作品能讲述选错路线会事倍功半。框架选型基础用原生 API、复杂状态用 LangGraph、OpenAI 生态用 Agents SDK、类型安全用 Pydantic AI。7 天最小闭环从概念理解到项目包装每天有明确目标和验收标准。资源筛选好资源可运行、可验证、可追溯、能解释失败烂资源只有截图和口号。后续规划按优先级补充理论、协议、安全等深水区内容。好的 Agent 工程师不是会调 LangChain API 的人而是能从场景分析、工具设计、上下文管理、评测构造和安全审计五个维度系统性思考问题的人。