从零搭建自定义AI Agent：核心原理与工程实践

先下一个结论AI Agent 和大模型、LLM 这三件事放在一起早就不该停留在“调接口、发 Prompt、看返回”的阶段了。真正值得学的是怎么把一个只有 Chat 能力的模型变成一个能自己拆任务、调工具、看结果、记忆上下文的智能体。这篇文章按 2026 年实际可落地的开发方式把从零搭建自定义 AI Agent 的完整链路拆开覆盖环境准备、ReAct 循环、Function Calling、RAG、记忆、多智能体协作、部署排查和面试考点。适合两类人看一类是刚入门大模型开发、看过很多教程但没动手搭过 Agent 的另一类是已经会调 LLM API但不知道如何把简单调用变成可上线的工程体系。我见过太多学习 Agent 的人卡在同一步代码跑通了但换个任务就废Demo 能聊天但没法接入真实业务用框架非常顺但框架一旦报错就完全不知道从哪查。这类问题的根源基本都一样没有把 Agent 的运行逻辑、工具调用机制、上下文和记忆管理这些底层环节搞透。下面按实际开发顺序走一遍。1. AI Agent 到底是什么为什么 2026 年学这套特别关键1.1 先纠正一个最常见的误解Agent 不是 Chat 套壳很多人以为 Agent 就是在 LLM 外面加一层 System Prompt让它“扮演”一个助手。这种理解不能说完全错但会严重限制后面的工程能力。真正的 AI Agent至少要具备四个能力能理解用户输入的复杂任务而不是只做单轮问答能自主拆解任务把大目标拆成可执行的小步骤能调用外部工具比如搜索、数据库、API、计算器、文件读写能根据工具返回结果调整下一步动作而不是盲目继续。这四个能力合起来才叫“智能体”。只做第一项那是聊天机器人做到前两项算是任务型助手四项都做才能叫 Agent。从开发角度看还有个更重要的区别Chat 应用是“请求-响应”模型用户发一句模型回一句结束。Agent 应用是“循环模型”模型可能要进行多轮观察、思考、行动直到任务完成或者达到终止条件。这一个差异决定了代码结构完全不同。1.2 一套完整的 Agent 开发体系包含哪些能力如果你准备系统学习 Agent 开发不要只盯着某一个框架或者某一个大模型而是要把下面这些模块连成一条线模块解决什么问题常见实现方式LLM 接入让 Agent 有基础的理解和生成能力云 API、本地模型、企业内部网关提示词工程约束模型的行为边界和输出格式System Prompt、Few-shot、结构化输出任务拆解把复杂问题分成多个子任务ReAct、Plan-and-Execute、思维链工具调用Agent 能操作外部系统Function Calling、Tool Calling、MCP记忆管理Agent 能记住上下文和历史经验短期上下文窗口、向量库长期记忆RAG给模型补充领域知识文档切分、Embedding、向量检索多智能体协作多个 Agent 分工完成复杂流程LangGraph、AutoGen、自研编排工程化让 Agent 稳定、可观测、可上线日志、队列、超时、重试、评估这套体系里LLM 只是底层的“推理引擎”真正决定一个 Agent 能不能用的是你怎么设计它的循环、记忆、工具和失败处理。1.3 零基础到可实践的学习路线与时间预期我不太建议一上来就学 LangChain 或者 LangGraph 这样的重框架。原因很简单框架把很多底层逻辑封装掉了你会用框架但不理解报错原因。更稳妥的路线是先用原生代码调用 LLM API理解输入输出结构手工实现一个最小 ReAct 循环理解 Agent 是怎么一步步思考的再引入工具调用和 RAG最后再用框架做工程化和复杂编排。这条路线走下来的时间如果每天能投入 2 到 3 小时基础好的话两周能跑通最小 Demo一个月能做出一个带记忆、带工具、能批量处理任务的 Agent。关键不在于时间而在于每一步都要留下可运行、可验证的代码。2. 开始前的环境准备模型接入、依赖安装与项目目录2.1 三种模型接入方式怎么选本地模型、云 API、企业内部网关搭建 Agent 之前第一件事不是写代码而是确定模型怎么接。2026 年的主流选择有三种各有利弊。第一种是本地部署。Ollama 是当前最省事的本地大模型运行工具之一能拉取多种开源模型并提供一个兼容 OpenAI 格式的本地接口。优点是数据不出本机、免费、方便调试缺点是需要自己准备显卡或较大的内存响应速度受硬件限制。适合学习阶段和个人项目。第二种是云 API。直接使用国内外大模型厂商提供的在线接口优点是部署简单、模型能力强、无需关心硬件缺点是按量计费并且需要在代码里管理 API Key。第三种是企业内部网关。一些公司会搭建统一的大模型网关对外提供兼容接口对内做权限、审计、成本控制。这种接入方式最接近生产环境但一般需要公司内部环境。对于零基础学习我的建议是优先本地部署一个小模型同时准备一个云 API 备用。本地模型便于无限调试云 API 用来对照能力差异。2.2 推荐的项目目录结构一个干净的项目目录能省掉后面大量排查时间。下面是我自己在 Agent 项目里常用的结构agent-project/ ├── agent/ │ ├── __init__.py │ ├── core.py # Agent 核心循环 │ ├── llm.py # LLM 客户端封装 │ ├── tools.py # 工具注册与实现 │ ├── memory.py # 记忆模块 │ └── rag.py # 向量检索模块 ├── data/ # 文档、知识库、测试数据 ├── logs/ # 运行日志 ├── config/ │ └── settings.yaml # 模型、参数、路径配置 ├── scripts/ │ └── run_demo.py # 启动脚本 ├── tests/ # 单元测试和样例测试 └── requirements.txt不要把所有代码都塞进一个文件。Agent 开发过程中你一定会反复修改工具定义、记忆策略和 Prompt模块化做得越好排查问题越快。2.3 最小依赖清单与安装验证一个最小 Agent 项目核心依赖其实不多# 示例依赖实际版本以你的环境为准 openai1.30.0 ollama python-dotenv pyyaml如果你的 Agent 需要 RAG再加向量库和 Embedding 相关依赖如果要接网页搜索再加对应的 SDK。永远不要一开始就把所有依赖装齐按需安装能让环境问题简单很多。安装之后先跑一句最基础的连通性验证from openai import OpenAI # 如果使用本地 Ollamabase_url 指向本地服务 client OpenAI( base_urlhttp://localhost:11434/v1, api_keyollama ) resp client.chat.completions.create( modelqwen2.5:7b, # 替换为你本地实际拉取的模型名 messages[{role: user, content: 只回答两个字正常}] ) print(resp.choices[0].message.content)如果这一步能正常输出说明模型接入没有问题。后面所有 Agent 逻辑都可以建立在这个调用之上。3. 手写一个最小 Agent从 LLM 调用到 ReAct 循环3.1 第一版不调用工具只用 Prompt 控制输出很多人一开始就容易犯一个错误直接上复杂框架。实际上最小可运行的 Agent 可以只用 Prompt 实现连工具都不需要。比如你希望 Agent 能拆解任务并输出三步执行计划可以这样写SYSTEM_PROMPT 你是一个任务规划助手。请按以下规则输出 1. 把用户任务拆成最多5个子步骤 2. 每个子步骤一行以“STEP:”开头 3. 不输出额外解释。 messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: 帮我写一篇关于大模型RAG落地的技术博客} ]这个版本虽然简单作用却很大。它让你验证模型是不是理解 Prompt 格式、会不会乖乖按格式输出、输出结果是否稳定。这一步不过关后面加功能只会更乱。我会建议所有初学者先把这一版跑通然后连续发 10 条不同任务看看输出格式是否有 100% 稳定。不稳定的话先调 Prompt而不是急着加代码。3.2 第二版加入 ReAct 推理循环ReAct 是目前理解 Agent 运行逻辑最好的切入点。它的核心是让模型在“思考-行动-观察”之间循环Thought分析当前状态决定下一步该做什么Action选择要调用的工具传入参数Observation查看工具返回的结果然后重复直到有 Final Answer。手写一个最小 ReAct 循环大概长这样MAX_STEPS 5 messages [ {role: system, content: 你是一个使用 ReAct 方式工作的助手。}, {role: user, content: 请查询一下 2026 年春节的具体日期} ] for step in range(MAX_STEPS): resp client.chat.completions.create( modelqwen2.5:7b, messagesmessages, temperature0.2, ) content resp.choices[0].message.content print(fStep {step 1}: {content}) # 这里判断模型输出是否已经给出 Final Answer if Final Answer: in content: break # 把当前输出加入 messages让模型继续思考 messages.append({role: assistant, content: content})上面这个写法是示意不要把大模型返回的文本直接无脑塞回 messages。实际开发中你要解析 content 里的 Action执行对应工具再把结果作为 Observation 拼进下一轮对话。3.3 理解 Agent 的运行逻辑观察、思考、行动、总结ReAct 循环看起来简单但有几个细节决定它能不能稳定工作。第一个是终止条件。如果没有明确的终止条件Agent 可能无限循环。常见做法包括最大步数限制、检测到 Final Answer、工具调用结果为空或异常时直接结束。多一个条件Agent 就多一分可控。第二个是上下文累积。每一轮思考、行动和观察都会写进 messages模型需要处理的 token 越来越多。长任务跑到后面早期信息可能被截断或遗忘。这个问题不是 ReAct 独有的但所有 Agent 开发都会遇到。第三个是模型能力边界。小模型经常在 ReAct 循环里“想太多”或者“假装调用了工具但没传参数”。遇到这种情况不要急着怪模型先检查 Prompt 里是否给出了工具清单、参数格式和否定情况的处理方式。4. 给 Agent 装上记忆会话记忆与长期记忆4.1 记忆不是把聊天记录全塞进上下文Agent 要有记忆这是对的。但很多人实现记忆的方式就是把所有历史消息一股脑拼到 Prompt 里。这在短期会话里可行一旦上下文窗口被占满就会出现两个问题一是 token 费用升高二是模型会被无关内容干扰回答质量下降。所以记忆必须分层。第一层是短期会话记忆。直接用 messages 保留最近几轮对话即可超出范围就做摘要。第二层是业务记忆。保存用户偏好、任务状态、关键结论下一轮任务可以直接读取。第三层是长期知识记忆。把历史经验和领域知识写入向量库需要时检索出来。4.2 基于向量库的长期记忆长期记忆的典型实现方式是先对文本做 Embedding存进向量数据库当 Agent 需要历史信息时把当前问题也做 Embedding去向量库中检索相似片段再交给 LLM 使用。一个简易流程是# 示例写入记忆 memory_id vector_store.add_texts( texts[用户偏好喜欢简洁的技术教程不要太多术语], metadata{user_id: user_001} ) # 示例检索记忆 relevant_memories vector_store.similarity_search( 这个用户喜欢什么风格的内容, k3 )在工程实现上向量库选型要考虑数据量、响应速度和部署成本。数据量小选轻量级方案数据量大再考虑独立向量数据库服务。4.3 记忆模块常见坑记忆模块最常见的坑有四个。一是没有给记忆加时间戳。Agent 检索到的记忆可能已经过期用户需求早就变了。正确做法是在 metadata 里记录时间检索排序时加入时间衰减。二是检索片段太碎。向量检索按语义相似度取 TOP K但单条片段如果没有上下文模型读不懂。建议写入记忆时按“事件”存储每个事件包含背景、动作、结果。三是记忆与当前任务关联度低。检索结果不能全部塞给模型先做一次相关性排序只保留真正有用的内容。四是权限问题。如果你的 Agent 服务多人使用记忆必须按用户隔离不能出现 A 用户检索到 B 用户数据的情况。5. 调用工具与接入 RAG让 Agent 能处理真实业务5.1 Function Calling / Tool Calling 的两种实现方式Agent 不能只靠模型知识回答真实业务里必须让它操作外部系统。现在主流做法是 Function Calling也叫 Tool Calling。第一种方式是让模型输出结构化的工具调用请求。OpenAI 兼容接口里工具定义长这样tools [ { type: function, function: { name: query_weather, description: 查询指定城市的天气, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] resp client.chat.completions.create( modelqwen2.5:7b, messagesmessages, toolstools, tool_choiceauto, )模型返回的内容里如果tool_calls不为空就说明模型决定调用工具。你的代码需要解析出来执行对应的 Python 函数再把结果追加到对话里。第二种方式是纯 Prompt 约定。不依赖接口的 tools 参数而是让模型输出 JSON然后代码解析 JSON 分发执行。这种方式兼容性更好但稳定性差小模型经常输出无效 JSON。实际项目里优先用第一种。只有模型不支持工具调用时才考虑用 Prompt 硬解析。5.2 用 RAG 给 LLM 补上领域知识RAG 是目前给大模型补知识最实用的手段。它不是让模型记住更多内容而是先把文档切成小块做 Embedding 存入向量库用户提问时先检索出相关片段再让模型基于这些片段回答。RAG 做得好不好关键不在向量库而在三个环节文档切分、Embedding 选型、检索排序。文档切分要注意不要按固定长度硬切尽量按段落、标题、语义边界切。切分太碎会让模型失去上下文切分太大又会导致检索噪音多。Embedding 模型选择要看语种和领域。中文场景建议用中文效果更好的 Embedding 模型代码、金融、医疗等垂直领域如果有领域微调的 Embedding 模型效果通常会更好。检索排序部分基础做法是相似度 TOP K。但真实业务里往往还要加入关键词过滤、时间过滤、权限过滤和重排序模型。5.3 一个综合示例从任务输入到工具调用再到结果校验下面用伪代码把整个链路串起来def run_agent_task(user_input): messages [{role: system, content: SYSTEM_PROMPT}] messages.append({role: user, content: user_input}) for step in range(MAX_STEPS): resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolsALL_TOOLS, tool_choiceauto, ) msg resp.choices[0].message if msg.tool_calls: for tool_call in msg.tool_calls: result execute_tool(tool_call) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) else: return msg.content return 达到最大步骤任务未完成这个流程里execute_tool必须做三件事解析参数、执行函数、把异常转化成可读文本。工具调用失败不能直接抛异常而是要把错误信息返回给模型让模型决定是换参数重试还是放弃。此外工具返回结果要控制长度。如果工具返回了大段日志或完整数据库记录直接塞给模型会撑爆上下文。常见做法是只保留关键字段超长内容先截断或做摘要。6. 多智能体协作、批量任务与工程化6.1 不急着上框架先看单 Agent 能不能稳定很多教程一上来就教多 Agent 编排这对新手非常不友好。多个 Agent 意味着通信协议、任务分发、结果汇总、失败重试、互相阻塞等问题任何一环出错排查成本都会成倍上升。所以我强烈建议先把单个 Agent 在业务场景里跑稳再考虑多 Agent。单 Agent 能稳定完成任务说明你的工具定义、记忆、RAG 都已经过关这时候引入多 Agent 才是在做组合优化而不是在补基础坑。6.2 多 Agent 协作的三种典型模式实际项目里多 Agent 协作不是越多越好而是按任务结构选型。流水线模式适合任务阶段清晰的情况。比如文案 Agent 产出初稿审核 Agent 做合规检查优化 Agent 做表达润色前一个 Agent 的输出就是下一个的输入。路由模式适合任务类型多样的情况。一个主 Agent 先判断用户意图再分发给对应的专业 Agent。典型场景是客服系统售后问题转售后 Agent技术问题转技术 Agent销售问题转销售 Agent。协商模式适合需要多个角色共同决策的情况。多个 Agent 分别从不同角度分析问题主 Agent 汇总后给出结论。这种方式效果可能好但成本和耗时也高不适合实时性要求高的场景。6.3 批量任务的输入输出控制真实业务里Agent 很少只处理单个任务更多是批量跑。批量任务的核心不是并发而是可控性。我一般会先跑 3 到 5 条样本确认输入输出都符合预期再放大到全量。放大时重点检查输入数据格式是否统一、输出文件名是否冲突、失败任务是否有记录、日志是否按任务 ID 分离。批量任务还需要考虑幂等性。如果同一个任务被重复执行会不会产生重复数据如果会就要在任务表里加去重字段或者在写入时做唯一性约束。另一个容易被忽略的问题是速率控制。云 API 通常有每分钟请求数限制本地模型有算力限制。不要把所有任务一次性提交要用队列控制并发避免触发限流或把机器打挂。6.4 稳定性、超时与重试策略Agent 类任务天然不稳定因为 LLM 的输出有随机性。工程化要做的是把这种随机性控制住。超时设置要区分两个层级单次 LLM 调用超时和整个 Agent 任务超时。单次调用超时建议在 30 到 120 秒之间整个任务根据步骤数设定上限。重试策略也不能一刀切。网络超时可以重试模型返回空内容可以重试但工具执行成功而结果不符合预期时重试不一定有用这时候更该做的是记录日志、调整 Prompt 或换模型。日志里至少要包含任务 ID、输入内容、每一步的思考、工具名、工具参数、工具返回、最终输出、耗时、token 消耗。没有这些信息Agent 一旦跑偏你根本不知道是在哪一步偏的。7. 部署上线、观测与常见排查7.1 从脚本到 API 服务本地 Demo 跑通之后要变成可调用的服务通常有两种方式。第一种是直接用 FastAPI 把 Agent 包成 HTTP 接口。这种方式适合内部工具和小型应用。要注意的是Agent 任务可能耗时很长HTTP 请求容易超时。比较好的做法是接口先返回任务 IDAgent 在后台执行前端通过查询接口获取结果。第二种是接入消息队列做异步任务。适合生产环境和批量任务。任务进入队列后由 Worker 消费执行结果写入存储再通过状态接口或回调通知调用方。部署时还要考虑配置管理。模型名、API Key、向量库地址、工具开关等配置不能写死在代码里要走配置文件或环境变量。7.2 观测日志、跟踪与评估Agent 的调试比普通程序难。普通程序是确定性的输入相同输出相同Agent 带随机性同一输入可能走不同分支。所以观测能力是必须的。第一层是日志。不能用 print 代替。要给每条日志加时间、级别、任务 ID并按模块写不同日志文件。第二层是链路跟踪。每个 Agent 任务内部有多少步、调用了哪些工具、每步耗时多少、token 消耗多少都需要记录。第三层才是效果评估。准备一组固定测试集每次修改 Prompt 或代码后用同一批问题跑一遍。记录成功率、输出质量、平均耗时、平均步骤数。没有评估集的 Agent 项目后面优化就是一个黑盒。7.3 常见排查链路Agent 出现问题先别急着改 Prompt按照下面的顺序排查看现象。是启动报错、任务卡住、输出为空、输出格式不对还是结果明显错误看输入。输入文件的编码、路径、格式、字段是否完整有时候是数据问题不是代码问题。看环境。依赖版本是否冲突、模型路径是否正确、API Key 是否有权限、端口是否被占用。看日志。Agent 在哪一步开始不正常是任务拆解出错还是工具调用失败还是 RAG 检索结果太差看参数。并发数、超时时间、步数上限、temperature 是否设置合理。不要一上来就把并发拉满先用小并发压测。最后看模型本身。同一个 Prompt 在云 API 上正常、在本地小模型上不正常这种情况非常常见说明不是代码问题而是模型能力不够。这个排查链路里日志是最重要的。没有日志所有排查都靠猜。8. AI Agent 面试考点、项目包装与后续学习8.1 AI Agent 面试到底在考什么2026 年的大模型 Agent 岗位面试基本不会只问“什么是 LangChain”。面试官更关注的是你是否理解 Agent 的本质。常见问题包括ReAct 和 Plan-and-Execute 有什么区别Function Calling 的原理是什么如果模型不支持 Function Calling你怎么实现工具调用RAG 中文档切分长度怎么定检索结果不相关怎么处理Agent 怎么防止死循环多个工具返回结果互相矛盾时Agent 如何决策如何控制 Agent 的 token 成本本地大模型和云 API 做 Agent 各有什么优劣势这些问题没有标准答案但都有一个共同点需要你用实际项目经验回答而不是背概念。8.2 把练手项目包装成可表达的简历项目练手项目如果只是“调用了大模型接口”写进简历价值不大。要让项目有区分度可以从三个方向包装。第一个方向是解决真实问题。比如做一个“基于 RAG 的合同审查 Agent”输入风险点输出条款分析结果接入了文档解析、向量检索和结构化输出。问题越具体越能体现能力。第二个方向是体现工程稳定性。在项目描述里写清楚日志、重试、超时处理、评估集这些工程细节。面试官往往更看重这个因为这说明你不只是写 Demo 的人。第三个方向是体现效果的数据。比如“回答准确性从 60% 提升到 85%”“单条任务耗时从 40 秒降到 15 秒”“支持 1000 条批量任务稳定运行”。有数据项目才有说服力。8.3 后续学习建议微调、框架与安全学完基础 Agent 开发之后有三个进阶方向。第一个是大模型微调。当 Prompt 和 RAG 都解决不了领域问题时才需要微调。微调的重点不是跑通训练代码而是搞清楚数据构造、评估方法和什么时候该微调。有时候微调收益还不如把 RAG 做细。第二个是代码级框架和数据结构。LangGraph、AutoGen 这类框架值得学但要在手写 Agent 之后再学。先懂原理再学工具效率更高。另外Graph、状态机、消息队列这些基础工程知识对复杂 Agent 开发越来越重要。第三个是安全和稳定性。2026 年的 Agent 系统早就不只是“跑通就行”的阶段输入注入、输出越权、工具误调用、记忆污染都需要处理。这部分内容往往不会出现在入门教程里但恰恰是生产环境最看重的。我个人更建议先把单任务跑稳再考虑批量和接口。这个顺序看起来慢但踩坑最少。真正落地一个 Agent 项目时最该盯住的不是它有多智能而是输入格式、工具返回、日志和失败重试这些无聊但关键的工程细节。