前  言

很多团队第一次接触智能体，是从一个聊天界面开始的。输入问题，模型给出回答；接上知识库、接口和工具以后，系统还能检索合同、查询库存、生成纪要，甚至起草业务建议。在演示阶段，这样的系统已经很像一个“会办事”的助手。

但进入真实业务以后，用户关心的不只是“能不能做出来”，还会继续追问“做错了怎么办”。一张采购申请会不会重复创建，审批人到底批准了哪个动作，模型依据的是哪一版合同，写回失败后系统会不会再次触发同样的动作，这些都不是聊天记录本身能够回答的。只要智能体开始读取业务数据、调用工具、推进流程，尤其是开始改写ERP、CRM、OA等业务系统，问题重心就会从回答质量转向任务过程本身。

本书讨论的AgentOS，不是某个单独产品，也不是几个框架的简单堆叠。它更像一套组织智能体项目的方法：把任务状态、依据来源、业务变更、审批、写回、观测和恢复连在一起。目标很具体：当智能体参与业务动作时，每一步都要知道从哪里来、到哪里去、出了问题该找什么记录。

本书沿着一条逐步添加能力的路线展开。第1章先写一个能跑通的小Agent；随后用Pydantic固定对象，用LangGraph表达流程，用LiteLLM统一模型调用，用MCP/FastMCP接入工具，用LlamaIndex和查询计划管理资料来源，用OPA处理策略和审批，用OpenTelemetry、pytest、promptfoo、队列和Temporal补上记录、评测、恢复和成本。最后把这些能力组合成一个基础AgentOS工程，并整理成后续项目可以复用的能力。从手写Agent到AgentOS的学习路径如下图所示。

本书采用一套贯穿始终的虚构企业背景—恒远装备集团。这个企业拥有ERP、CRM、OA、数据仓库和文档平台，也有采购、售后、法务、财务和运维等多类角色。书中的MOTOR-42 采购异常案例会从第1章开始出现，后面不断扩展。

起初，它只是一个“系统给出补货建议”的小例子。随后，它会逐步引入业务变更单、状态图、策略审批、幂等写回和运行记录，最终演化为一个可以完整运行的企业场景。这样安排的好处是，读者不需要在每一章都重新理解一套业务背景，而是可以把精力集中在新加入的机制和框架上。

为了便于动手实践，本书仍然配套了样例工程，但正文不会把读者带进大量目录、命令和工程文件名。初学阶段更重要的是看懂4件事：对象什么时候生成，状态怎样推进，审批和写回在哪里发生，失败后系统靠什么恢复。等这些关系看清楚以后，再回到源码中对照运行会更轻松。

真实项目还要锁定依赖版本，因为Agent框架的API演进很快。书末附录会单独说明版本基线和依赖原则，正文只在必要位置保留基础接口，不把包管理、命令行和完整工程结构放进主线叙述。每章先用一句话理解框架，如下表所示。

表  每章先用一句话理解框架

章    节 框架或主题 入门理解

第1章 Agent/AgentOS 入门 让模型不只“会回答”，还会查资料、做判断并准备执行任务

第2章 Pydantic 把模型文本和工具返回变成“字段说得清、能校验”的对象

第3章 LangGraph 用“流程图+状态”组织一次Agent任务

第4章 LiteLLM 给不同模型一个统一入口，再把路由和成本记录下来

第5章 MCP/FastMCP 让外部工具、资料和提示模板能被智能体按约定发现和调用

第6章 LlamaIndex/RAG 先查到有来源的资料，再让模型基于资料回答

第7章 OPA/Rego 把“能不能做”从代码中抽出来，变成可测试的策略

第8章 OpenTelemetry/评测 给任务运行路线、业务动作和上线检查留下证据

第9章 队列/Temporal 让跨时间、跨系统、跨人的任务不靠一次请求硬撑到底

第10～12章 组合工程和平台化 把做对的对象、流程、工具、策略和评测沉淀给下一批项目复用

本书不会把每个框架讲成独立说明书，而是尽量按照“先看问题，再看做法，然后看还差什么”的顺序展开。每章通常都会先给出一个初学者可能写出来的版本，再说明它放入企业业务后会遇到什么麻烦。

在此基础上，书中再引入一个合适的框架或对象模型，最后放回同一个场景中检查。希望读者读完整本书之后，不只是记住LangGraph、LiteLLM、MCP、LlamaIndex、OPA或OpenTelemetry这些名字，更能判断它们为什么要放在一起，又该怎样组合成一个可用、可解释、可继续演进的企业智能体系统。

著    者

2026年8月