最近一两年AI Agent 可以说是 AI 应用开发里热度最高的方向之一。不少同学在 B 站收藏了很多 Agent 教程但真到自己动手做时还是会卡在环境搭建、工具调用、记忆管理、Function Calling 这些细节上。本文把一套能落地的 AI Agent 学习路径整理成文字版从核心概念讲起再到一个完整的实战项目让 Agent 通过 Elasticsearch REST API 自动分析日志、统计错误、定位异常服务。这篇文章适合下面几类读者刚开始接触 AI Agent想搞清楚它和普通聊天机器人有什么区别的同学已经会调用大模型 API但不知道怎么让模型使用工具、执行任务的开发者后端工程师或运维同学想给日常日志分析、故障排查加一个“智能助手”正在做 AI Agent 框架选型想知道 LangChain、LangGraph、手写调用之间怎么取舍的人。学完本文之后你会掌握 Agent 的核心原理读懂 ReAct 和 Function Calling并且能直接跑起来一个“日志分析 Agent”项目。文章中的代码不依赖复杂的平台只要你有可用的 OpenAI 兼容接口很多国产大模型也提供同样的兼容接口再配一个本地或测试环境的 Elasticsearch就能复现。1. AI Agent 是什么为什么值得系统学1.1 从“聊天机器人”到“智能体”先来看一个最简单的问题传统聊天机器人和 AI Agent 有什么区别传统聊天机器人做的事情是“你说一句我回一句”。模型只负责把输入文本转换成输出文本它不能主动去查数据库、不能调用外部系统、不能感知外部环境的变化。你的问题一旦需要“实时数据”它就只能靠训练时的知识来猜或者告诉你“我无法获取最新信息”。AI Agent 则往前迈了一大步。你可以把它理解成一个带“手脚”的大模型大模型是大脑负责理解任务、拆解步骤、决定下一步做什么工具是手脚包括调用 REST API、查询数据库、执行代码、操作浏览器等记忆是工作区让 Agent 能记住上下文、历史结果和用户偏好执行循环是运转机制Agent 通过“思考-调用-观察结果-再思考”不断逼近最终答案。换句话说Agent 的价值不在于“能聊天”而在于“能完成任务”。同样是“帮我看看今天订单服务的错误日志”聊天机器人只能给你一段通用建议Agent 可以去查 Elasticsearch返回真实的错误数量、错误分布、受影响的服务然后再给你分析结论。1.2 AI Agent 的核心组成从工程实现角度看一个完整的 AI Agent 通常由五部分组成组成作用常见实现LLM 大脑理解任务、规划步骤、生成文本GPT 系列、DeepSeek、Qwen 等工具集 Tools让 Agent 能与外部系统交互REST API、Python 函数、数据库查询执行循环 Loop决定何时调用工具、何时给出最终答案ReAct、Function Calling、Agent 框架记忆 Memory保存短期上下文和长期知识消息列表、向量数据库、Redis、KV 存储反馈与评估判断结果是否正确、是否需要重试人工反馈、规则校验、评测集初学者最容易忽略的是“工具集”和“执行循环”。很多人以为把大模型 API 接上就是 Agent其实那只是一个聊天机器人。真正的 Agent 难点在于如何让模型正确选择工具如何把工具返回的复杂结果重新组织成用户能理解的答案如何在多步调用中保持上下文不混乱如何防止模型在一个错误结果上反复循环。这些正是本文后面要逐步解决的核心问题。1.3 典型应用场景AI Agent 不是只能做 Demo它在很多真实业务场景中已经落地智能客服Agent 自动查订单、查物流、处理售后而不是只回复“请您稍等”日志与运维分析Agent 根据自然语言自动查询监控系统、ES 日志、告警平台辅助定位故障数据分析Agent 连接数据仓库把“本月各渠道销售额是多少”变成 SQL 并执行然后返回图表和结论办公自动化Agent 自动整理邮件、生成周报、填写表单代码助手Agent 读取仓库代码、搜索 API 文档、执行测试命令辅助开发者完成编码任务。在这些场景中Agent 的共同特征都是把“大模型的推理能力”和“系统的操作能力”连接在一起。这也是我们接下来要重点练习的能力。2. 环境准备与框架选型2.1 本地环境要求在开始写代码之前先准备一套可复现的开发环境。本文示例基于 Python版本建议使用 3.10 或更高版本。原因有两个新版 OpenAI SDK 和一些 Agent 框架对 Python 3.9 以下版本的支持越来越弱项目里用到类型标注和 f-string 等语法在 3.10 以上体验更稳定。如果你不确定本机 Python 版本可以先执行命令检查python --version操作系统方面Windows、macOS、Linux 都可以跑通。命令行的差异主要在环境变量设置上Windows 下可以用setmacOS/Linux 下可以用export后面文章会分别说明。另外如果你想跑通本文的完整案例需要准备一个 OpenAI 兼容的模型接口包括base_url、api_key、model三个信息一个可访问的 Elasticsearch 实例端口默认是9200如果没有 Elasticsearch也没关系代码里内置了 Mock 模式可以直接用模拟日志演示 Agent 的运行流程。这里的重点是思路而不是具体平台。你可以使用任何提供 OpenAI 兼容接口的模型服务只需要修改环境变量即可。2.2 安装依赖新建一个项目目录并创建虚拟环境mkdir agent-demo cd agent-demo python -m venv venvmacOS / Linux 激活虚拟环境source venv/bin/activateWindows PowerShell 激活虚拟环境venv\Scripts\Activate.ps1然后在项目根目录创建requirements.txtopenai1.0.0 requests2.31.0安装依赖pip install -r requirements.txt这里没有锁定具体版本号因为 OpenAI SDK 迭代比较快。需要说明的是不同 SDK 版本在调用参数上可能有细微差异本文代码以 OpenAI SDK 1.x 的通用写法为准。如果你安装到了更新的版本遇到参数报错时优先查看官方文档中的迁移说明。2.3 主流框架怎么选很多同学一开始会在框架选型上纠结很久。这里先做一个横向对比。方案特点适合场景手写 OpenAI SDK Function Calling代码直观原理清晰无框架依赖学习原理、轻量 Agent、定制化强LangChain生态丰富组件多文档全快速做原型、需要大量现成组件LangGraph图结构编排 Agent 流程支持状态管理生产级复杂流程、多人协作开发AutoGen多智能体对话模式研究实验、多角色模拟Dify低代码/可视化平台非技术人员搭建 AI 应用我的建议是第一遍学习不要选太重的框架直接手写一遍 OpenAI 兼容接口的 Function Calling。原因很简单手写能让你理解 Agent 的底层循环而不是被框架的抽象封装住很多框架出问题时最终还是得回到“消息格式对不对”“工具返回结构对不对”这些底层问题手写的代码量其实不多核心循环大概几十行就能跑通。等你理解了原理再去用 LangGraph 这类框架做流程编排会事半功倍。本文的实战部分就采用“手写 OpenAI 兼容接口 Function Calling”的方式。2.4 项目目录规划为了让代码结构清晰我们先规划好项目目录。本文最终的项目结构如下agent-demo/ ├── venv/ # 虚拟环境 ├── requirements.txt # 依赖 ├── init_es_data.py # 初始化 ES 测试数据 ├── tools.py # 工具层封装 ES REST API ├── agent.py # Agent 核心循环 └── main.py # 命令行入口各文件职责tools.py负责所有外部操作相当于 Agent 的“手脚”agent.py负责大模型调用、工具选择、结果回传相当于 Agent 的“大脑”main.py负责接收用户输入启动 Agent。这种拆分的好处是以后你想给 Agent 加新能力只需要在tools.py里新增一个函数然后在agent.py的工具描述里注册即可不需要改动主流程。3. 核心原理ReAct 与 Function Calling3.1 ReAct思考-行动-观察循环ReAct 是 Agent 最核心的推理范式之一全称是 Reasoning and Acting意思是“推理与行动交替进行”。它的执行过程可以拆成下面几步用户提出任务模型思考当前任务需要哪些信息并决定调用哪个工具程序执行模型指定的工具返回结果模型观察工具结果判断任务是否完成如果没完成继续重复第 2 步到第 4 步如果完成了模型生成最终答案返回给用户。用一个用户的真实问题来举例用户提问最近1小时有多少ERROR日志主要来自哪些服务模型可能的推理过程如下第1步 思考我需要先查询ES统计最近1小时的ERROR日志数量。 行动调用 count_error_logs(time_range1h) 观察返回 45 第2步 思考数量已经拿到现在需要知道主要来自哪些服务。 行动调用 get_error_top_services(time_range1h) 观察返回 [order-service:20, pay-service:15, gateway:10] 第3步 思考数据已经足够可以生成最终结论。 回答最近1小时共有45条ERROR日志主要集中在order-service和pay-service……这个“思考-行动-观察”的循环就是 ReAct 的核心。它让模型不再是一次性输出答案而是像一个真正的工作人员那样一步步收集信息、做出判断。在实际代码中你不需要真的让模型输出“思考”和“观察”这些文本。OpenAI 兼容接口的tool_calls机制已经帮我们完成了大部分工作模型直接返回“我要调用哪个工具、参数是什么”程序执行后再把结果作为tool消息送回模型。3.2 Function Calling模型怎么“使用”工具Function Calling 是当前实现 AI Agent 最主流的技术方案。它的思路并不是让模型真的去执行代码而是让模型“声明”它想调用哪个函数以及函数的参数是什么。举个例子。假设我们定义了一个函数get_weather(city)那么在调用模型时需要把这个函数的描述以 JSON Schema 的形式传给模型{ type: function, function: { name: get_weather, description: 查询指定城市的天气, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京 } }, required: [city] } } }当用户问“北京今天下雨吗”时模型可能会返回一个特殊的tool_calls结果{ name: get_weather, arguments: {\city\: \北京\} }注意模型并没有真正查询天气。它只是说“我建议调用get_weather函数参数是北京。”真正执行函数的是我们自己的代码result get_weather(北京)然后把执行结果作为tool消息再次发给模型模型看到结果后才能组织最终回答。这就是 Function Calling 的核心思想模型负责“决策”代码负责“执行”。这样做有几个好处模型不需要真的写可执行代码降低了安全风险工具的执行结果可控我们可以增加权限校验、日志记录、超时重试模型可以把复杂的工具参数结构化输出避免自由文本解析的误差。3.3 记忆与上下文管理Agent 的记忆可以分为短期记忆和长期记忆。短期记忆就是指当前会话的消息列表。在 Function Calling 场景中消息列表不仅包含用户和模型的对话还包含工具调用的过程记录。一个典型的消息序列如下system: 你是日志分析助手 user: 最近1小时有多少ERROR日志 assistant: 我想需要调用统计工具 [...tool_calls...] tool: 工具执行结果返回 45 assistant: 最近1小时共有45条ERROR日志。短期记忆是 Agent 实现多轮任务的基础。如果每次请求都重新拼一个空消息列表模型就无法感知“刚才已经查过日志数量”这个事实。长期记忆则用于跨会话保存信息比如用户的偏好、历史故障记录、企业知识库等。实现方案很多向量数据库如 Milvus、Qdrant、pgvector存语义向量适合做知识库检索Redis 或 MySQL 存结构化信息适合保存用户状态和任务记录文件系统存日志和中间结果适合离线分析和审计。在今天的日志分析 Agent 中我们用消息列表实现短期记忆就足够。但如果将来要让 Agent 记住“哪台服务器经常出问题”就需要引入长期记忆模块。3.4 多智能体与工作流编排当任务变得复杂时单个 Agent 可能难以胜任。比如一个完整的故障排查流程包括收集日志、分析异常、查询变更记录、通知负责人。如果全让一个 Agent 做工具列表会非常长上下文也容易混乱。这时可以把任务拆成多个专用 Agent日志分析 Agent负责查询