{ "metadata": { "id": "ch03", "title": "第3章：Agent编程范式", "volume": "vol1", "volume_title": "认知篇", "word_count": 5098, "difficulty": "beginner", "prerequisites": [ "ch01" ], "key_concepts": [ "从函数式到 Agent式：编程范式的演变", "范式演进的驱动力", "Agent范式的独特特征", "为什么现在需要Agent范式", "Agent编程的核心要素", "感知-思考-行动循环", "目标函数与奖励信号", "反馈循环与自我修正", "声明式 vs 命令式 Agent 编程", "两种风格对比", "各自的适用场景", "混合式：渐进式自主", "事件驱动与响应式 Agent", "事件驱动架构在 Agent 中的角色", "Agent编程的核心抽象" ], "learning_objectives": [], "estimated_tokens": 3059, "source_file": "vol1/ch03_Agent编程范式.md" }, "overview": "如果说面向对象编程（OOP）教会了我们用\"对象\"来组织代码，函数式编程（FP）教会了我们用\"纯函数\"来管理副作用，那么 Agent 编程则代表了一种全新的思维范式——**让程序拥有自主决策和与环境交互的能力**。本章将深入探讨 Agent 编程范式的本质，从编程范式的历史演变出发，剖析 Agent 编程与传统范式的根本区别，并系统地介绍 Agent 编程的核心抽象、设计原则和实践方法。\n\n读完本章，你将理解：Agent 编程为何不同于你之前接触过的任何编程范式；如何用感知-思考-行动（Perceive-Think-Act）的循环来组织 Agent 逻辑；以及在实际项目中如何选择合适的编程语言和框架来实现 Agent 系统。", "sections": [ { "id": "3.1", "title": "3.1 从函数式到 Agent式：编程范式的演变", "level": 2, "content": "", "subsections": [ { "id": "3.1.1", "title": "3.1.1 范式演进的驱动力", "content": "编程范式（Programming Paradigm）不是凭空产生的，而是对不断增长的软件复杂度的回应。每一次范式跃迁，都伴随着对\"谁来做决策\"这个根本问题的重新回答。\n\n\n**过程式编程**的核心理念是\"按照步骤来\"：先做A，再做B，条件C成立就做D。程序员完全控制每一步的执行顺序。\n\n**面向对象编程**将数据和操作封装在对象中，通过消息传递实现对象间协作。对象拥有了\"行为\"，但仍然是程序员预先定义好的——对象不会\"思考\"。\n\n**函数式编程**追求纯函数和不可变状态，通过函数组合构建复杂逻辑。它解决了并发状态管理的问题，但函数本身不会主动\"决定\"做什么。\n\n**Agent 编程**引入了一个根本性的变化：**决策权从程序员转移到了程序本身**。程序不再是被动执行指令的工具，而是能够根据环境状态、目标函数和可用工具，自主决定下一步行动的智能实体。" }, { "id": "3.1.2", "title": "3.1.2 Agent范式的独特特征", "content": "Agent 编程与之前所有范式的核心区别可以总结为三个关键词：**自主性（Autonomy）**、**目标导向（Goal-orientation）**和**环境交互（Environmental Interaction）**。\n\n| 特征 | 传统编程 | Agent编程 |\n|------|---------|----------|\n| 决策者 | 程序员（硬编码） | Agent（运行时推理） |\n| 控制流 | 预定义（if/else、循环） | 动态生成（LLM推理） |\n| 行为确定性 | 确定性（相同输入→相同输出） | 非确定性（可能选择不同策略） |\n| 错误处理 | 异常捕获、错误码 | 自我反思、策略调整 |\n| 扩展方式 | 修改代码 | 添加工具/提示词 |\n| 环境感知 | 无（或有限） | 持续感知并响应变化 |" }, { "id": "3.1.3", "title": "3.1.3 为什么现在需要Agent范式", "content": "Agent 编程并非突然出现，而是技术积累到一定程度的自然产物：\n\n1. **LLM 推理能力**：GPT-4、Claude 等模型具备了足够的理解和推理能力，可以作为 Agent 的\"大脑\"\n2. **工具调用标准化**：Function Calling / Tool Use 协议的普及，使 LLM 能可靠地与外部系统交互\n3. **基础设施成熟**：向量数据库、API 网关、云服务等基础设施完善，为 Agent 提供了丰富的\"感官\"和\"工具\"\n4. **复杂任务需求**：传统编程在处理开放式、多步骤、需要判断力的任务时力不从心" } ] }, { "id": "3.2", "title": "3.2 Agent编程的核心要素", "level": 2, "content": "", "subsections": [ { "id": "3.2.1", "title": "3.2.1 感知-思考-行动循环", "content": "Agent 编程的基石是 **Perceive-Think-Act（PTA）循环**，它与军事领域的 OODA Loop（Observe-Orient-Decide-Act）有异曲同工之妙。" }, { "id": "3.2.2", "title": "3.2.2 目标函数与奖励信号", "content": "与传统程序的\"输入-处理-输出\"不同，Agent 需要一个**目标函数（Objective Function）**来指导其行为。目标可以是显式的（用户指令），也可以是隐式的（系统优化目标）。" }, { "id": "3.2.3", "title": "3.2.3 反馈循环与自我修正", "content": "Agent 编程区别于传统编程的一个重要特征是**内置的反馈循环**。Agent 不仅执行操作，还会评估操作结果，并根据反馈调整策略。" } ] }, { "id": "3.3", "title": "3.3 声明式 vs 命令式 Agent 编程", "level": 2, "content": "", "subsections": [ { "id": "3.3.1", "title": "3.3.1 两种风格对比", "content": "Agent 编程存在两种主要风格，类似于传统编程中的声明式与命令式之分：\n\n**命令式 Agent 编程**：明确指定 Agent 的每一步操作，类似于编写详细的操作手册。\n\n\n**声明式 Agent 编程**：描述目标和约束，让 Agent 自主规划执行路径。" }, { "id": "3.3.2", "title": "3.3.2 各自的适用场景", "content": "| 场景 | 推荐风格 | 原因 |\n|------|---------|------|\n| 简单、确定性任务 | 命令式 | 步骤固定，不需要推理 |\n| 关键业务流程 | 命令式 | 需要精确控制，降低风险 |\n| 开放式探索任务 | 声明式 | 需要灵活性和创造力 |\n| 复杂多步骤任务 | 声明式 | 步骤组合空间大，人工规划成本高 |\n| 快速原型 | 声明式 | 开发效率高 |\n| 生产环境 | 混合式 | 关键路径命令式，辅助路径声明式 |" }, { "id": "3.3.3", "title": "3.3.3 混合式：渐进式自主", "content": "在实际项目中，最常见的是混合式——**渐进式自主（Progressive Autonomy）**：核心流程用命令式确保可靠性，非核心环节让 Agent 自主决策。" } ] }, { "id": "3.4", "title": "3.4 事件驱动与响应式 Agent", "level": 2, "content": "", "subsections": [ { "id": "3.4.1", "title": "3.4.1 事件驱动架构在 Agent 中的角色", "content": "事件驱动架构（EDA）与 Agent 编程天然契合——Agent 需要对环境变化做出实时响应，而事件正是环境变化的载体。" }, { "id": "3.4.2", "title": "3.4.2 Reactive Agent vs Proactive Agent", "content": "Agent 按行为模式可分为两种：\n\n- **Reactive Agent（反应式）**：被动等待事件触发，类似事件监听器\n- **Proactive Agent（主动式）**：主动发起行动，持续朝目标推进" } ] }, { "id": "3.5", "title": "3.5 Agent编程的核心抽象", "level": 2, "content": "Agent 编程有三个核心抽象概念：**工具（Tool）**、**记忆（Memory）** 和 **规划器（Planner）**。它们共同构成了 Agent 的\"手脚\"、\"大脑\"和\"智慧\"。", "subsections": [ { "id": "3.5.1", "title": "3.5.1 Tool抽象", "content": "工具是 Agent 与外部世界交互的接口。在 Agent 编程范式中，工具不是简单的函数调用，而是一个带有丰富元数据的抽象。" }, { "id": "3.5.2", "title": "3.5.2 Memory抽象", "content": "记忆是 Agent 保持上下文连续性的关键。Agent 的记忆分为短期和长期两个层次。" }, { "id": "3.5.3", "title": "3.5.3 Planner抽象", "content": "规划器是 Agent 的\"战略大脑\"，负责将高层目标分解为可执行步骤。" } ] }, { "id": "3.6", "title": "3.6 Agent编程与微服务/函数计算的对比", "level": 2, "content": "", "subsections": [ { "id": "3.6.1", "title": "3.6.1 核心差异", "content": "虽然 Agent 编程与微服务和 Serverless 有相似之处（都是模块化、可组合的），但它们在本质上截然不同。\n\n\n| 维度 | 微服务 | Serverless | Agent编程 |\n|------|--------|-----------|----------|\n| **编排方式** | 固定编排（API Gateway） | 事件触发 | 自主决策 |\n| **流程确定性** | 高（预定义路由） | 中（事件映射） | 低（动态推理） |\n| **扩展方式** | 水平扩展实例 | 自动扩缩容 | 添加工具/知识 |\n| **状态管理** | 外部存储（DB/Redis） | 无状态 | 内置记忆系统 |\n| **错误处理** | 重试、熔断 | 重试、DLQ | 自我反思、策略调整 |\n| **适用场景** | 标准化业务流程 | 事件驱动任务 | 开放式复杂任务 |" }, { "id": "3.6.2", "title": "3.6.2 互补关系", "content": "三者并非互斥，而是互补的。在实际架构中：\n\n- **微服务**提供 Agent 的\"工具层\"——搜索服务、数据分析服务、文件处理服务等\n- **Serverless**适合作为 Agent 工具的执行环境——按需调用，成本可控\n- **Agent**作为\"编排大脑\"，智能地组合调用这些服务" } ] }, { "id": "3.7", "title": "3.7 Agent编程语言与框架的选择", "level": 2, "content": "", "subsections": [ { "id": "3.7.1", "title": "3.7.1 语言生态对比", "content": "" }, { "id": "3.7.2", "title": "3.7.2 选型决策矩阵", "content": "| 考量因素 | Python | TypeScript | Rust/Go |\n|---------|--------|-----------|---------|\n| 生态成熟度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |\n| 开发效率 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |\n| 运行性能 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| Web集成 | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |\n| 生产部署 | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |\n| 框架选择 | LangChain, AutoGen, CrewAI | Vercel AI SDK, LangChain.js | 稀少 |\n| 适用场景 | 原型、后端、数据分析 | Web应用、全栈 | 高性能服务 |\n\n**推荐策略**：\n- **原型验证阶段**：Python（生态最丰富，迭代最快）\n- **Web前端Agent**：TypeScript（与前端生态无缝集成）\n- **高性能后端**：Python核心逻辑 + Rust/Go性能关键路径\n- **生产部署**：TypeScript（全栈统一）或 Python + 容器化" } ] }, { "id": "最佳实践", "title": "最佳实践", "level": 2, "content": "", "subsections": [ { "id": "1. 从小处着手，渐进增强", "title": "1. 从小处着手，渐进增强", "content": "不要一开始就构建复杂的全自主 Agent。从命令式控制开始，逐步增加 Agent 的自主决策范围。" }, { "id": "2. 明确定义工具边界", "title": "2. 明确定义工具边界", "content": "每个工具应该职责单一、输入输出清晰。避免\"万能工具\"——它会让 Agent 的选择变得困难且不可预测。" }, { "id": "3. 设计可观测性", "title": "3. 设计可观测性", "content": "Agent 的非确定性使得调试变得困难。从一开始就为每一步决策记录日志：思考过程、工具选择原因、执行结果。" }, { "id": "4. 设置护栏（Guardrails）", "title": "4. 设置护栏（Guardrails）", "content": "无论 Agent 多\"智能\"，都要设置硬性约束：最大步骤数、工具调用频率限制、敏感操作确认机制、成本上限。" }, { "id": "5. 分层记忆策略", "title": "5. 分层记忆策略", "content": "短期记忆保持最近的对话上下文，长期记忆存储重要事实和用户偏好。两者配合使用，避免上下文溢出。" } ] }, { "id": "常见陷阱", "title": "常见陷阱", "level": 2, "content": "", "subsections": [ { "id": "1. 过度自主", "title": "1. 过度自主", "content": "**问题**：给 Agent 太大的自主权，导致它做出意料之外的操作。\n**解决**：对关键操作（删除、支付、发送邮件等）要求人工确认。" }, { "id": "2. 工具爆炸", "title": "2. 工具爆炸", "content": "**问题**：注册了太多工具（>20个），Agent 选择困难，响应变慢。\n**解决**：工具分级（常用/偶尔/罕见），只向 Agent 暴露当前任务相关的工具子集。" }, { "id": "3. 忽略成本", "title": "3. 忽略成本", "content": "**问题**：Agent 在探索阶段消耗大量 token，成本失控。\n**解决**：设置 token 预算，使用更小的模型做规划，大模型做关键决策。" }, { "id": "4. 忘记记忆管理", "title": "4. 忘记记忆管理", "content": "**问题**：对话变长后，重要信息被截断遗忘。\n**解决**：实现主动记忆管理——重要信息提取、摘要压缩、长期记忆检索。" } ] }, { "id": "小结", "title": "小结", "level": 2, "content": "Agent 编程范式代表了软件开发的一次根本性转变：从\"告诉程序怎么做\"到\"告诉程序做什么\"。通过感知-思考-行动循环、工具/记忆/规划器三大抽象，以及声明式与命令式的灵活组合，开发者可以构建出真正智能的软件系统。\n\n理解 Agent 编程范式，是掌握后续所有 Agent 技术（多 Agent 协作、RAG、Function Calling 等）的基础。在接下来的章节中，我们将深入探讨这些核心概念的具体实现。", "subsections": [] }, { "id": "延伸阅读", "title": "延伸阅读", "level": 2, "content": "1. **论文**: \"ReAct: Synergizing Reasoning and Acting in Language Models\" (Yao et al., 2022) — 经典的 Agent 推理框架\n2. **论文**: \"Toolformer: Language Models Can Teach Themselves to Use Tools\" (Schick et al., 2023) — 工具学习的理论基础\n3. **论文**: \"Generative Agents: Interactive Simulacra of Human Behavior\" (Park et al., 2023) — Agent 自主行为的开创性研究\n4. **书籍**: \"Designing Agentive Technology\" (Christopher Noessel) — 代理式技术的设计哲学\n5. **框架文档**: LangChain Agents Guide — https://python.langchain.com/docs/modules/agents/\n6. **框架文档**: Microsoft AutoGen — https://microsoft.github.io/autogen/\n7. **文章**: \"The Landscape of Emerging AI Agent Architectures\" — Agent 架构全景分析", "subsections": [] } ], "code_blocks": [ { "id": "code-1", "language": "mermaid", "description": "编程范式（Programming Paradigm）不是凭空产生的，而是对不断增长的软件复杂度的回应。每一次范式跃迁，都伴随着对\"谁来做决策\"这个根本问题的重新回答。", "code": "timeline\n title 编程范式的演进\n 1950s : 机器/汇编语言 — 程序员做一切\n 1960s : 过程式编程 — 用函数组织控制流\n 1970s : 结构化编程 — 消除goto，用循环和分支\n 1980s : 面向对象 — 用对象封装状态和行为\n 1990s : 泛型编程 — 参数化类型，算法复用\n 2000s : 函数式复兴 — 不可变状态，纯函数组合\n 2010s : 响应式编程 — 声明式异步数据流\n 2020s : Agent编程 — 自主决策，环境交互", "section_ref": "3.1.1", "runnable": false, "dependencies": [] }, { "id": "code-2", "language": "python", "description": "| 环境感知 | 无（或有限） | 持续感知并响应变化 |", "code": "# 传统编程：硬编码决策\ndef process_user_query(query: str) -> str:\n if \"天气\" in query:\n return weather_api.get_weather(query)\n elif \"翻译\" in query:\n return translate_api.translate(query)\n else:\n return \"抱歉，我不理解你的问题。\"\n\n# Agent编程：自主决策\nasync def agent_process(query: str, agent: Agent) -> str:\n # Agent自行分析意图、选择工具、规划步骤\n plan = await agent.plan(query) # 感知 + 思考\n results = await agent.execute(plan) # 行动\n return await agent.synthesize(results) # 综合输出", "section_ref": "3.1.2", "runnable": true, "dependencies": [] }, { "id": "code-3", "language": "mermaid", "description": "Agent 编程的基石是 Perceive-Think-Act（PTA）循环，它与军事领域的 OODA Loop（Observe-Orient-Decide-Act）有异曲同工之妙。", "code": "graph TD\n A[感知 Perceive] --> B[思考 Think]\n B --> C[行动 Act]\n C --> D[环境反馈]\n D --> A\n \n A -->|用户输入、API响应、系统状态| B\n B -->|推理、规划、工具选择| C\n C -->|调用工具、生成回复、修改状态| D\n D -->|新信息、结果确认、错误信号| A", "section_ref": "3.2.1", "runnable": false, "dependencies": [] }, { "id": "code-4", "language": "python", "description": "D -->|新信息、结果确认、错误信号| A", "code": "from dataclasses import dataclass\nfrom typing import Protocol, Any\nfrom abc import ABC, abstractmethod\n\n@dataclass\nclass Perception:\n \"\"\"感知数据：Agent从环境中获取的信息\"\"\"\n user_input: str\n context: dict[str, Any]\n history: list[dict[str, str]]\n available_tools: list[str]\n\n@dataclass\nclass Thought:\n \"\"\"思考结果：Agent的推理和规划\"\"\"\n reasoning: str # 推理过程\n plan: list[str] # 行动计划\n tool_calls: list[dict] # 工具调用决策\n\n@dataclass\nclass Action:\n \"\"\"行动：Agent执行的具体操作\"\"\"\n tool_name: str\n tool_args: dict[str, Any]\n expected_outcome: str\n\nclass AgentLoop(ABC):\n \"\"\"Agent核心循环\"\"\"\n \n def __init__(self, max_iterations: int = 10):\n self.max_iterations = max_iterations\n \n async def run(self, user_input: str) -> str:\n \"\"\"主循环：感知→思考→行动→反馈\"\"\"\n perception = await self.perceive(user_input)\n \n for i in range(self.max_iterations):\n thought = await self.think(perception)\n \n if thought.is_final_answer:\n return thought.final_answer\n \n action = await self.plan_action(thought)\n result = await self.act(action)\n perception = await self.update_perception(perception, result)\n \n return \"抱歉，我无法在限定步骤内完成任务。\"\n \n @abstractmethod\n async def perceive(self, input_data: str) -> Perception:\n \"\"\"感知：收集和整理环境信息\"\"\"\n ...\n \n @abstractmethod\n async def think(self, perception: Perception) -> Thought:\n \"\"\"思考：推理和规划\"\"\"\n ...\n \n @abstractmethod\n async def act(self, action: Action) -> dict:\n \"\"\"行动：执行工具调用\"\"\"\n ...", "section_ref": "3.2.1", "runnable": true, "dependencies": [] }, { "id": "code-5", "language": "python", "description": "与传统程序的\"输入-处理-输出\"不同，Agent 需要一个目标函数（Objective Function）来指导其行为。目标可以是显式的（用户指令），也可以是隐式的（系统优化目标）。", "code": "from enum import Enum\nfrom typing import Callable\n\nclass GoalType(Enum):\n TASK_COMPLETE = \"task_complete\" # 完成指定任务\n MAXIMIZE_SCORE = \"maximize_score\" # 最大化某个分数\n MINIMIZE_COST = \"minimize_cost\" # 最小化成本\n MAINTAIN_STATE = \"maintain_state\" # 维持某个状态\n\n@dataclass\nclass AgentGoal:\n \"\"\"Agent的目标定义\"\"\"\n description: str # 目标描述（自然语言）\n goal_type: GoalType # 目标类型\n success_criteria: Callable # 成功判断函数\n max_steps: int = 20 # 最大步骤\n budget: dict[str, float] | None = None # 资源预算（token、时间等）\n \n def is_achieved(self, state: dict) -> bool:\n return self.success_criteria(state)\n\n# 示例：定义一个数据分析Agent的目标\ndata_analysis_goal = AgentGoal(\n description=\"分析销售数据，找出Top3产品并生成报告\",\n goal_type=GoalType.TASK_COMPLETE,\n success_criteria=lambda s: (\n s.get(\"top_products_count\", 0) >= 3 and\n s.get(\"report_generated\", False) is True\n ),\n max_steps=15,\n budget={\"max_tokens\": 50000, \"max_time_seconds\": 120}\n)", "section_ref": "3.2.2", "runnable": true, "dependencies": [] }, { "id": "code-6", "language": "python", "description": "Agent 编程区别于传统编程的一个重要特征是内置的反馈循环。Agent 不仅执行操作，还会评估操作结果，并根据反馈调整策略。", "code": "class SelfReflectiveAgent:\n \"\"\"具备自我反思能力的Agent\"\"\"\n \n async def execute_with_reflection(\n self, \n task: str,\n max_retries: int = 3\n ) -> str:\n for attempt in range(max_retries):\n # 执行任务\n result = await self.execute_task(task)\n \n # 自我评估\n evaluation = await self.self_evaluate(task, result)\n \n if evaluation.score >= 0.8:\n return result # 质量达标\n \n # 根据评估反馈修正\n feedback = evaluation.feedback\n task = self.revise_approach(task, feedback)\n \n print(f\"尝试 {attempt + 1} 质量不达标（分数: {evaluation.score}），修正中...\")\n \n return result # 返回最后结果并标注质量警告\n \n async def self_evaluate(self, task: str, result: str) -> Evaluation:\n \"\"\"让Agent评估自己的输出质量\"\"\"\n prompt = f\"\"\"\n 任务: {task}\n 结果: {result}\n \n 请评估以上结果的完成度和质量，给出：\n 1. 完成度分数 (0-1)\n 2. 质量分数 (0-1) \n 3. 改进建议\n \"\"\"\n return await self.llm.evaluate(prompt)", "section_ref": "3.2.3", "runnable": true, "dependencies": [] }, { "id": "code-7", "language": "python", "description": "命令式 Agent 编程：明确指定 Agent 的每一步操作，类似于编写详细的操作手册。", "code": "# 命令式：精确控制每一步\nasync def imperative_search_agent(query: str):\n # 步骤1：调用搜索API\n search_results = await search_tool.search(query)\n \n # 步骤2：提取前5条结果\n top_results = search_results[:5]\n \n # 步骤3：逐一访问网页\n contents = []\n for url in top_results:\n content = await web_tool.scrape(url)\n contents.append(content)\n \n # 步骤4：综合回答\n answer = await llm.summarize(query, contents)\n return answer", "section_ref": "3.3.1", "runnable": true, "dependencies": [] }, { "id": "code-8", "language": "python", "description": "声明式 Agent 编程：描述目标和约束，让 Agent 自主规划执行路径。", "code": "# 声明式：描述目标和约束\nsearch_agent = Agent(\n name=\"research_assistant\",\n goal=\"帮用户深入研究问题，提供全面的答案\",\n tools=[search_tool, web_tool, summarizer],\n constraints=[\n \"至少引用3个来源\",\n \"信息必须来自可信来源\",\n \"回答要结构化、有引用\"\n ],\n planning_strategy=\"plan_and_execute\" # Agent自主规划\n)\n\nresult = await search_agent.run(\"什么是量子计算？\")", "section_ref": "3.3.1", "runnable": true, "dependencies": [] }, { "id": "code-9", "language": "python", "description": "在实际项目中，最常见的是混合式——渐进式自主（Progressive Autonomy）：核心流程用命令式确保可靠性，非核心环节让 Agent 自主决策。", "code": "class HybridAgent:\n \"\"\"混合式Agent：关键步骤命令式，其余声明式\"\"\"\n \n def __init__(self):\n self.mandatory_steps = [\n (\"validate_input\", self.validate),\n (\"execute_core_logic\", self.core_logic),\n (\"format_output\", self.format),\n ]\n self.autonomous_agent = Agent(\n tools=[db_tool, api_tool, calc_tool],\n strategy=\"react\"\n )\n \n async def run(self, task: str) -> str:\n # 命令式：验证输入\n validated = await self.validate(task)\n \n # 声明式：Agent自主完成核心任务\n result = await self.autonomous_agent.run(\n f\"完成以下任务：{validated}\\n\"\n f\"约束：{validated.constraints}\"\n )\n \n # 命令式：格式化输出\n return await self.format(result)", "section_ref": "3.3.3", "runnable": true, "dependencies": [] }, { "id": "code-10", "language": "python", "description": "事件驱动架构（EDA）与 Agent 编程天然契合——Agent 需要对环境变化做出实时响应，而事件正是环境变化的载体。", "code": "import asyncio\nfrom datetime import datetime\nfrom typing import Any\n\nclass Event:\n def __init__(self, type: str, data: Any, source: str):\n self.type = type\n self.data = data\n self.source = source\n self.timestamp = datetime.now()\n\nclass EventDrivenAgent:\n \"\"\"事件驱动的Agent\"\"\"\n \n def __init__(self):\n self.event_queue: asyncio.Queue[Event] = asyncio.Queue()\n self.handlers: dict[str, list[Callable]] = {}\n self.state: dict[str, Any] = {}\n \n def on(self, event_type: str, handler: Callable):\n \"\"\"注册事件处理器\"\"\"\n if event_type not in self.handlers:\n self.handlers[event_type] = []\n self.handlers[event_type].append(handler)\n \n async def emit(self, event: Event):\n \"\"\"发射事件\"\"\"\n await self.event_queue.put(event)\n \n async def event_loop(self):\n \"\"\"事件处理主循环\"\"\"\n while True:\n event = await self.event_queue.get()\n handlers = self.handlers.get(event.type, [])\n for handler in handlers:\n await handler(self, event)\n\n# 使用示例\nagent = EventDrivenAgent()\n\n@agent.on(\"user_message\")\nasync def handle_message(agent: EventDrivenAgent, event: Event):\n \"\"\"处理用户消息\"\"\"\n response = await agent.process_message(event.data)\n await agent.emit(Event(\"send_response\", response, \"agent\"))\n\n@agent.on(\"schedule_reminder\")\nasync def handle_reminder(agent: EventDrivenAgent, event: Event):\n \"\"\"处理定时提醒\"\"\"\n # 等待到指定时间后触发\n await asyncio.sleep(event.data[\"delay_seconds\"])\n await agent.emit(Event(\"notification\", \n f\"提醒：{event.data['message']}\", \"scheduler\"))", "section_ref": "3.4.1", "runnable": true, "dependencies": [] }, { "id": "code-11", "language": "python", "description": "- Proactive Agent（主动式）：主动发起行动，持续朝目标推进", "code": "class ReactiveAgent:\n \"\"\"反应式Agent：被动响应\"\"\"\n \n async def run(self):\n while True:\n event = await self.wait_for_event() # 阻塞等待\n response = await self.handle(event)\n await self.send(response)\n\nclass ProactiveAgent:\n \"\"\"主动式Agent：持续朝目标推进\"\"\"\n \n async def run(self):\n goal = self.load_goal()\n while not goal.is_achieved(self.state):\n # 主动感知环境\n situation = await self.assess_environment()\n \n # 主动规划下一步\n next_action = await self.plan_next(situation, goal)\n \n # 主动执行\n await self.execute(next_action)\n \n # 短暂等待，避免忙等\n await asyncio.sleep(self.poll_interval)\n\nclass HybridEventAgent:\n \"\"\"混合型Agent：同时支持主动和被动\"\"\"\n \n async def run(self):\n active_goal = self.get_active_goal()\n \n while True:\n # 使用wait_for实现主动轮询 + 被动响应\n done, pending = await asyncio.wait(\n [self.poll_environment(), self.wait_for_event()],\n timeout=self.poll_interval,\n return_when=asyncio.FIRST_COMPLETED\n )\n \n for task in done:\n result = task.result()\n await self.handle_result(result, active_goal)", "section_ref": "3.4.2", "runnable": true, "dependencies": [] }, { "id": "code-12", "language": "python", "description": "工具是 Agent 与外部世界交互的接口。在 Agent 编程范式中，工具不是简单的函数调用，而是一个带有丰富元数据的抽象。", "code": "from pydantic import BaseModel, Field\nfrom typing import Any, TypeVar, Generic\n\nT = TypeVar('T')\n\nclass ToolParameter(BaseModel):\n \"\"\"工具参数定义\"\"\"\n name: str\n type: str\n description: str\n required: bool = True\n default: Any = None\n enum: list[str] | None = None # 枚举值约束\n\nclass ToolResult(BaseModel):\n \"\"\"工具执行结果\"\"\"\n success: bool\n data: Any\n error: str | None = None\n metadata: dict[str, Any] = {} # token消耗、执行时间等\n\nclass Tool(Generic[T]):\n \"\"\"工具抽象基类\"\"\"\n \n def __init__(self, name: str, description: str):\n self.name = name\n self.description = description\n self.parameters: list[ToolParameter] = []\n \n def param(self, name: str, type: str, description: str, \n required: bool = True, **kwargs) -> 'Tool':\n \"\"\"链式定义参数\"\"\"\n self.parameters.append(ToolParameter(\n name=name, type=type, description=description, **kwargs\n ))\n return self\n \n @abstractmethod\n async def execute(self, **kwargs) -> ToolResult:\n \"\"\"执行工具\"\"\"\n ...\n \n def to_schema(self) -> dict:\n \"\"\"转换为LLM Function Calling格式\"\"\"\n return {\n \"type\": \"function\",\n \"function\": {\n \"name\": self.name,\n \"description\": self.description,\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n p.name: {\"type\": p.type, \"description\": p.description}\n for p in self.parameters\n },\n \"required\": [p.name for p in self.parameters if p.required]\n }\n }\n }\n\n# 使用示例\nsearch_tool = Tool(\"web_search\", \"搜索互联网获取最新信息\") \\\n .param(\"query\", \"string\", \"搜索关键词\") \\\n .param(\"num_results\", \"integer\", \"返回结果数量\", required=False, default=5)\n\nasync def search_execute(**kwargs) -> ToolResult:\n results = await search_api(kwargs[\"query\"], kwargs.get(\"num_results\", 5))\n return ToolResult(success=True, data=results)\n\nsearch_tool.execute = search_execute", "section_ref": "3.5.1", "runnable": true, "dependencies": [ "pydantic" ] }, { "id": "code-13", "language": "python", "description": "记忆是 Agent 保持上下文连续性的关键。Agent 的记忆分为短期和长期两个层次。", "code": "from dataclasses import dataclass, field\nfrom datetime import datetime\nimport json\n\n@dataclass\nclass MemoryEntry:\n content: str\n timestamp: datetime\n importance: float = 0.5 # 重要性评分 0-1\n tags: list[str] = field(default_factory=list)\n metadata: dict = field(default_factory=dict)\n\nclass AgentMemory:\n \"\"\"Agent记忆系统\"\"\"\n \n def __init__(self, short_term_limit: int = 20, \n long_term_db: Any = None):\n self.short_term: list[MemoryEntry] = [] # 短期记忆（对话历史）\n self.long_term = long_term_db # 长期记忆（向量数据库）\n self.short_term_limit = short_term_limit\n \n def add(self, content: str, importance: float = 0.5,\n tags: list[str] | None = None) -> MemoryEntry:\n \"\"\"添加记忆\"\"\"\n entry = MemoryEntry(\n content=content,\n timestamp=datetime.now(),\n importance=importance,\n tags=tags or []\n )\n \n # 短期记忆直接添加\n self.short_term.append(entry)\n \n # 重要记忆存入长期存储\n if importance > 0.7 and self.long_term:\n self.long_term.store(entry)\n \n return entry\n \n def get_context(self, max_tokens: int = 4000) -> str:\n \"\"\"获取上下文（智能裁剪）\"\"\"\n # 按重要性和时间综合排序\n scored = [\n (entry, self._relevance_score(entry))\n for entry in self.short_term\n ]\n scored.sort(key=lambda x: x[1], reverse=True)\n \n context_parts = []\n total_tokens = 0\n for entry, score in scored:\n tokens = len(entry.content) // 2 # 粗略估算\n if total_tokens + tokens > max_tokens:\n break\n context_parts.append(entry.content)\n total_tokens += tokens\n \n return \"\\n\".join(context_parts)\n \n async def recall(self, query: str, top_k: int = 5) -> list[MemoryEntry]:\n \"\"\"从长期记忆中检索相关内容\"\"\"\n if not self.long_term:\n return []\n return await self.long_term.search(query, top_k=top_k)\n \n def _relevance_score(self, entry: MemoryEntry) -> float:\n \"\"\"综合评分：时间衰减 + 重要性\"\"\"\n age_hours = (datetime.now() - entry.timestamp).total_seconds() / 3600\n time_decay = 1.0 / (1.0 + age_hours * 0.1)\n return entry.importance * time_decay", "section_ref": "3.5.2", "runnable": true, "dependencies": [] }, { "id": "code-14", "language": "python", "description": "规划器是 Agent 的\"战略大脑\"，负责将高层目标分解为可执行步骤。", "code": "from enum import Enum\n\nclass PlanningStrategy(Enum):\n REACT = \"react\" # 边思考边行动\n PLAN_AND_EXECUTE = \"plan_execute\" # 先规划后执行\n TREE_OF_THOUGHT = \"tot\" # 思维树探索\n REFLEXION = \"reflexion\" # 带反思的规划\n\nclass Planner:\n \"\"\"规划器抽象\"\"\"\n \n def __init__(self, strategy: PlanningStrategy, llm: Any):\n self.strategy = strategy\n self.llm = llm\n \n async def plan(self, task: str, context: dict) -> list[Action]:\n if self.strategy == PlanningStrategy.REACT:\n return await self._react_plan(task, context)\n elif self.strategy == PlanningStrategy.PLAN_AND_EXECUTE:\n return await self._full_plan(task, context)\n elif self.strategy == PlanningStrategy.TREE_OF_THOUGHT:\n return await self._tot_plan(task, context)\n elif self.strategy == PlanningStrategy.REFLEXION:\n return await self._reflexion_plan(task, context)\n \n async def _react_plan(self, task: str, context: dict) -> list[Action]:\n \"\"\"ReAct: 生成一个下一步行动\"\"\"\n prompt = f\"\"\"\n 任务: {task}\n 上下文: {json.dumps(context, ensure_ascii=False)}\n \n 请思考下一步应该做什么。回答格式：\n 思考: [你的推理]\n 行动: [工具名(参数)]\n \"\"\"\n response = await self.llm.generate(prompt)\n return [self._parse_action(response)]\n \n async def _full_plan(self, task: str, context: dict) -> list[Action]:\n \"\"\"Plan-and-Execute: 生成完整计划\"\"\"\n prompt = f\"\"\"\n 任务: {task}\n 可用工具: {json.dumps(context.get('available_tools', []))}\n \n 请制定一个完整的执行计划，分解为具体步骤。\n 每一步应指定要调用的工具和参数。\n \"\"\"\n response = await self.llm.generate(prompt)\n return self._parse_plan(response)\n \n async def _tot_plan(self, task: str, context: dict) -> list[Action]:\n \"\"\"Tree of Thought: 探索多条推理路径\"\"\"\n # 生成多个候选推理路径\n candidates = await self._generate_candidates(task, context, n=3)\n \n # 评估每条路径的可行性\n scored = []\n for candidate in candidates:\n score = await self._evaluate_path(candidate, task)\n scored.append((candidate, score))\n \n # 选择最优路径\n scored.sort(key=lambda x: x[1], reverse=True)\n return scored[0][0]", "section_ref": "3.5.3", "runnable": true, "dependencies": [] }, { "id": "code-15", "language": "mermaid", "description": "虽然 Agent 编程与微服务和 Serverless 有相似之处（都是模块化、可组合的），但它们在本质上截然不同。", "code": "graph LR\n subgraph 微服务\n A[API请求] --> B[路由] --> C[服务1] --> D[响应]\n B --> E[服务2] --> D\n end\n \n subgraph Agent\n F[目标/输入] --> G[Agent推理] --> H[动态选择工具] --> I[执行]\n G --> J[自主规划] --> K[调整策略] --> I\n I --> L[评估结果] --> G\n end", "section_ref": "3.6.1", "runnable": false, "dependencies": [] }, { "id": "code-16", "language": "python", "description": "- Agent作为\"编排大脑\"，智能地组合调用这些服务", "code": "# Agent + 微服务 + Serverless 的混合架构\nclass ProductionAgent:\n def __init__(self):\n # 微服务作为工具\n self.tools = {\n \"search\": MicroserviceTool(\"search-service\", \"/api/search\"),\n \"analytics\": MicroserviceTool(\"analytics-service\", \"/api/analyze\"),\n \"email\": MicroserviceTool(\"notification-service\", \"/api/send\"),\n # Serverless函数作为工具\n \"report_gen\": ServerlessTool(\"report-generator\", \n provider=\"aws_lambda\"),\n \"image_process\": ServerlessTool(\"img-proc\",\n provider=\"cloud_functions\"),\n }\n self.agent = Agent(tools=self.tools, strategy=\"react\")", "section_ref": "3.6.2", "runnable": true, "dependencies": [] }, { "id": "code-17", "language": "python", "description": "", "code": "# ===== Python 生态 =====\n# LangChain - 最流行的Agent框架\nfrom langchain.agents import create_react_agent, AgentExecutor\nfrom langchain.tools import tool\n\n@tool\ndef search(query: str) -> str:\n \"\"\"搜索互联网\"\"\"\n return search_api(query)\n\nagent = create_react_agent(llm, [search], prompt)\nexecutor = AgentExecutor(agent=agent, tools=[search])\nresult = executor.invoke({\"input\": \"查询最新AI新闻\"})\n\n# AutoGen - 微软的多Agent框架\nimport autogen\nassistant = autogen.AssistantAgent(\"assistant\", llm_config)\nuser_proxy = autogen.UserProxyAgent(\"user_proxy\")\nuser_proxy.initiate_chat(assistant, message=\"帮我分析数据\")", "section_ref": "3.7.1", "runnable": true, "dependencies": [ "langchain", "autogen" ] }, { "id": "code-18", "language": "typescript", "description": "userproxy.initiatechat(assistant, message=\"帮我分析数据\")", "code": "// ===== TypeScript 生态 =====\n// Vercel AI SDK - 轻量级Agent工具\nimport { generateText, tool } from 'ai';\nimport { z } from 'zod';\n\nconst result = await generateText({\n model: openai('gpt-4-turbo'),\n tools: {\n search: tool({\n description: '搜索互联网',\n parameters: z.object({ query: z.string() }),\n execute: async ({ query }) => searchAPI(query),\n }),\n },\n maxSteps: 5,\n prompt: '查询最新的AI新闻',\n});", "section_ref": "3.7.1", "runnable": true, "dependencies": [] } ], "tables": [ { "headers": [ "特征", "传统编程", "Agent编程" ], "data": [ [ "决策者", "程序员（硬编码）", "Agent（运行时推理）" ], [ "控制流", "预定义（if/else、循环）", "动态生成（LLM推理）" ], [ "行为确定性", "确定性（相同输入→相同输出）", "非确定性（可能选择不同策略）" ], [ "错误处理", "异常捕获、错误码", "自我反思、策略调整" ], [ "扩展方式", "修改代码", "添加工具/提示词" ], [ "环境感知", "无（或有限）", "持续感知并响应变化" ] ] }, { "headers": [ "场景", "推荐风格", "原因" ], "data": [ [ "简单、确定性任务", "命令式", "步骤固定，不需要推理" ], [ "关键业务流程", "命令式", "需要精确控制，降低风险" ], [ "开放式探索任务", "声明式", "需要灵活性和创造力" ], [ "复杂多步骤任务", "声明式", "步骤组合空间大，人工规划成本高" ], [ "快速原型", "声明式", "开发效率高" ], [ "生产环境", "混合式", "关键路径命令式，辅助路径声明式" ] ] }, { "headers": [ "维度", "微服务", "Serverless", "Agent编程" ], "data": [ [ "**编排方式**", "固定编排（API Gateway）", "事件触发", "自主决策" ], [ "**流程确定性**", "高（预定义路由）", "中（事件映射）", "低（动态推理）" ], [ "**扩展方式**", "水平扩展实例", "自动扩缩容", "添加工具/知识" ], [ "**状态管理**", "外部存储（DB/Redis）", "无状态", "内置记忆系统" ], [ "**错误处理**", "重试、熔断", "重试、DLQ", "自我反思、策略调整" ], [ "**适用场景**", "标准化业务流程", "事件驱动任务", "开放式复杂任务" ] ] }, { "headers": [ "考量因素", "Python", "TypeScript", "Rust/Go" ], "data": [ [ "生态成熟度", "⭐⭐⭐⭐⭐", "⭐⭐⭐", "⭐⭐" ], [ "开发效率", "⭐⭐⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐" ], [ "运行性能", "⭐⭐", "⭐⭐⭐", "⭐⭐⭐⭐⭐" ], [ "Web集成", "⭐⭐", "⭐⭐⭐⭐⭐", "⭐⭐⭐" ], [ "生产部署", "⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐⭐⭐⭐" ], [ "框架选择", "LangChain, AutoGen, CrewAI", "Vercel AI SDK, LangChain.js", "稀少" ], [ "适用场景", "原型、后端、数据分析", "Web应用、全栈", "高性能服务" ] ] } ], "key_takeaways": [], "common_pitfalls": [], "related_chapters": [ "ch01", "ch04" ] }