一句话：从最原始的 API 调用出发，自己从零造一个 mini Agent 框架， 再切换到现代框架——学完后，无论流行什么框架你都能快速上手，知识不过时。 全程 Python + TypeScript 双语言并列，OpenAI 兼容接口可一键切换提供商。 为什么有这个教程 市面上的 Agent 教程大多有两个毛病： "先工具后原理"：上来就教你调 LangChain 的 AgentExecutor，一行代码跑起来很爽， 但出 bug 时完全不知道哪里错了。框架一旦过时，你的知识也跟着报废。 玩具示例：清一色 "Hello World Agent"，看完不会写真实的 Agent。 本教程反其道而行： 🧭 先原理后工具 先看清原理，再选择工具。 原理是不变的，工具是流动的。
目标：理解 LLM API 的核心概念，能用 Python/TypeScript 发出第一个请求并读懂返回值。 这是整个教程的地基——后续 16 章的 Agent 循环、工具调用、记忆系统全都建立在此之上。 TL;DR 30 秒速读：LLM API 就是一个 HTTP 接口，你发 messages 数组，它返回补全文本，每次调用完全独立，模型不会记住任何历史。 如果只记一件事：messages 数组里的 role（system/user/assistant）决定了"谁在说话"，system prompt 是你控制模型行为的最强杠杆。 1. LLM API 是什么？
本章是「任务助手 Agent」的第一次能力升级：从"随便聊聊"变成"精准执行任务"。 我们会用原生字符串模板（f-string / 模板字符串）手写 4 种核心 Prompt 技术， 不依赖任何第三方抽象库。 TL;DR 30 秒速读：Prompt 工程的四种核心技术是 System Prompt（定身份）、Few-shot（给示例教模式）、Chain-of-Thought（引导逐步推理）、结构化输出（强制 JSON），它们是所有 Agent 指令设计的基础。 如果只记一件事：system prompt 的优先级高于 user message，
「任务助手 Agent」获得了"手"——它能调用工具查天气、做计算、搜百科，不再只是空谈。 TL;DR 30 秒速读：LLM 本身不能执行任何代码，所谓"工具调用"是模型输出一段 JSON 指令，由你的客户端解析并执行，再把结果反馈给模型。 如果只记一件事：工具的 description 写得越清晰，模型选择工具越准确；写"处理数据"不如写"查询指定城市的当前天气，返回温度和天气状况"。 本章目标 学完本章，你将理解： 工具调用的本质：LLM 不直接执行工具，而是输出结构化指令（JSON），由客户端执行 JSON Schema
「任务助手 Agent」获得了"自主性"——从第03章的"单轮调用工具"，进化为"多步循环调工具直到完成任务"。 这是本教程的核心概念：单轮=工具调用，多轮=Agent。 TL;DR 30 秒速读：Agent 循环就是一个 for 循环，每轮让 LLM 决定下一步行动、执行工具、把结果反馈回去，直到模型不再调用工具或达到 max_steps 上限。 如果只记一件事：永远给 Agent 循环加 max_steps 上限（建议 10 到 20），没有上限的循环是生产事故的源头，一个失控 Agent
「任务助手 Agent」获得了"记忆力"——第04章的 Agent 循环每次启动都"失忆"， 本章让它能在多轮对话中记住上下文、跨会话记住用户偏好、在海量知识中检索相关信息。 TL;DR 30 秒速读：LLM 每次 API 调用完全无状态，所有"记忆"都是你在 messages 数组里手动传回去的历史，记忆系统的本质就是决定"传哪些历史、怎么传、传多少"。 如果只记一件事：对话超过 20 轮就别用纯 Buffer 了，要么用 SummaryMemory 压缩旧历史，要么用 VectorMemory 按相关性检索，否则 token
「任务助手 Agent」获得了"韧性"——从第04章的"能跑就行"，进化为"出错也能优雅恢复"。 一个生产级 Agent 与玩具 Demo 的分水岭，不在于"功能多"，而在于出错时会发生什么。 TL;DR 30 秒速读：Agent 容错的核心是区分"可重试错误"（超时、限流）和"永久错误"（认证失败、参数错误），前者用指数退避重试，后者立即失败，工具异常则反馈给 Agent 让它自我纠正。 如果只记一件事：工具抛异常时不要崩溃，把错误信息以 role=
「任务助手 Agent」获得了"思考力"——从第04章的"隐式推理"（模型在黑盒里想），进化为"显式推理" （模型把思考过程写出来：Thought → Action → Observation）。 这是经典论文 ReAct: Synergizing Reasoning and Acting in Language Models（Yao et al., 2022）提出的核心范式， 几乎所有现代 Agent 框架的"推理轨迹"都源于此。 TL;DR 30 秒速读：ReAct 让模型在每一步行动前先写出思考过程（Thought → Action → Observation），分&
「任务助手 Agent」获得了"战略眼光"——从第07章的"边想边做"（ReAct 一步一步线性推进）， 进化为"先规划全局、再分步执行、执行完还要反思改进"。 这是让 Agent 能处理复杂、多阶段任务的关键能力。 TL;DR 30 秒速读：Plan-and-Execute 让 Agent 先把任务分解成步骤列表（用 response_format=json_object 强制结构化输出），再逐步执行，最后汇总结果；Reflection 让 Agent 审视自己的输出并改进。 如果只记一件事：用 response_format={"type&
「任务助手 Agent」获得了"查资料"的能力——前几章的 Agent 只能用模型自带的知识回答， 本章让它能在外部知识库中检索相关信息，再基于检索结果生成准确的回答。 这是让 Agent 处理私有数据、最新信息的核心能力。 TL;DR 30 秒速读：RAG 通过"检索相关文档片段 → 注入 prompt → 模型基于片段回答"三步管道，让 Agent 能引用外部知识库而非凭记忆猜测；Agentic RAG 把检索变成工具，让 Agent 自主决定是否检索、检索几次。 如果只记一件事：分块策略决定检索质量——chunk_size=200-500 字符、overlap=50-100 字符是中文文档的经验值，
「任务助手 Agent」从"孤胆英雄"变成了"团队"——不再是一个 Agent 硬扛所有事， 而是让多个专门化的 Agent 分工协作：一个当 Supervisor（调度）、几个当 Worker（干活）， 遇到超出自己能力范围的问题还能 Handoff（转交）给更专业的同事。 TL;DR 30 秒速读：多 Agent 用 Supervisor-Worker 模式分工协作（Supervisor 分派任务、Worker 执行）和 Handoff 模式转交对话（客服 → 技术专家），但最大的陷阱是"用早了"——大多数任务单
Prompt 工程的进化——当 Agent 动辄调用几十次工具、跑上百步循环时，"写好一个 prompt"已经不够了。 真正决定 Agent 质量的，是你如何管理喂给模型的上下文：压缩什么、隔离什么、为每次调用分配多少 token 预算。 这就是 2025 年后兴起的「上下文工程」。 TL;DR 30 秒速读：上下文工程通过压缩（超阈值摘要旧轨迹）、子 Agent 隔离（只收回摘要不看全量轨迹）、Token 预算管理（主动控制上下文长度）三大支柱，解决长任务 Agent 的成本爆炸和质量衰退问题。 如果只记一件事：上下文窗口是"上限"不是"推荐用量"
AI Agent 教程
「任务助手 Agent」长出骨架了——从第01–11章散落在各文件里的函数和字典，被抽象成 6 个有清晰边界的组件接口。本章只画图纸（定义 Protocol/ABC/interface），第13章才浇筑混凝土（实现）。 学完本章，你打开 LangChain、OpenAI Agents SDK、Pydantic AI、Mastra、Vercel AI SDK 的源码， 会发现它们底层都在做同一件事：把这 6 块拼起来。 TL;DR 30 秒速读：所有 Agent 框架的底层都是 6 个组件——AgentRunner（循环引擎）、ToolRegistry（工具注册表）、LLMClient（模型包装器）、Memory（记忆管理）、ActionParser（
AI Agent 教程
「任务助手 Agent」的骨架有了血肉——第12章画好的 6 块接口图纸， 本章浇筑成能真正跑起来的 mini Agent 框架。你会亲手实现 6 个组件类， 用依赖注入组装它们，然后运行一个"查天气 + 算温差"的多步 Agent。 没有 LangChain，没有 AutoGen，只有你自己的代码——学完后，任何框架的源码 你都能在一小时内看懂。 TL;DR 30 秒速读：把第12章的 6 个接口 Protocol/interface 逐一写成可运行的实现类，用依赖注入组装成一个完整的 mini Agent 框架，跑通"查天气 + 算温差"的多步循环。 如果只记一件事：
AI Agent 教程
「任务助手 Agent」从教学玩具走向生产可用——第13章你造的 6 大组件框架， 本章给它装上 3 个生产级特性：流式输出（用户不再盯着空白等）、 结构化输出强制（LLM 输出 100% 符合 schema）、工具参数校验 （在执行前拦截非法参数）。最后对比 OpenAI Agents SDK / Pydantic AI / Mastra 如何用更少代码完成同样的事——理解原理后，你打开任何框架源码都能 1 小时看懂。 TL;DR 30 秒速读：给第13章的 mini 框架装上流式输出、结构化输出强制、工具参数校验三个生产级特性，然后对比 OpenAI Agents SDK / Pydantic AI / Vercel AI SDK 如何用一行代码搞定你
AI Agent 教程
「任务助手 Agent」上线前最后一道关——你怎么知道你的 Agent "好不好"？ 不是靠感觉，而是靠可量化的评估。本章教你三种评估手段：行为测试 （断言 Agent 走对了流程）、LLM-as-Judge（用模型给输出打分）、回归测试 （防止升级模型后行为退化）。学完本章，你能给 Agent 建一套"体检套餐"， 每次改动都跑一遍，坏行为立即报警。 TL;DR 30 秒速读：评估 Agent 和评估模型完全不同，你需要测行为轨迹（调了哪些工具、走了什么流程），而不只是测最终输出。本章教三种手段：行为测试、LLM-as-Judge 打分、回归测试套件。 如果只记一件事：只测输出会漏掉&
AI Agent 教程
「任务助手 Agent」装上黑匣子了——第12章的 Observer 组件，本章给它接上真正的"飞行记录仪"。 你将学会用 Tracing（链路追踪） 记录每一步 LLM 调用和工具调用、用结构化日志 让机器可读、用成本追踪算清每次查询花了多少钱。学完本章，你的 Agent 不再是一个 "出了 bug 不知道为什么"的黑盒，而是一个每一步都可追溯、可复盘、可优化的透明系统。 TL;DR 30 秒速读：给 Agent 装上"飞行记录仪"——用 TraceCollector 记录每一步 LLM 调用和工具调用的树状链路，用 CostTracker 按
AI Agent 教程
「任务助手 Agent」获得了"免疫系统"——从第06章的"基础输入/输出校验"，进化为 一套纵深防御体系。一个能上线的 Agent，不是"功能够多"，而是"攻击者打不穿"。 这是 Part 6（生产化）的收官章。前面你学会了评估（第15章）和可观测（第16章）， 现在我们要回答最后一个生产化问题：当 Agent 暴露在充满恶意的真实世界，它怎么活下来？ TL;DR 30 秒速读：Agent 面临四大安全威胁（Prompt 注入、数据泄露、工具滥用、不安全输出），本章实现四道防线（注入检测、
AI Agent 教程
本表汇总教程 17 章的核心 API 和模式，A4 打印友好。 1. LLM API 调用 # OpenAI 兼容（Python） from openai import OpenAI client = OpenAI(api_key="sk-xxx") response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是任务助手"
News
This is zhangsheng, a brand new site by zhangsheng that's just getting started. Things will be up and running here shortly, but you can subscribe in the meantime if you'd like to stay up to date and receive emails when new content is published!