{
  "metadata": {
    "id": "ch01",
    "title": "第1章：什么是AI Agent",
    "volume": "vol1",
    "volume_title": "认知篇",
    "word_count": 7226,
    "difficulty": "beginner",
    "prerequisites": [],
    "key_concepts": [
      "Agent的定义",
      "一个直观的定义",
      "学术视角的定义",
      "实践中的定义",
      "Agent的核心特征",
      "四大核心能力",
      "一个关键区分：Agent vs. 自动化",
      "Agent与传统软件的区别",
      "范式转换",
      "一个对比示例",
      "设计哲学的差异",
      "何时用传统软件，何时用Agent",
      "Agent与Chatbot的区别",
      "核心区别",
      "一个直观的比喻"
    ],
    "learning_objectives": [],
    "estimated_tokens": 4336,
    "source_file": "vol1/ch01_什么是AI_Agent.md"
  },
  "overview": "如果你正在读这本书，你很可能已经听说过\"AI Agent\"这个词。它出现在技术博客的标题里，出现在产品发布会的PPT上，出现在风投的投资主题中。但当你试图精确定义它时，可能会发现每个人说的\"Agent\"似乎不是同一个东西。\n\n本章的目标很明确：**给AI Agent一个清晰的、可操作的定义**。我们不会止步于抽象概念——你会看到代码，看到架构，看到真实的判断标准。读完本章，你应该能够：\n\n- 准确判断一个系统是否是Agent\n- 理解Agent与Chatbot、传统软件的本质区别\n- 选择合适的Agent类型来解决实际问题\n- 对Agent的能力和局限有清醒的认知\n\n让我们开始。\n\n---",
  "sections": [
    {
      "id": "1.1",
      "title": "1.1 Agent的定义",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "1.1.1",
          "title": "1.1.1 一个直观的定义",
          "content": "先给一个最直观的定义：\n\n> **AI Agent（智能体）是一个能够感知环境、进行推理决策、执行动作以实现目标的自治系统。**\n\n这个定义里有五个关键词，每一个都值得展开：\n\n| 关键词 | 含义 | 例子 |\n|--------|------|------|\n| **感知（Perception）** | 从环境中获取信息 | 读取用户消息、查询数据库、调用API |\n| **推理（Reasoning）** | 基于感知到的信息进行分析和决策 | 分析意图、制定计划、评估选项 |\n| **执行（Action）** | 在环境中产生实际影响 | 发送邮件、修改文件、调用工具 |\n| **目标（Goal）** | 有明确的预期结果 | \"帮用户订机票\"、\"完成代码审查\" |\n| **自治（Autonomy）** | 在一定范围内自主决策，不需要每步都由人指定 | Agent自己决定先查数据库还是先问用户 |\n\n这五个要素构成了Agent的\"灵魂\"。缺少任何一个，系统就会退化成其他东西：\n\n- 缺少**执行** → 变成分析系统（Analytics System）\n- 缺少**推理** → 变成自动化脚本（RPA Script）\n- 缺少**感知** → 变成定时任务（Cron Job）\n- 缺少**目标** → 变成随机行为系统\n- 缺少**自治** → 变成命令行工具（CLI Tool）"
        },
        {
          "id": "1.1.2",
          "title": "1.1.2 学术视角的定义",
          "content": "在学术界，Stuart Russell 和 Peter Norvig 在《人工智能：一种现代方法》中将智能体定义为：\n\n> \"An agent is anything that can be viewed as perceiving its environment through sensors and acting upon that environment through actuators.\"\n\n翻译过来就是：**Agent是通过传感器感知环境、通过执行器作用于环境的任何实体。**\n\n这个定义更加宽泛，它甚至可以涵盖恒温器这样的简单系统。但在本书的语境中，当我们说\"AI Agent\"时，通常指的是**基于大语言模型（LLM）的、具有较强推理能力的智能体**。"
        },
        {
          "id": "1.1.3",
          "title": "1.1.3 实践中的定义",
          "content": "在实际工程中，我倾向于使用一个更务实的工作定义：\n\n> **AI Agent = LLM + 工具（Tools）+ 记忆（Memory）+ 规划（Planning）**\n\n这个公式虽然简化了很多细节，但它抓住了当前Agent系统的核心技术栈：\n\n\n这个代码框架虽然简单，但它揭示了Agent编程的核心循环：**感知 → 推理 → 执行 → 再感知 → ...**，直到目标达成。\n\n---"
        }
      ]
    },
    {
      "id": "1.2",
      "title": "1.2 Agent的核心特征",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "1.2.1",
          "title": "1.2.1 四大核心能力",
          "content": "基于前面的定义，我们可以提炼出Agent的四大核心能力：\n\n#### （1）自主决策能力（Autonomy）\n\n传统软件是\"指令-执行\"模式：你告诉它做什么，它就做什么。Agent则不同——你告诉它**目标**，它自己决定**怎么做**。\n\n\n这种自主性的程度是可调的。你可以给Agent很大自由度，也可以通过约束来限制它的决策空间。\n\n#### （2）工具使用能力（Tool Use）\n\nAgent最强大的能力之一是**调用外部工具**。纯LLM只能在文本世界里工作，而Agent可以：\n\n- 查询数据库\n- 调用API\n- 执行代码\n- 操作文件系统\n- 发送网络请求\n- 控制浏览器\n\n\n工具使用将Agent从\"能说不能做\"的聊天机器人变成了\"既说又做\"的数字员工。\n\n#### （3）记忆能力（Memory）\n\n没有记忆的Agent就像金鱼——每次对话都从零开始。真正的Agent需要不同层级的记忆：\n\n\n\n#### （4）学习能力（Learning）\n\n最前沿的Agent不仅仅是执行预设任务，它们还能从经验中学习：\n\n- **从反馈中学习**：根据用户的肯定/否定调整行为\n- **从错误中学习**：记住失败的尝试，避免重复犯错\n- **从模式中学习**：总结规律，形成更好的策略"
        },
        {
          "id": "1.2.2",
          "title": "1.2.2 一个关键区分：Agent vs. 自动化",
          "content": "很多人容易把Agent和自动化混淆。它们的核心区别在于：\n\n| 维度 | 自动化（Automation） | Agent |\n|------|---------------------|-------|\n| **决策方式** | 预定义的规则/流程 | 基于推理的动态决策 |\n| **适应性** | 输入变化时可能失败 | 能处理预期之外的情况 |\n| **工具选择** | 硬编码的工具链 | 根据需要动态选择工具 |\n| **错误处理** | 预定义的异常处理 | 能推理出新的处理方式 |\n| **上限** | 设计者预设的所有场景 | 受限于LLM的能力边界 |\n\n\n---"
        }
      ]
    },
    {
      "id": "1.3",
      "title": "1.3 Agent与传统软件的区别",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "1.3.1",
          "title": "1.3.1 范式转换",
          "content": "Agent编程代表着一次根本性的范式转换。理解这种转换，是掌握Agent编程的前提。\n\n传统软件开发的范式是**确定性的**：\n\n\n同样的输入永远产生同样的输出。你可以精确预测程序的每一步行为。\n\nAgent开发的范式是**概率性的**：\n\n\n同样的输入可能产生不同的行动方案。你只能约束Agent的行为范围，但不能精确预测每一步。"
        },
        {
          "id": "1.3.2",
          "title": "1.3.2 一个对比示例",
          "content": "让我们通过一个具体任务来感受这种差异——**\"帮用户预订明天从北京到上海的机票\"**。\n\n**传统软件开发方式：**\n\n\n**Agent方式：**\n\n\n关键区别在于：传统软件中，每一个if-else都需要开发者预先想到；而Agent能够根据当前情况**自主推理**出合理的处理方式。"
        },
        {
          "id": "1.3.3",
          "title": "1.3.3 设计哲学的差异",
          "content": "| 维度 | 传统软件 | Agent |\n|------|---------|-------|\n| **核心问题** | \"如何做\"（How） | \"做什么\"（What） |\n| **开发者角色** | 实现每一步逻辑 | 定义目标和约束 |\n| **错误处理** | 预定义所有错误场景 | 自适应处理异常 |\n| **测试方式** | 确定性测试（断言精确输出） | 评估性测试（判断结果质量） |\n| **可预测性** | 高（相同输入→相同输出） | 低（但可通过约束提高） |\n| **适应性** | 需要修改代码 | 可以通过调整提示词 |"
        },
        {
          "id": "1.3.4",
          "title": "1.3.4 何时用传统软件，何时用Agent",
          "content": "不是所有问题都适合用Agent解决。以下是一些判断标准：\n\n**适合用Agent的场景：**\n- 任务涉及多步骤的复杂推理\n- 需要根据上下文灵活调整策略\n- 输入格式不固定或需要自然语言理解\n- 边界情况太多，无法穷举\n- 需要\"理解\"语义而非简单匹配\n\n**适合用传统软件的场景：**\n- 性能要求极高（如高频交易）\n- 需要确定性保证（如金融计算）\n- 逻辑规则清晰且稳定\n- 对延迟极其敏感\n- 涉及安全关键决策（需人工兜底）\n\n**最佳实践：混合架构**\n\n大多数生产级系统不是纯Agent或纯传统软件，而是混合架构：\n\n\n---"
        }
      ]
    },
    {
      "id": "1.4",
      "title": "1.4 Agent与Chatbot的区别",
      "level": 2,
      "content": "这是最常见的一个混淆。很多人把加了几条工具的Chatbot叫做Agent，但实际上它们有本质区别。",
      "subsections": [
        {
          "id": "1.4.1",
          "title": "1.4.1 核心区别",
          "content": "| 维度 | Chatbot | Agent |\n|------|---------|-------|\n| **交互模式** | 对话式，你来我往 | 目标驱动，持续工作 |\n| **主动性** | 被动等待输入 | 主动规划和执行 |\n| **持久性** | 对话结束即终止 | 可以长时间运行、跨会话 |\n| **工具使用** | 可能调用少量工具 | 深度集成多种工具 |\n| **状态管理** | 无状态或简单状态 | 复杂状态追踪 |\n| **输出类型** | 文本回复为主 | 可以执行任意操作 |"
        },
        {
          "id": "1.4.2",
          "title": "1.4.2 一个直观的比喻",
          "content": "- **Chatbot**像一个坐在柜台后的咨询员——你问一个问题，他回答一个问题。你走了，他就休息了。\n- **Agent**像一个项目经理——你给他一个目标，他自己规划、协调资源、解决问题，直到完成目标。"
        },
        {
          "id": "1.4.3",
          "title": "1.4.3 代码对比",
          "content": ""
        },
        {
          "id": "1.4.4",
          "title": "1.4.4 演化路径",
          "content": "值得注意的是，Chatbot和Agent不是非此即彼的关系。很多系统是逐步从Chatbot演化成Agent的：\n\n\n理解这个演化路径很重要，因为它告诉我们：**不需要一步到位地构建完整Agent，可以渐进式地增强现有系统。**\n\n---"
        }
      ]
    },
    {
      "id": "1.5",
      "title": "1.5 Agent的分类体系",
      "level": 2,
      "content": "Agent是一个很大的概念，不同类型的Agent适用于不同的场景。建立清晰的分类体系有助于我们选择合适的方案。",
      "subsections": [
        {
          "id": "1.5.1",
          "title": "1.5.1 按自主程度分类",
          "content": "#### 反应式Agent（Reactive Agent）\n\n最简单的Agent，直接根据输入做出反应，没有内部状态和复杂的推理。\n\n\n适用场景：简单的分类、路由、格式转换。\n\n#### 慎思式Agent（Deliberative Agent）\n\n具有内部状态和推理能力的Agent，会在行动前进行\"思考\"。\n\n\n适用场景：需要多步推理的复杂任务。\n\n#### 混合式Agent（Hybrid Agent）\n\n结合反应式和慎思式的优点——对简单情况快速反应，对复杂情况深入思考。\n\n\n这是目前生产环境中最常用的Agent架构。"
        },
        {
          "id": "1.5.2",
          "title": "1.5.2 按功能类型分类",
          "content": "| 类型 | 描述 | 典型例子 |\n|------|------|----------|\n| **信息获取型** | 搜索、检索、汇总信息 | 搜索助手、研究助手 |\n| **内容生成型** | 创建文本、图像、代码 | 写作助手、代码助手 |\n| **决策支持型** | 分析数据、提供建议 | 数据分析Agent、投资顾问 |\n| **操作执行型** | 执行具体操作 | 邮件管理Agent、文件管理Agent |\n| **协调管理型** | 协调多个Agent或人 | 项目管理Agent、工作流编排Agent |"
        },
        {
          "id": "1.5.3",
          "title": "1.5.3 按部署形态分类",
          "content": "| 形态 | 特点 | 适用场景 |\n|------|------|----------|\n| **独立Agent** | 单个Agent独立工作 | 简单任务、个人助手 |\n| **嵌入式Agent** | 集成到现有应用中 | 增强现有产品功能 |\n| **多Agent系统** | 多个Agent协作完成复杂任务 | 复杂工作流、企业级系统 |\n| **Agent平台** | 提供Agent创建和管理能力 | Agent开发平台、SaaS |"
        },
        {
          "id": "1.5.4",
          "title": "1.5.4 按LLM依赖程度分类",
          "content": "这个分类在工程实践中特别重要，因为它直接影响到系统的成本、延迟和可靠性：\n\n| 类型 | LLM依赖 | 特点 | 适用场景 |\n|------|---------|------|----------|\n| **LLM-Heavy** | 高 | 推理、规划都依赖LLM | 创意任务、开放域任务 |\n| **LLM-Light** | 低 | LLM只做意图识别，执行用传统代码 | 结构化任务、高频任务 |\n| **LLM-Free** | 无 | 纯规则驱动 | 超低延迟、确定性要求高 |\n\n\n**工程建议**：在生产环境中，尽可能降低对LLM的依赖。LLM调用是系统中成本最高、延迟最大、可靠性最低的部分。能用传统代码解决的，就不要用LLM。\n\n---"
        }
      ]
    },
    {
      "id": "1.6",
      "title": "1.6 典型应用场景",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "1.6.1",
          "title": "1.6.1 客服自动化",
          "content": "这是目前Agent应用最广泛的场景之一。"
        },
        {
          "id": "1.6.2",
          "title": "1.6.2 代码开发助手",
          "content": "程序员可能是最早也是最活跃的Agent用户群体。"
        },
        {
          "id": "1.6.3",
          "title": "1.6.3 数据分析",
          "content": "Agent特别擅长处理探索性的数据分析任务——因为这类任务需要根据中间结果不断调整分析方向。"
        },
        {
          "id": "1.6.4",
          "title": "1.6.4 工作流自动化",
          "content": "---"
        }
      ]
    },
    {
      "id": "1.7",
      "title": "1.7 Agent的局限性与挑战",
      "level": 2,
      "content": "在热情拥抱Agent技术的同时，我们也必须清醒地认识到它当前面临的局限。",
      "subsections": [
        {
          "id": "1.7.1",
          "title": "1.7.1 幻觉问题（Hallucination）",
          "content": "LLM会\"一本正经地胡说八道\"，Agent也不例外。当Agent基于错误的信息做出决策时，后果可能比Chatbot更严重——因为它不仅仅是说错话，还可能执行错误的操作。\n\n\n**缓解策略**：\n- 关键操作前要求人工确认\n- 对Agent的输出进行交叉验证\n- 限制Agent在安全沙箱中执行操作"
        },
        {
          "id": "1.7.2",
          "title": "1.7.2 成本问题",
          "content": "每次LLM调用都是有成本的。一个复杂的Agent任务可能需要多次LLM调用（推理、规划、工具选择、参数生成、结果总结），成本可能快速累积。"
        },
        {
          "id": "1.7.3",
          "title": "1.7.3 可靠性和可预测性",
          "content": "Agent的行为是概率性的，这意味着：\n- 同样的输入可能产生不同的输出\n- 某些操作可能偶尔失败\n- 行为模式可能随着模型更新而变化"
        },
        {
          "id": "1.7.4",
          "title": "1.7.4 安全性",
          "content": "Agent具有执行能力，这意味着如果被恶意利用，后果可能很严重。需要特别注意：\n\n- **提示注入攻击**：通过精心构造的输入控制Agent行为\n- **权限控制**：限制Agent能执行的操作范围\n- **审计追踪**：记录Agent的所有操作\n\n\n---"
        }
      ]
    },
    {
      "id": "最佳实践",
      "title": "最佳实践",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "1. 从小处开始",
          "title": "1. 从小处开始",
          "content": "不要一上来就试图构建一个全能的Agent。从一个功能明确、范围有限的小Agent开始："
        },
        {
          "id": "2. 明确定义Agent的边界",
          "title": "2. 明确定义Agent的边界",
          "content": "Agent不是万能的。明确它能做什么、不能做什么，比让它\"尽量做到最好\"更重要："
        },
        {
          "id": "3. 设计好\"人的回路\"（Human-i",
          "title": "3. 设计好\"人的回路\"（Human-in-the-Loop）",
          "content": "让Agent在关键决策节点请人确认，而不是完全自主："
        },
        {
          "id": "4. 为Agent设计完善的可观测性",
          "title": "4. 为Agent设计完善的可观测性",
          "content": "你无法优化你看不见的东西。Agent的决策过程必须可追踪："
        },
        {
          "id": "5. 选择合适的自主程度",
          "title": "5. 选择合适的自主程度",
          "content": "不是所有Agent都需要高度自治。根据场景选择合适的自主程度：\n\n\n---"
        }
      ]
    },
    {
      "id": "常见陷阱",
      "title": "常见陷阱",
      "level": 2,
      "content": "",
      "subsections": [
        {
          "id": "陷阱1：把Chatbot包装成Agent",
          "title": "陷阱1：把Chatbot包装成Agent",
          "content": "很多人在Chatbot上加了几个API调用就宣称它是Agent。真正的Agent需要**持续的、目标驱动的**工作能力，而不是一问一答。\n\n**判断标准**：如果去掉LLM后，你的系统退化为一个简单的API路由器，那它可能还不是一个Agent。"
        },
        {
          "id": "陷阱2：过度依赖LLM",
          "title": "陷阱2：过度依赖LLM",
          "content": "把所有逻辑都塞给LLM，导致成本高、延迟大、不可控。"
        },
        {
          "id": "陷阱3：忽视边界情况",
          "title": "陷阱3：忽视边界情况",
          "content": "Agent的\"创造力\"是一把双刃剑——它可能在边界情况下做出意想不到的事情。\n\n**建议**：\n- 为Agent设计明确的操作白名单\n- 在沙箱环境中充分测试\n- 实现操作审计和回滚机制"
        },
        {
          "id": "陷阱4：忽视上下文窗口限制",
          "title": "陷阱4：忽视上下文窗口限制",
          "content": "LLM有上下文窗口大小的限制。如果你的Agent需要处理大量信息，需要设计好上下文管理策略："
        },
        {
          "id": "陷阱5：缺乏评估体系",
          "title": "陷阱5：缺乏评估体系",
          "content": "Agent的行为是概率性的，如果没有系统化的评估方法，你无法知道它到底做得好不好。\n\n**建议**：\n- 建立评测数据集\n- 定义明确的评估指标\n- 实现自动化评测流水线\n- 持续跟踪Agent的表现\n\n---"
        }
      ]
    },
    {
      "id": "小结",
      "title": "小结",
      "level": 2,
      "content": "让我们回顾一下本章的核心内容：\n\n1. **Agent的定义**：能够感知环境、推理决策、执行动作以实现目标的自治系统。在实践中，Agent = LLM + 工具 + 记忆 + 规划。\n\n2. **四大核心能力**：自主决策、工具使用、记忆、学习。这四项能力的组合程度决定了Agent的复杂度。\n\n3. **与传统软件的区别**：从\"如何做\"到\"做什么\"的范式转换。Agent不是替代传统软件，而是与之互补。\n\n4. **与Chatbot的区别**：Chatbot是对话式的，Agent是目标驱动的。但两者之间存在演化路径。\n\n5. **分类体系**：按自主程度（反应式/慎思式/混合式）、功能类型、部署形态、LLM依赖程度进行分类。\n\n6. **应用场景**：客服自动化、代码开发、数据分析、工作流自动化是目前最成熟的场景。\n\n7. **局限性**：幻觉、成本、可靠性、安全性是当前Agent技术面临的核心挑战。\n\n理解这些概念是后续深入学习和实践的基础。在接下来的章节中，我们将回顾Agent技术是如何一步步走到今天的，然后深入探讨Agent编程的具体范式。\n\n---",
      "subsections": []
    },
    {
      "id": "延伸阅读",
      "title": "延伸阅读",
      "level": 2,
      "content": "1. **经典文献**\n   - Russell, S. & Norvig, P. (2020). *Artificial Intelligence: A Modern Methods* (4th ed.) — 第2章对Agent有深入讨论\n   - Wooldridge, M. (2009). *An Introduction to MultiAgent Systems* — 多Agent系统入门经典\n\n2. **大语言模型时代的Agent**\n   - Wang, L. et al. (2024). *A Survey on Large Language Model Based Autonomous Agents* — LLM Agent的全面综述\n   - Schick, T. et al. (2024). *Toolformer: Language Models Can Teach Themselves to Use Tools* — 工具增强LLM的开创性工作\n\n3. **实践资源**\n   - OpenAI Cookbook (github.com/openai/openai-cookbook) — 包含大量Agent实现的示例代码\n   - LangChain Documentation (python.langchain.com) — 主流Agent框架的文档\n\n4. **值得关注的Agent项目**\n   - AutoGPT — 最早的自主Agent实验之一\n   - BabyAGI — 展示Agent任务分解能力的最小实现\n   - CrewAI — 多Agent协作框架\n   - Microsoft AutoGen — 微软的多Agent框架\n\n---\n\n*上一篇 → [卷索引](./vol1_index.md) | 下一篇 → [第2章：Agent技术演进史](./ch02_Agent技术演进史.md)*",
      "subsections": []
    }
  ],
  "code_blocks": [
    {
      "id": "code-1",
      "language": "python",
      "description": "这个公式虽然简化了很多细节，但它抓住了当前Agent系统的核心技术栈：",
      "code": "# 一个最小Agent的抽象模型\nclass MinimalAgent:\n    def __init__(self, llm, tools, memory):\n        self.llm = llm          # 大脑：推理引擎\n        self.tools = tools       # 手：执行能力\n        self.memory = memory     # 记忆：上下文和经验\n        self.goal = None         # 目标：待完成任务\n    \n    def perceive(self, input_data):\n        \"\"\"感知：接收环境信息\"\"\"\n        self.memory.add(\"user_input\", input_data)\n    \n    def reason(self):\n        \"\"\"推理：基于LLM进行思考和规划\"\"\"\n        context = self.memory.get_relevant()\n        plan = self.llm.generate(\n            system=\"你是一个有帮助的AI Agent。\",\n            context=context,\n            goal=self.goal,\n            available_tools=self.tools.list()\n        )\n        return plan\n    \n    def act(self, plan):\n        \"\"\"执行：按照计划调用工具\"\"\"\n        for step in plan.steps:\n            if step.is_tool_call:\n                result = self.tools.call(step.tool_name, step.args)\n                self.memory.add(\"tool_result\", result)\n            else:\n                self.memory.add(\"thought\", step.content)\n    \n    def run(self, goal, input_data):\n        \"\"\"Agent的主循环\"\"\"\n        self.goal = goal\n        self.perceive(input_data)\n        while not self.is_goal_achieved():\n            plan = self.reason()\n            self.act(plan)\n        return self.get_result()",
      "section_ref": "1.1.3",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-2",
      "language": "python",
      "description": "传统软件是\"指令-执行\"模式：你告诉它做什么，它就做什么。Agent则不同——你告诉它目标，它自己决定怎么做。",
      "code": "# 传统软件：指定每一步\ndef traditional_approach():\n    emails = fetch_emails()        # 第一步\n    important = filter(emails)     # 第二步\n    summaries = summarize(important)  # 第三步\n    send_report(summaries)         # 第四步\n\n# Agent方式：只指定目标\nagent.run(\n    goal=\"帮我整理今天的重要邮件并发送摘要报告\",\n    input_data={\"user\": \"zhangsan\"}\n)\n# Agent会自己决定：\n# 1. 先查看哪些邮件是重要的\n# 2. 是否需要查看日历来判断\"重要\"的标准\n# 3. 报告的格式和详细程度\n# 4. 发送给谁",
      "section_ref": "1.2.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-3",
      "language": "python",
      "description": "- 控制浏览器",
      "code": "# Agent可以调用的工具示例\ntools = [\n    Tool(\n        name=\"search_web\",\n        description=\"搜索互联网获取最新信息\",\n        parameters={\n            \"query\": {\"type\": \"string\", \"description\": \"搜索关键词\"}\n        }\n    ),\n    Tool(\n        name=\"execute_python\",\n        description=\"执行Python代码并返回结果\",\n        parameters={\n            \"code\": {\"type\": \"string\", \"description\": \"要执行的Python代码\"}\n        }\n    ),\n    Tool(\n        name=\"query_database\",\n        description=\"查询公司内部数据库\",\n        parameters={\n            \"sql\": {\"type\": \"string\", \"description\": \"SQL查询语句\"},\n            \"database\": {\"type\": \"string\", \"description\": \"数据库名称\"}\n        }\n    )\n]\n\n# Agent会根据任务需要，自主选择和组合使用这些工具",
      "section_ref": "1.2.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-4",
      "language": "text",
      "description": "没有记忆的Agent就像金鱼——每次对话都从零开始。真正的Agent需要不同层级的记忆：",
      "code": "┌─────────────────────────────────────────┐\n│           长期记忆 (Long-term Memory)     │\n│  用户偏好、历史知识、学到的经验            │\n│  存储：向量数据库 / 知识图谱               │\n├─────────────────────────────────────────┤\n│           工作记忆 (Working Memory)        │\n│  当前任务的上下文、中间状态                │\n│  存储：对话历史 / 状态变量                 │\n├─────────────────────────────────────────┤\n│           短期记忆 (Short-term Memory)     │\n│  当前轮次的输入                            │\n│  存储：当前消息 / 函数返回值               │\n└─────────────────────────────────────────┘",
      "section_ref": "1.2.1",
      "runnable": false,
      "dependencies": []
    },
    {
      "id": "code-5",
      "language": "python",
      "description": "└─────────────────────────────────────────┘",
      "code": "# 三层记忆的实现示例\nclass AgentMemory:\n    def __init__(self):\n        self.short_term = []          # 当前对话的最近N轮\n        self.working = {}             # 当前任务的上下文\n        self.long_term = VectorStore() # 持久化知识\n    \n    def remember_user_preference(self, key, value):\n        \"\"\"记住用户偏好（长期记忆）\"\"\"\n        self.long_term.upsert(\n            id=f\"pref_{key}\",\n            content=f\"用户偏好: {key} = {value}\",\n            metadata={\"type\": \"preference\", \"key\": key}\n        )\n    \n    def recall_relevant(self, query, top_k=5):\n        \"\"\"回忆与当前场景相关的信息\"\"\"\n        return self.long_term.search(query, top_k=top_k)\n    \n    def update_working_state(self, key, value):\n        \"\"\"更新工作状态\"\"\"\n        self.working[key] = value\n    \n    def add_exchange(self, role, content):\n        \"\"\"添加对话交换到短期记忆\"\"\"\n        self.short_term.append({\"role\": role, \"content\": content})\n        # 保持短期记忆窗口\n        if len(self.short_term) > 20:\n            self.short_term = self.short_term[-20:]",
      "section_ref": "1.2.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-6",
      "language": "python",
      "description": "- 从模式中学习：总结规律，形成更好的策略",
      "code": "class LearningAgent(MinimalAgent):\n    def __init__(self, llm, tools, memory):\n        super().__init__(llm, tools, memory)\n        self.experience_log = []  # 经验日志\n    \n    def learn_from_feedback(self, feedback):\n        \"\"\"从用户反馈中学习\"\"\"\n        experience = {\n            \"task\": self.goal,\n            \"actions_taken\": self.get_action_history(),\n            \"outcome\": feedback,\n            \"timestamp\": datetime.now()\n        }\n        self.experience_log.append(experience)\n        \n        # 将经验转化为长期记忆\n        if feedback == \"positive\":\n            self.memory.long_term.upsert(\n                id=f\"success_{self.goal}\",\n                content=f\"任务 '{self.goal}' 的成功策略: {self.summarize_strategy()}\",\n                metadata={\"type\": \"success_strategy\"}\n            )\n        else:\n            self.memory.long_term.upsert(\n                id=f\"failure_{self.goal}\",\n                content=f\"任务 '{self.goal}' 的失败教训: {feedback}\",\n                metadata={\"type\": \"failure_lesson\"}\n            )\n    \n    def plan_with_experience(self):\n        \"\"\"规划时参考历史经验\"\"\"\n        relevant_experiences = self.memory.recall_relevant(self.goal)\n        enhanced_context = f\"\"\"\n        历史相关经验:\n        {format_experiences(relevant_experiences)}\n        \n        当前任务: {self.goal}\n        \"\"\"\n        return self.llm.generate(context=enhanced_context)",
      "section_ref": "1.2.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-7",
      "language": "python",
      "description": "| 上限 | 设计者预设的所有场景 | 受限于LLM的能力边界 |",
      "code": "# 自动化：硬编码的邮件处理流程\ndef automated_email_handler(email):\n    if email.subject.contains(\"urgent\"):\n        send_sms(email.content)\n    elif email.subject.contains(\"invoice\"):\n        save_to_accounting(email)\n    else:\n        archive(email)\n    # 遇到\"稍微紧急但不是urgent\"的邮件？无法处理\n\n# Agent：基于理解的邮件处理\nagent.run(\n    goal=\"处理收到的邮件\",\n    input={\"email\": email}\n)\n# Agent能理解：\n# - \"ASAP\" 和 \"urgent\" 是类似的意思\n# - 这封发票可能是诈骗邮件\n# - 用户之前说过不关心某类通知",
      "section_ref": "1.2.2",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-8",
      "language": "text",
      "description": "传统软件开发的范式是确定性的：",
      "code": "输入 → [确定性的处理逻辑] → 输出",
      "section_ref": "1.3.1",
      "runnable": false,
      "dependencies": []
    },
    {
      "id": "code-9",
      "language": "text",
      "description": "Agent开发的范式是概率性的：",
      "code": "输入 + 目标 → [LLM推理] → 可能的行动方案 → [执行] → 结果（可能需要迭代）",
      "section_ref": "1.3.1",
      "runnable": false,
      "dependencies": []
    },
    {
      "id": "code-10",
      "language": "python",
      "description": "传统软件开发方式：",
      "code": "def book_flight(user_id, departure, destination, date):\n    # 1. 查询用户偏好\n    preferences = db.query(\"SELECT * FROM user_prefs WHERE user_id = ?\", user_id)\n    \n    # 2. 查询可用航班\n    flights = flight_api.search(departure, destination, date)\n    \n    # 3. 按偏好筛选\n    if preferences.prefer_morning:\n        flights = [f for f in flights if f.departure_hour < 12]\n    \n    # 4. 按价格排序\n    flights.sort(key=lambda f: f.price)\n    \n    # 5. 选择最便宜的\n    selected = flights[0]\n    \n    # 6. 预订\n    booking = flight_api.book(selected.id, user_id)\n    \n    return booking\n\n# 问题：如果用户没有设置偏好怎么办？\n# 如果没有早班机怎么办？\n# 如果最便宜的是红眼航班怎么办？\n# 需要为每种边界情况写代码...",
      "section_ref": "1.3.2",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-11",
      "language": "python",
      "description": "Agent方式：",
      "code": "agent.run(\n    goal=\"帮用户预订明天从北京到上海的机票\",\n    input={\"user_id\": \"zhangsan\"}\n)\n\n# Agent的推理过程可能是：\n# 1. 查询用户过去的出行记录 → 发现他经常选国航\n# 2. 查询明天的航班 → 发现早上8点和下午3点各有航班\n# 3. 检查用户的日历 → 发现下午2点有会议\n# 4. 推理：下午的航班时间太紧，选择早上8点\n# 5. 检查价格 → 发现在预算范围内\n# 6. 预订，并发送确认消息给用户",
      "section_ref": "1.3.2",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-12",
      "language": "python",
      "description": "大多数生产级系统不是纯Agent或纯传统软件，而是混合架构：",
      "code": "class HybridFlightBookingSystem:\n    def __init__(self):\n        self.agent = BookingAgent()     # 处理复杂决策\n        self.db = FlightDatabase()      # 处理数据存储\n        self.payment = PaymentService() # 处理支付（确定性逻辑）\n    \n    def book(self, user_id, request):\n        # 第一步：Agent理解用户意图并收集信息\n        booking_params = self.agent.process_request(request)\n        \n        # 第二步：传统软件处理确定性操作\n        available_flights = self.db.search_flights(booking_params)\n        \n        # 第三步：Agent帮助用户选择\n        selected_flight = self.agent.recommend_flight(\n            available_flights, \n            user_preferences=self.db.get_prefs(user_id)\n        )\n        \n        # 第四步：传统软件处理支付（需要确定性保证）\n        payment_result = self.payment.process(\n            amount=selected_flight.price,\n            method=booking_params.payment_method\n        )\n        \n        # 第五步：Agent生成确认消息\n        confirmation = self.agent.generate_confirmation(\n            flight=selected_flight,\n            payment=payment_result\n        )\n        \n        return confirmation",
      "section_ref": "1.3.4",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-13",
      "language": "python",
      "description": "- Agent像一个项目经理——你给他一个目标，他自己规划、协调资源、解决问题，直到完成目标。",
      "code": "# ============ Chatbot 的典型实现 ============\nclass Chatbot:\n    def __init__(self, llm):\n        self.llm = llm\n    \n    def chat(self, user_message, history=None):\n        \"\"\"收到一条消息，回复一条消息\"\"\"\n        response = self.llm.chat(\n            messages=[\n                {\"role\": \"system\", \"content\": \"你是一个有帮助的助手。\"},\n                *history,\n                {\"role\": \"user\", \"content\": user_message}\n            ]\n        )\n        return response\n    \n    # 交互模式：\n    # User: \"帮我查一下明天的天气\"\n    # Bot:  \"明天北京晴，温度15-25度\"\n    # [对话结束]\n\n\n# ============ Agent 的典型实现 ============\nclass WeatherAgent:\n    def __init__(self, llm, tools):\n        self.llm = llm\n        self.tools = tools\n        self.planner = TaskPlanner()\n    \n    def execute(self, goal):\n        \"\"\"接收目标，持续执行直到完成\"\"\"\n        plan = self.planner.create_plan(goal, self.tools)\n        \n        while not plan.is_complete():\n            current_step = plan.next_step()\n            \n            if current_step.needs_tool:\n                result = self.tools.call(\n                    current_step.tool, \n                    current_step.arguments\n                )\n                plan.record_result(result)\n            else:\n                thought = self.llm.think(current_step, plan.context())\n                plan.update(thought)\n            \n            # 如果遇到问题，重新规划\n            if plan.is_blocked():\n                plan = self.planner.replan(plan, self.tools)\n        \n        return plan.get_result()\n    \n    # 交互模式：\n    # User: \"帮我规划明天的出行\"\n    # Agent内部: \n    #   1. 调用天气API → 明天下午有雨\n    #   2. 调用日历API → 明天下午有会议\n    #   3. 推理 → 建议上午出行，带伞\n    #   4. 调用地图API → 推荐路线\n    #   5. 生成完整出行方案\n    # Agent: \"根据天气和您的日程安排，我建议...\"",
      "section_ref": "1.4.3",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-14",
      "language": "text",
      "description": "值得注意的是，Chatbot和Agent不是非此即彼的关系。很多系统是逐步从Chatbot演化成Agent的：",
      "code": "Stage 1: 纯对话 Chatbot\n    ↓ 添加FAQ知识库\nStage 2: 知识增强 Chatbot\n    ↓ 添加工具调用\nStage 3: 工具增强 Chatbot\n    ↓ 添加多步推理\nStage 4: 简单 Agent\n    ↓ 添加规划和记忆\nStage 5: 完整 Agent\n    ↓ 添加多Agent协作\nStage 6: Agent 系统",
      "section_ref": "1.4.4",
      "runnable": false,
      "dependencies": []
    },
    {
      "id": "code-15",
      "language": "python",
      "description": "最简单的Agent，直接根据输入做出反应，没有内部状态和复杂的推理。",
      "code": "class ReactiveAgent:\n    \"\"\"反应式Agent：刺激-反应模式\"\"\"\n    \n    def __init__(self, rules):\n        self.rules = rules  # 预定义的规则集\n    \n    def act(self, perception):\n        for rule in self.rules:\n            if rule.matches(perception):\n                return rule.action\n        return self.default_action()",
      "section_ref": "1.5.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-16",
      "language": "python",
      "description": "具有内部状态和推理能力的Agent，会在行动前进行\"思考\"。",
      "code": "class DeliberativeAgent:\n    \"\"\"慎思式Agent：先思考再行动\"\"\"\n    \n    def __init__(self, llm, world_model):\n        self.llm = llm\n        self.world_model = world_model  # 对世界的内部模型\n    \n    def act(self, perception):\n        # 1. 更新对世界的认知\n        self.world_model.update(perception)\n        \n        # 2. 生成多个候选方案\n        candidates = self.llm.generate_options(\n            state=self.world_model.current_state()\n        )\n        \n        # 3. 评估每个方案\n        evaluations = []\n        for candidate in candidates:\n            predicted_outcome = self.world_model.predict(candidate)\n            score = self.evaluate(predicted_outcome)\n            evaluations.append((candidate, score))\n        \n        # 4. 选择最优方案\n        best = max(evaluations, key=lambda x: x[1])\n        return best[0]",
      "section_ref": "1.5.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-17",
      "language": "python",
      "description": "结合反应式和慎思式的优点——对简单情况快速反应，对复杂情况深入思考。",
      "code": "class HybridAgent:\n    \"\"\"混合式Agent：快思考 + 慢思考\"\"\"\n    \n    def __init__(self, llm, reactive_rules):\n        self.llm = llm\n        self.reactive_rules = reactive_rules\n    \n    def act(self, perception):\n        # 快速路径：简单情况直接反应\n        for rule in self.reactive_rules:\n            if rule.matches(perception) and rule.confidence > 0.95:\n                return rule.action\n        \n        # 慢速路径：复杂情况深入推理\n        return self.deliberate(perception)\n    \n    def deliberate(self, perception):\n        \"\"\"复杂情况下的深度推理\"\"\"\n        return self.llm.reason(\n            perception=perception,\n            available_tools=self.tools.list(),\n            goal=self.current_goal\n        )",
      "section_ref": "1.5.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-18",
      "language": "python",
      "description": "| LLM-Free | 无 | 纯规则驱动 | 超低延迟、确定性要求高 |",
      "code": "# LLM-Heavy Agent：几乎所有决策都经过LLM\nclass HeavyAgent:\n    def process(self, task):\n        plan = self.llm.plan(task)        # LLM规划\n        for step in plan:\n            tool_choice = self.llm.choose_tool(step)  # LLM选工具\n            args = self.llm.generate_args(step)        # LLM生成参数\n            result = self.tools.call(tool_choice, args)\n            next_step = self.llm.decide_next(result)   # LLM决定下一步\n        return self.llm.summarize(results)\n\n\n# LLM-Light Agent：LLM只做意图路由\nclass LightAgent:\n    def process(self, task):\n        intent = self.llm.classify_intent(task)  # 只调一次LLM\n        \n        # 后续全部用确定性代码\n        if intent == \"book_flight\":\n            return self.flight_booking_handler.handle(task)\n        elif intent == \"check_weather\":\n            return self.weather_handler.handle(task)\n        else:\n            return self.fallback_handler.handle(task)",
      "section_ref": "1.5.4",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-19",
      "language": "python",
      "description": "这是目前Agent应用最广泛的场景之一。",
      "code": "class CustomerServiceAgent:\n    \"\"\"智能客服Agent\"\"\"\n    \n    def __init__(self):\n        self.tools = [\n            Tool(\"search_faq\", \"搜索常见问题库\"),\n            Tool(\"query_order\", \"查询订单状态\"),\n            Tool(\"process_refund\", \"处理退款申请\"),\n            Tool(\"transfer_to_human\", \"转接人工客服\"),\n            Tool(\"create_ticket\", \"创建工单\"),\n        ]\n        self.memory = CustomerMemory()  # 记住客户的投诉历史\n        self.llm = LLM(model=\"gpt-4\")\n    \n    def handle_customer(self, customer_message, customer_id):\n        # 加载客户历史（记忆）\n        history = self.memory.get_customer_history(customer_id)\n        \n        # 理解客户意图\n        intent = self.llm.analyze_intent(customer_message, history)\n        \n        # 根据意图执行操作\n        if intent.type == \"complaint\":\n            # 查看客户历史投诉\n            past_issues = self.tools.search_faq(customer_message)\n            similar_cases = self.memory.find_similar(customer_id, intent)\n            \n            # 尝试自动解决\n            if self.can_auto_resolve(intent, similar_cases):\n                resolution = self.resolve_automatically(intent)\n                return self.generate_response(resolution)\n            else:\n                # 转人工\n                self.tools.create_ticket(customer_id, intent)\n                return \"您的问题比较复杂，已为您转接人工客服...\"",
      "section_ref": "1.6.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-20",
      "language": "python",
      "description": "程序员可能是最早也是最活跃的Agent用户群体。",
      "code": "class CodeAgent:\n    \"\"\"代码开发Agent\"\"\"\n    \n    def __init__(self):\n        self.tools = [\n            Tool(\"read_file\", \"读取文件内容\"),\n            Tool(\"write_file\", \"写入文件\"),\n            Tool(\"run_tests\", \"运行测试\"),\n            Tool(\"search_codebase\", \"搜索代码库\"),\n            Tool(\"execute_shell\", \"执行Shell命令\"),\n            Tool(\"install_package\", \"安装依赖包\"),\n        ]\n    \n    def implement_feature(self, feature_description, project_path):\n        # 1. 理解需求\n        requirements = self.llm.analyze_requirements(\n            feature_description,\n            existing_code=self.tools.search_codebase(project_path)\n        )\n        \n        # 2. 制定实现计划\n        plan = self.llm.create_implementation_plan(requirements)\n        \n        # 3. 逐步实现\n        for step in plan:\n            self.tools.write_file(step.file_path, step.code)\n            \n            # 实现后立即验证\n            test_result = self.tools.run_tests(step.related_tests)\n            if not test_result.passed:\n                fix = self.llm.fix_error(test_result.error, step.code)\n                self.tools.write_file(step.file_path, fix)\n        \n        # 4. 运行完整测试\n        final_result = self.tools.run_tests(\"all\")\n        return final_result",
      "section_ref": "1.6.2",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-21",
      "language": "python",
      "description": "Agent特别擅长处理探索性的数据分析任务——因为这类任务需要根据中间结果不断调整分析方向。",
      "code": "class DataAnalysisAgent:\n    \"\"\"数据分析Agent\"\"\"\n    \n    def analyze(self, question, data_source):\n        # 1. 加载和初步理解数据\n        data = self.load_data(data_source)\n        data_profile = self.profile_data(data)\n        \n        # 2. 理解分析目标\n        analysis_plan = self.llm.create_analysis_plan(\n            question=question,\n            data_profile=data_profile\n        )\n        \n        # 3. 迭代式分析\n        results = []\n        for step in analysis_plan:\n            code = self.llm.generate_analysis_code(\n                step, data_profile, previous_results=results\n            )\n            result = self.execute_python(code)\n            results.append(result)\n            \n            # 根据结果调整后续计划\n            if self.needs_more_analysis(result):\n                additional_steps = self.llm.suggest_followup(result)\n                analysis_plan.extend(additional_steps)\n        \n        # 4. 生成报告\n        report = self.llm.generate_report(question, results)\n        return report",
      "section_ref": "1.6.3",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-22",
      "language": "python",
      "description": "",
      "code": "class WorkflowAgent:\n    \"\"\"工作流自动化Agent\"\"\"\n    \n    def automate(self, trigger, workflow_description):\n        # 理解工作流\n        steps = self.llm.parse_workflow(workflow_description)\n        \n        # 监听触发条件\n        while True:\n            if self.check_trigger(trigger):\n                # 执行工作流\n                context = {}\n                for step in steps:\n                    # 动态适配每个步骤\n                    if step.type == \"api_call\":\n                        context[step.name] = self.call_api(\n                            step.config, context\n                        )\n                    elif step.type == \"decision\":\n                        decision = self.llm.decide(\n                            step.criteria, context\n                        )\n                        context[step.name] = decision\n                    elif step.type == \"notification\":\n                        self.send_notification(\n                            step.recipient, \n                            self.llm.format_message(step.template, context)\n                        )\n                \n                # 记录执行结果\n                self.log_execution(trigger, steps, context)",
      "section_ref": "1.6.4",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-23",
      "language": "python",
      "description": "LLM会\"一本正经地胡说八道\"，Agent也不例外。当Agent基于错误的信息做出决策时，后果可能比Chatbot更严重——因为它不仅仅是说错话，还可能执行错误的操作。",
      "code": "# 危险场景：Agent基于幻觉做出操作\n# User: \"把最近的发票全部标记为已支付\"\n# Agent幻觉：认为某笔大额支出是发票\n# Agent执行：将一笔实际是贷款的记录标记为已支付\n# 结果：财务数据出错",
      "section_ref": "1.7.1",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-24",
      "language": "python",
      "description": "每次LLM调用都是有成本的。一个复杂的Agent任务可能需要多次LLM调用（推理、规划、工具选择、参数生成、结果总结），成本可能快速累积。",
      "code": "# 一次完整的Agent任务可能涉及的LLM调用\nclass CostAwareAgent:\n    def estimate_cost(self, task):\n        return {\n            \"intent_understanding\": 1,      # 1次调用\n            \"planning\": 1,                  # 1次调用\n            \"tool_selection_per_step\": 3,   # 假设3步，每步1次\n            \"argument_generation\": 3,       # 每步1次\n            \"result_interpretation\": 3,     # 每步1次\n            \"error_recovery\": 1,            # 可能需要1次\n            \"final_summary\": 1,             # 1次调用\n        }\n        # 总计：~12次LLM调用",
      "section_ref": "1.7.2",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-25",
      "language": "python",
      "description": "- 审计追踪：记录Agent的所有操作",
      "code": "class SecureAgent(MinimalAgent):\n    def __init__(self, llm, tools, memory, permission_manager):\n        super().__init__(llm, tools, memory)\n        self.permissions = permission_manager\n    \n    def safe_act(self, plan):\n        \"\"\"安全执行：每次操作前检查权限\"\"\"\n        for step in plan.steps:\n            if not self.permissions.is_allowed(step):\n                # 敏感操作需要人工确认\n                approval = self.request_human_approval(step)\n                if not approval.approved:\n                    self.log_blocked_action(step)\n                    continue\n            \n            # 执行并审计\n            result = self.tools.call(step.tool_name, step.args)\n            self.audit_log.record(step, result)",
      "section_ref": "1.7.4",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-26",
      "language": "python",
      "description": "不要一上来就试图构建一个全能的Agent。从一个功能明确、范围有限的小Agent开始：",
      "code": "# ❌ 不好的做法：一上来就搞大而全\nclass SuperAgent:\n    \"\"\"能做所有事情的超级Agent\"\"\"  # 几乎不可能做好\n    \n# ✅ 好的做法：从特定功能开始\nclass EmailTriagingAgent:\n    \"\"\"只做邮件分类的小Agent\"\"\"  # 范围明确，容易做好",
      "section_ref": "1. 从小处开始",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-27",
      "language": "python",
      "description": "Agent不是万能的。明确它能做什么、不能做什么，比让它\"尽量做到最好\"更重要：",
      "code": "class WellBoundedAgent:\n    def __init__(self):\n        self.capabilities = [\n            \"搜索公司内部文档\",\n            \"总结会议记录\",\n            \"创建简单的日历事件\"\n        ]\n        self.not_capabilities = [\n            \"发送邮件\",      # 需要人工确认\n            \"删除任何数据\",  # 安全边界\n            \"访问外部网站\",  # 安全边界\n        ]\n    \n    def handle(self, request):\n        if not self.can_handle(request):\n            return self.handoff_to_human(request)\n        return self.execute(request)",
      "section_ref": "2. 明确定义Agent的边界",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-28",
      "language": "python",
      "description": "让Agent在关键决策节点请人确认，而不是完全自主：",
      "code": "class HumanInTheLoopAgent:\n    CONFIRMATION_REQUIRED = [\n        \"send_email\",       # 发送邮件\n        \"delete_data\",      # 删除数据\n        \"financial_transaction\",  # 金融交易\n        \"external_api_call\",      # 调用外部API\n    ]\n    \n    def act(self, plan):\n        for step in plan:\n            if step.tool in self.CONFIRMATION_REQUIRED:\n                approval = self.ask_human(\n                    f\"Agent想要执行: {step.tool}({step.args})\\n\"\n                    f\"原因: {step.reasoning}\\n\"\n                    f\"是否批准？\"\n                )\n                if not approval:\n                    continue\n            self.tools.call(step.tool, step.args)",
      "section_ref": "3. 设计好\"人的回路\"（Human-i",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-29",
      "language": "python",
      "description": "你无法优化你看不见的东西。Agent的决策过程必须可追踪：",
      "code": "class ObservableAgent(MinimalAgent):\n    def __init__(self, llm, tools, memory):\n        super().__init__(llm, tools, memory)\n        self.traces = []  # 执行追踪\n    \n    def reason(self):\n        thought = self.llm.think(...)\n        self.traces.append({\n            \"timestamp\": datetime.now(),\n            \"type\": \"reasoning\",\n            \"input\": self.memory.get_context(),\n            \"output\": thought,\n            \"token_usage\": self.llm.last_token_usage,\n            \"latency_ms\": self.llm.last_latency,\n        })\n        return thought",
      "section_ref": "4. 为Agent设计完善的可观测性",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-30",
      "language": "python",
      "description": "不是所有Agent都需要高度自治。根据场景选择合适的自主程度：",
      "code": "# 场景1：高自主度（研究助手）\nresearch_agent = Agent(\n    autonomy_level=\"high\",      # 可以自行搜索、分析、总结\n    confirmation_required=[],   # 不需要人工确认\n    fallback=\"ask_human\"        # 无法完成时才问人\n)\n\n# 场景2：中等自主度（客服Agent）  \nservice_agent = Agent(\n    autonomy_level=\"medium\",    # 可以回答常见问题\n    confirmation_required=[\"refund\", \"escalate\"],  # 退款和升级需确认\n    fallback=\"transfer_to_human\"\n)\n\n# 场景3：低自主度（代码审查助手）\nreview_agent = Agent(\n    autonomy_level=\"low\",       # 只提供建议\n    confirmation_required=[\"all_changes\"],  # 所有修改需确认\n    fallback=\"skip_review\"      # 不确定就跳过\n)",
      "section_ref": "5. 选择合适的自主程度",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-31",
      "language": "python",
      "description": "把所有逻辑都塞给LLM，导致成本高、延迟大、不可控。",
      "code": "# ❌ 过度依赖LLM\nclass OverReliantAgent:\n    def process(self, data):\n        # 简单的JSON解析也用LLM\n        parsed = self.llm.parse_json(data)\n        # 简单的条件判断也用LLM\n        category = self.llm.classify(parsed, categories)\n        # 简单的格式化也用LLM\n        return self.llm.format_response(parsed, category)\n\n# ✅ 合理使用LLM\nclass BalancedAgent:\n    def process(self, data):\n        parsed = json.loads(data)          # 用传统代码\n        category = self.classify(parsed)   # 用传统代码（规则/ML）\n        if category == \"complex\":\n            return self.llm.handle_complex(parsed)  # 只在必要时用LLM\n        return self.format_response(parsed, category)  # 用传统代码",
      "section_ref": "陷阱2：过度依赖LLM",
      "runnable": true,
      "dependencies": []
    },
    {
      "id": "code-32",
      "language": "python",
      "description": "LLM有上下文窗口大小的限制。如果你的Agent需要处理大量信息，需要设计好上下文管理策略：",
      "code": "# ❌ 无限累积上下文\nclass NaiveAgent:\n    def chat(self, messages):\n        self.history.extend(messages)  # 一直增长...\n        return self.llm.chat(self.history)  # 终究会超出窗口限制\n\n# ✅ 主动管理上下文\nclass SmartAgent:\n    def chat(self, message):\n        self.history.append(message)\n        \n        # 当上下文接近窗口限制时，进行压缩\n        if self.estimate_tokens(self.history) > self.window_limit * 0.8:\n            self.history = self.compress_context(self.history)\n        \n        return self.llm.chat(self.history)\n    \n    def compress_context(self, history):\n        \"\"\"保留最近N轮 + 早期摘要\"\"\"\n        recent = history[-10:]\n        early_summary = self.llm.summarize(history[:-10])\n        return [{\"role\": \"system\", \"content\": f\"历史摘要: {early_summary}\"}] + recent",
      "section_ref": "陷阱4：忽视上下文窗口限制",
      "runnable": true,
      "dependencies": []
    }
  ],
  "tables": [
    {
      "headers": [
        "关键词",
        "含义",
        "例子"
      ],
      "data": [
        [
          "**感知（Perception）**",
          "从环境中获取信息",
          "读取用户消息、查询数据库、调用API"
        ],
        [
          "**推理（Reasoning）**",
          "基于感知到的信息进行分析和决策",
          "分析意图、制定计划、评估选项"
        ],
        [
          "**执行（Action）**",
          "在环境中产生实际影响",
          "发送邮件、修改文件、调用工具"
        ],
        [
          "**目标（Goal）**",
          "有明确的预期结果",
          "\"帮用户订机票\"、\"完成代码审查\""
        ],
        [
          "**自治（Autonomy）**",
          "在一定范围内自主决策，不需要每步都由人指定",
          "Agent自己决定先查数据库还是先问用户"
        ]
      ]
    },
    {
      "headers": [
        "维度",
        "自动化（Automation）",
        "Agent"
      ],
      "data": [
        [
          "**决策方式**",
          "预定义的规则/流程",
          "基于推理的动态决策"
        ],
        [
          "**适应性**",
          "输入变化时可能失败",
          "能处理预期之外的情况"
        ],
        [
          "**工具选择**",
          "硬编码的工具链",
          "根据需要动态选择工具"
        ],
        [
          "**错误处理**",
          "预定义的异常处理",
          "能推理出新的处理方式"
        ],
        [
          "**上限**",
          "设计者预设的所有场景",
          "受限于LLM的能力边界"
        ]
      ]
    },
    {
      "headers": [
        "维度",
        "传统软件",
        "Agent"
      ],
      "data": [
        [
          "**核心问题**",
          "\"如何做\"（How）",
          "\"做什么\"（What）"
        ],
        [
          "**开发者角色**",
          "实现每一步逻辑",
          "定义目标和约束"
        ],
        [
          "**错误处理**",
          "预定义所有错误场景",
          "自适应处理异常"
        ],
        [
          "**测试方式**",
          "确定性测试（断言精确输出）",
          "评估性测试（判断结果质量）"
        ],
        [
          "**可预测性**",
          "高（相同输入→相同输出）",
          "低（但可通过约束提高）"
        ],
        [
          "**适应性**",
          "需要修改代码",
          "可以通过调整提示词"
        ]
      ]
    },
    {
      "headers": [
        "维度",
        "Chatbot",
        "Agent"
      ],
      "data": [
        [
          "**交互模式**",
          "对话式，你来我往",
          "目标驱动，持续工作"
        ],
        [
          "**主动性**",
          "被动等待输入",
          "主动规划和执行"
        ],
        [
          "**持久性**",
          "对话结束即终止",
          "可以长时间运行、跨会话"
        ],
        [
          "**工具使用**",
          "可能调用少量工具",
          "深度集成多种工具"
        ],
        [
          "**状态管理**",
          "无状态或简单状态",
          "复杂状态追踪"
        ],
        [
          "**输出类型**",
          "文本回复为主",
          "可以执行任意操作"
        ]
      ]
    },
    {
      "headers": [
        "类型",
        "描述",
        "典型例子"
      ],
      "data": [
        [
          "**信息获取型**",
          "搜索、检索、汇总信息",
          "搜索助手、研究助手"
        ],
        [
          "**内容生成型**",
          "创建文本、图像、代码",
          "写作助手、代码助手"
        ],
        [
          "**决策支持型**",
          "分析数据、提供建议",
          "数据分析Agent、投资顾问"
        ],
        [
          "**操作执行型**",
          "执行具体操作",
          "邮件管理Agent、文件管理Agent"
        ],
        [
          "**协调管理型**",
          "协调多个Agent或人",
          "项目管理Agent、工作流编排Agent"
        ]
      ]
    },
    {
      "headers": [
        "形态",
        "特点",
        "适用场景"
      ],
      "data": [
        [
          "**独立Agent**",
          "单个Agent独立工作",
          "简单任务、个人助手"
        ],
        [
          "**嵌入式Agent**",
          "集成到现有应用中",
          "增强现有产品功能"
        ],
        [
          "**多Agent系统**",
          "多个Agent协作完成复杂任务",
          "复杂工作流、企业级系统"
        ],
        [
          "**Agent平台**",
          "提供Agent创建和管理能力",
          "Agent开发平台、SaaS"
        ]
      ]
    },
    {
      "headers": [
        "类型",
        "LLM依赖",
        "特点",
        "适用场景"
      ],
      "data": [
        [
          "**LLM-Heavy**",
          "高",
          "推理、规划都依赖LLM",
          "创意任务、开放域任务"
        ],
        [
          "**LLM-Light**",
          "低",
          "LLM只做意图识别，执行用传统代码",
          "结构化任务、高频任务"
        ],
        [
          "**LLM-Free**",
          "无",
          "纯规则驱动",
          "超低延迟、确定性要求高"
        ]
      ]
    }
  ],
  "key_takeaways": [],
  "common_pitfalls": [],
  "related_chapters": [
    "ch02",
    "ch03",
    "ch04"
  ]
}