先别急着刷完 748 集Agent 开发入门的正确姿势打开 B 站搜索“AI Agent”你大概率会看到各种“全套教程”“从入门到就业”“看完这一套就够了”的标题。这些视频动辄几百集收藏夹吃灰率极高。问题不在于内容质量而在于学习方式——Agent 开发不是靠“刷完”就能学会的它和传统 CRUD 开发、前端开发、嵌入式开发有一个本质区别你无法用“看完”来代替“做出来”。这篇文章想解决的事情很明确不劝你收藏任何一套 748 集的视频而是帮你建立一个 Agent 开发的核心框架让你知道 Agent 到底是什么、核心原理有哪些、入手应该选什么框架、怎么写第一个能跑通的 Agent以及遇到问题应该去哪里排查。文章不会很长但每一段都值得你停下来想一想。如果你是一个刚接触 AI 应用开发的后端工程师、前端工程师或者正在纠结要不要转 AI 方向的在校学生这篇文章适合你。1. 这篇关于 AI Agent 开发的文章真正要解决什么先给一个判断Agent 开发是最近两年 AI 应用层最值得投入的方向但它同时也是被误解最多的方向。很多人以为 Agent 开发就是“调 API”把 GPT-4 的接口接进来加几句 system prompt 就算完事。如果你真这么做做出来的东西顶多算一个“带提示词的聊天机器人”和真正的 Agent 差得很远。也有人以为 Agent 开发需要极强的算法背景得先读三年论文才能动手。这也是误解。Agent 开发更多考验的是工程能力、任务拆解能力、对工具链的理解而不是数学推导能力。你不需要从零训练模型你需要的是把现有的大模型能力组合起来解决一个具体业务问题。那么Agent 开发到底解决了什么真实痛点举一个非常常见的场景。假设你是公司里负责运维的工程师每天要处理日志告警。过去你要写一堆 Python 脚本手动登录服务器执行命令分析日志再决定要不要告警。现在你可以做一个简单的 Agent给大模型接上日志查询工具的 API让模型自己判断“这个错误是什么级别”“要不要继续查上游服务状态”“最后生成一条告警摘要”。这个 Agent 能替你完成 80% 的重复判断你只需要处理它筛出来的真正严重的问题。类似的场景还有客服工单自动分类、代码仓库的 PR Review 助手、企业内部知识库问答、SQL 查询生成与执行、爬虫数据清洗等等。这些场景的共同点是有明确的输入输出、有可调用的工具、有需要模型进行推理和判断的空间。这就是 Agent 适合发挥的地方。读完这篇文章你将获得三条关键信息Agent 区别于传统程序的核心能力是什么。Agent 开发的完整架构与常用框架选型。一条从零到第一个可运行 Agent 的最小实践路径。2. 基础概念Agent 不是聊天机器人而是“会用工具的程序”要理解 Agent 开发必须先理解几个概念。这节会尽量用大白话讲清楚。2.1 LLMAgent 的大脑LLMLarge Language Model大语言模型是 Agent 的“大脑”。它负责理解用户的意图、生成计划、做出决策。没有 LLM 的 Agent 只是传统自动化脚本有了 LLM 的 Agent 才能“自己拿主意”。但 LLM 有一个天然短板它只会“想”和“说”不会“做”。让 GPT-4 写一段代码它可以写得很好但你让它直接去执行这段代码、读取你本地的文件、调用你的数据库它就无能为力了。除非你给它接上工具。2.2 ToolAgent 的手和脚Tool工具是 Agent 能对外部世界产生影响的手段。一个工具可以是一个函数、一个 API 接口、一个数据库查询、一个命令行执行器。举个例子。如果你给 Agent 接了一个search_web(query)工具它就能回答超出它训练数据时效的问题。如果你给它接了一个execute_sql(sql)工具它就能查你公司的数据库。如果你给它接了一个send_email(to, subject, body)工具它就能代替你发邮件。工具是 Agent 与外部世界交互的唯一方式。这也是 Agent 开发与传统开发最大的不同你不是把逻辑写死在代码里而是把工具提供给模型让模型自己决定调用哪个、什么时候调用、怎么传参数。2.3 PlanningAgent 的思考方式Planning规划是 Agent 最像“智能体”的部分。当用户给一个复杂任务时Agent 不是直接调用工具而是先拆解任务。比如用户说“帮我分析这个月的销售数据找出下滑原因并写一份报告”Agent 会先规划第一步找到销售数据表。第二步写 SQL 查询月度销售趋势。第三步分析哪个产品线下滑最明显。第四步搜索可能的竞品动态如果有联网工具。第五步生成报告。这个能力来自模型本身但也可以用代码方式强约束。常见的规划方式有两种一种是让模型自由发挥ReAct 模式另一种是在代码中定义好流程图Plan-and-Execute 模式。后面会详细说。2.4 MemoryAgent 的短期记忆与长期记忆Memory记忆决定了 Agent 能不能记得“上下文”。有两种记忆需要区分Context Window上下文窗口模型一次能处理的最大 token 数。这是“短期记忆”。Vector Store向量数据库把历史信息存成向量需要时检索回来。这是“长期记忆”。没有记忆的 Agent 每次调用都是“失忆”的。有了记忆Agent 才能在多轮对话中保持一致性或者从历史经验中学习。2.5 什么是真正意义上的 Agent综合上面几个概念可以给 Agent 下一个严格的定义Agent LLM Planning Tool Memory这四者缺一不可。如果你的程序只用了 LLM 做文本生成没有调用工具也没做规划那它只是一个聊天机器人。如果你的程序用了 LLM 做意图识别但决策逻辑全写在代码里那它只是一个加了 NLP 模块的传统程序。只有当你让 LLM 在循环中决定“下一步做什么、调用什么工具”你才算在开发 Agent。这个概念非常重要因为很多人学了很久 Agent 开发做出来的东西却只是“LLM API 的壳子”。2.6 Agent 与 Workflow 的区别还有一个容易混淆的概念是 Workflow。Workflow工作流是把步骤写死在代码里比如“用户输入 - 调用模型 - 输出结果”每一步顺序固定。而 Agent 是在运行时动态决定下一步做什么。前者适合流程稳定、不需要太多智能判断的场景后者适合开放性强、步骤不确定的场景。实际项目中两者常常混用。主流框架推荐的模式是用 Workflow 控制主流程在需要模型决策的地方用 Agent。这种混合架构在稳定性与灵活性之间取得了平衡也是我建议初学者采用的方式。维度传统 WorkflowAgent流程控制代码写死顺序固定模型动态决策步骤不固定确定性高结果可预期中低结果受模型影响适用场景流程稳定、重复执行开放性强、需要推理判断开发难度低中高可调试性好每一步可复现一般需要日志追踪模型行为对于初学者我的建议是先别急着追求“纯 Agent”先用 Workflow 的方式跑通一个任务然后逐步把需要推理判断的节点替换成 Agent。3. Agent 开发环境准备与前置条件在写第一个 Agent 之前先把环境准备好。这里以一个常见的技术栈为例。3.1 环境清单Agent 开发并不需要多高端的机器。你本地的电脑足够跑通大部分开源 Agent 框架和调用云 API 的示例。以下是推荐的环境和工具组合项目推荐选择说明操作系统Windows 10/11、macOS、Linux均可建议在命令行环境下学习编程语言Python 3.10生态最完善Agent 框架几乎都支持 Python包管理pip / poetry / uv个人项目用 pip 即可团队项目推荐 poetry 或 uv大模型 APIOpenAI、Anthropic、国产模型 API 等没有 API 可以用本地 Ollama 替代向量数据库可选Chroma、FAISS、Milvus做记忆功能时使用开发工具VS Code Python 插件 / JetBrains PyCharm不必特别纠结选顺手的使用版本管理Git GitHub必须有保存练习项目这里要特别说明一下文章中的代码示例主要使用 Python 3.10 和 LangChain 风格代码。版本号以你实际安装时的最新稳定版为准不建议盲从旧教程使用已弃用的类名和方法。3.2 安装 Python 虚拟环境Python 项目依赖很容易出现版本冲突所以强烈建议在每个项目里建立虚拟环境。以创建agent-dev项目为例mkdir agent-dev cd agent-dev python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活虚拟环境后你的命令行提示符前面会出现(venv)表示当前处于虚拟环境内。后续安装的包都只会装在这个目录里不会污染系统 Python。3.3 安装核心依赖先安装最基础的依赖pip install --upgrade pip pip install langchain langchain-openai python-dotenv如果你计划使用本地模型做实验还需要安装 Ollama并下载一个小体积模型。示例命令如下# 安装 OllamamacOS / Linux curl -fsSL https://ollama.com/install.sh | sh # 拉取一个轻量模型 ollama pull qwen2.5:7b说明如果你的网络环境访问外网模型服务有困难可以优先使用国内可用的模型 API 或本地 Ollama。代理与网络配置相关问题本文不涉及请在自己合法的网络环境中进行实验。3.4 配置模型 API 密钥在项目根目录创建.env文件把 API 密钥放进去。注意这个文件不要提交到 Git。# .env OPENAI_API_KEYsk-your-key-here # 如果使用其他兼容 OpenAI 接口的模型服务可增加以下配置 OPENAI_BASE_URLhttps://your-endpoint.example.com/v1然后在代码中加载这个文件# config.py import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY)如果你的密钥前缀是其他平台的同样通过环境变量管理。保持密钥不写入代码的习惯是生产环境的基本要求。到这里环境就准备好了。接下来进入核心流程。4. Agent 开发核心流程拆解这一节会拆解开发一个完整 Agent 的通用流程。不管用的是 LangChain、LlamaIndex、AutoGen 还是自研框架底层的思考方式是一致的。4.1 定义任务目标与边界写代码之前先想清楚你的 Agent 到底要解决什么问题输入是什么输出是什么允许调用哪些工具不允许调用哪些工具以“日志智能分析 Agent”为例任务根据用户输入的日志片段或日志查询条件自动分析异常原因并输出排查建议 输入日志文本或查询条件 输出异常摘要、可能原因、排查建议 允许工具日志查询 API、代码解释器 不允许工具发送邮件、删除日志这个边界定义非常重要。没有边界模型可能会在运行时做出你不想让它做的事情。Agent 开发中常见的“Prompt Injection提示注入”风险很大程度上要通过边界约束来缓解。4.2 选择基础模型与调用方式选择模型的时候主要考虑几个因素推理能力复杂任务需要更强推理能力的模型。上下文窗口处理超长文本时窗口要大。工具调用支持尽量选择原生支持 Function Calling / Tool Calling 的模型开发效率会高很多。响应速度与成本生产环境要评估。目前主流模型基本都支持工具调用。如果你用的是国产模型 API建议查阅对应文档确认工具调用的开通方式。4.3 定义工具集工具定义是 Agent 开发中工作量最大的部分之一。每个工具都要写清楚工具名称模型调用时用的标识。描述告诉模型这个工具是干什么的、什么时候用。参数结构使用时需要传入哪些参数。执行逻辑实际调用的函数体。举例写一个“查询城市天气”的工具import json from typing import Type from langchain_core.tools import BaseTool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str Field(description城市名称比如北京、上海) class WeatherTool(BaseTool): name: str get_weather description: str 查询指定城市当前天气情况适用于用户问天气时 args_schema: Type[BaseModel] WeatherInput def _run(self, city: str) - str: # 这里应该调用真实天气 API示例直接返回模拟数据 weather_data {北京: 晴22-30℃, 上海: 多云25-31℃} result weather_data.get(city, 暂不支持该城市查询) return json.dumps({city: city, weather: result}, ensure_asciiFalse)工具描述写得好不好直接决定模型能不能在正确时机调用它。描述太笼统模型就会犹豫描述太具体模型反而会局限。这是一个需要反复调优的部分。4.4 设计记忆与上下文管理如果你的 Agent 是多轮对话型的必须考虑记忆问题。一种简单的做法是把对话历史直接塞进 prompt。但上下文窗口有限塞不了太多轮。更高级的做法是短期记忆保留最近 N 轮对话。长期记忆把重要的历史信息抽取嵌入到向量数据库。摘要记忆每几轮对话生成一次摘要替代原始记录。在第一个项目里建议先用短期记忆跑通之后再加向量数据库。4.5 实现主循环Agent 的核心是一个循环简单描述为接收用户输入。把输入、历史、工具描述一起交给模型。模型返回“回答”或“工具调用请求”。如果模型决定调用工具执行工具把结果返回给模型。模型基于工具结果继续生成回到第 2 步。直到模型给出最终答案循环结束。这个模式通常叫 ReActReason Act。本质上就是让模型一边推理一边行动直到完成任务。下面用一个最小实现来演示这个循环。5. 完整示例零依赖实现一个可运行的 Agent考虑到初学者可能对框架有认知负担这一节先不引入 LangChain 等重框架而是用 Python 直接调用 OpenAI 兼容的 API实现一个最简单的支持工具调用的 Agent。这样做能帮助你理解 Agent 的底层逻辑不会因为框架封装太深而变成“只会调包”。5.1 项目结构agent-minimal/ ├── .env ├── config.py ├── tools.py ├── agent.py └── requirements.txt5.2 安装依赖pip install openai python-dotenv5.3 定义工具创建一个简单的“伪计算器”工具和一个“获取当前时间”工具# tools.py import datetime import json def calculator(expression: str) - str: 执行简单的四则运算表达式。 try: result eval(expression, {__builtins__: {}}, {}) return json.dumps({result: result}, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) def get_current_time() - str: 返回当前系统时间。 now datetime.datetime.now() return json.dumps({time: now.strftime(%Y-%m-%d %H:%M:%S)}, ensure_asciiFalse) # 工具注册表名字 - (函数, 描述) TOOLS { calculator: { function: calculator, description: 执行四则运算的数学计算器输入为数学表达式字符串, }, get_current_time: { function: get_current_time, description: 获取当前系统日期和时间无输入参数, }, }这里特别注意eval有安全隐患仅用于本地演示。实际项目中工具的代码要经过严格的安全审查涉及执行动态代码的能力要非常谨慎。5.4 实现 Agent 主循环# agent.py import json import os from openai import OpenAI from dotenv import load_dotenv from tools import TOOLS load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) SYSTEM_PROMPT 你是智能助手。你可以使用以下工具来帮助用户 {} 当用户需要调用工具时必须输出一个 JSON 对象格式如下 {{tool: 工具名, args: {{参数名: 参数值}}}} 不要输出任何其他文字。 当没有合适的工具时直接回答用户。 .format(json.dumps(TOOLS, ensure_asciiFalse, defaultstr)) def run_agent(user_input: str, max_steps: int 5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messagesmessages, temperature0.2, ) content response.choices[0].message.content.strip() print(f[思考第 {step 1} 步], content) # 尝试解析 JSON判断是否需要调用工具 try: parsed json.loads(content) tool_name parsed.get(tool) tool_args parsed.get(args, {}) except json.JSONDecodeError: print( 最终回答, content) return content if tool_name not in TOOLS: print( 未知工具直接回答, content) return content # 调用工具 tool_func TOOLS[tool_name][function] try: tool_result tool_func(**tool_args) except Exception as e: tool_result json.dumps({error: str(e)}, ensure_asciiFalse) print(f[工具结果] {tool_name} - {tool_result}) # 把工具结果追加到对话中 messages.append({role: assistant, content: content}) messages.append({role: user, content: f工具执行结果{tool_result}。请根据结果继续回答或给出最终结论。}) print( 达到最大步数停止执行) return None if __name__ __main__: test_input 现在几点钟顺便帮我计算 (15 23) * 2 等于多少。 run_agent(test_input)5.5 运行与测试python agent.py预期输出类似[思考第 1 步] {tool: get_current_time, args: {}} [工具结果] get_current_time - {time: 2025-06-15 14:30:22} [思考第 2 步] {tool: calculator, args: {expression: (15 23) * 2}} [工具结果] calculator - {result: 76} [思考第 3 步] 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 23) * 2 结果是 76。 最终回答 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 23) * 2 结果是 76。这说明 Agent 成功实现了“推理 - 行动 - 观察结果 - 继续推理”的循环。这个最小示例有两个明显的缺点一是没有引入成熟的工具调用协议只是在 prompt 里要求模型输出 JSON二是很容易出现解析失败的情况。生产环境不建议这么写推荐用框架自带的 Function Calling 支持。6. 使用 LangChain 实现更规范的 Agent理解原理之后再看框架就轻松很多。LangChain 是目前 Agent 开发中使用最广泛的框架之一它把很多底层工作标准化了。6.1 安装 LangChain 相关依赖pip install langchain langchain-openai6.2 使用工具调用能力的 Agent 示例这里实现一个相同的功能但使用 LangChain 的create_tool_calling_agent方式这种方式与模型的 native tool calling 协议对接效果更稳定。# langchain_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate load_dotenv() # 1. 定义工具 tool def calculator(expression: str) - str: 适用于执行四则运算。输入一个数学表达式。 try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as e: return f计算错误: {e} tool def get_current_time() - str: 获取当前日期时间。 from datetime import datetime return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 2. 初始化模型 llm ChatOpenAI( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) # 3. 构建 Prompt prompt ChatPromptTemplate.from_messages([ (system, 你是可靠的助手使用工具帮助用户解决问题。), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 创建 Agent tools [calculator, get_current_time] agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 5. 运行 if __name__ __main__: response agent_executor.invoke({input: 现在几点了帮我算 (15 23) * 2}) print(最终输出, response)运行方式python langchain_agent.pyverboseTrue会在控制台打印出 Agent 的每一步推理和工具调用过程这是学习 Agent 开发最重要的调试手段之一。你会看到模型“思考”了哪些步骤、调用哪个工具、工具返回了什么、最终如何给出答案。6.3 关键配置项的解释LangChain 的 AgentExecutor 有几个参数值得注意max_iterations限制最大迭代步数防止模型陷入无限循环建议设置为 3 到 10。early_stopping_method达到最大步数时的处理方式默认是force生成一个回答。handle_parsing_errors解析错误时如何处理建议开启。return_intermediate_steps是否在结果中返回中间步骤便于追踪。生产环境建议开启配合日志系统。一个更安全的配置示例agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, )7. 主流 Agent 开发框架选型与对比LangChain 并不是唯一选择。不同的项目规模、团队技术栈和业务场景适合不同的框架。这里做一个客观对比。框架核心特点适用场景学习曲线LangChain组件丰富工具生态最完善支持多种 Agent 模式企业级应用复杂工作流中等LangGraph基于图结构的 Agent 编排支持循环、分支、状态管理需要精确控制流程的复杂 Agent较高LlamaIndex擅长 RAG检索增强生成数据连接器丰富知识库问答、文档分析中等AutoGen多 Agent 对话协作框架微软出品多 Agent 模拟、群聊协作中等Coze扣子低代码平台可视化编排快速原型非技术背景也能做低Dify开源 LLM 应用平台自带 RAG 与 Agent 能力团队快速搭建 AI 应用低至中自研完全可控但工作量大对稳定性、安全性要求极高的场景高一个常见误区是初学者一上来就选“最强大”的框架。实际上如果任务场景并不复杂用 Coze 甚至简单的 API 调用就能解决不必引入 LangChain 的重型编排能力。框架选型应该遵循“从简到繁”的原则。针对不同技术背景的开发者我给出如下建议后端 Java/C 背景优先考虑 LangChain4j 或者直接用 Python LangChain原因是你主力语言可能不是 PythonPython 生态更适合 AI 开发可以先用 Python 做原型后续再用 Java 重构。前端角色如果不懂后端可以考虑先学 Coze/Dify用低代码方式感受 Agent 逻辑再逐步学习 Python。算法背景直接上 LlamaIndex LangGraph配合自己的模型能力做效果调优。8. Agent 开发进阶方向RAG、多 Agent 与 Agent Skills8.1 RAG检索增强生成RAG 是 Agent 开发中绕不开的方向。它的核心思想是用户提问时不是直接让模型生成而是先从知识库中检索相关文档片段再把文档片段作为上下文交给模型生成答案。这样做的好处是回答基于事实资料减少幻觉。可以接入企业私有知识库。数据更新不需要重新训练模型。RAG 的基本链路是文档加载 - 文本切分 - 向量化 - 向量存储 - 检索 - LLM 生成。在实现 Agent 时RAG 往往作为一个“知识检索工具”接入 Agent 中。8.2 多 Agent 协作当单一 Agent 难以处理复杂任务时可以考虑多 Agent 架构。有几种常见模式主管-工人模式一个“主管 Agent”负责拆解任务分派给多个“工人 Agent”执行。辩论模式多个 Agent 对同一问题提出不同观点最终汇总结论。流水线模式一个 Agent 的输出是另一个 Agent 的输入。多 Agent 的好处是每个 Agent 可以专注在自己的领域降低单个 prompt 的复杂度。但代价是 token 消耗增加、调试难度上升。新手不建议一上来就做多 Agent先保证单个 Agent 稳定可靠再说。8.3 Agent Skills 与工具扩展“Skills”这个词在最近的 Agent 生态里很流行它本质上是一组可供 Agent 复用的技能包可以包含工具函数、prompt 模板、调用规范。比如“SQL 查询技能”可以包含如何连接数据库、如何校验 SQL 安全性、如何格式化查询结果等多个能力。可以简单理解一个 Skill 是“工具 使用说明 约束条件”的打包。它让 Agent 在面对某类任务时不只是一个孤立的函数而是有一套完整的方法论。实际开发中建议把工具按场景归类每个场景维护一个 Skill 包。这不仅能提高复用性也方便做版本管理和测试。9. 常见问题与排查思路Agent 开发与传统开发在调试上有很大不同。模型的不确定性导致代码“看起来没报错但结果不对”的情况非常常见。以下按出现频率排序最典型的几个问题。问题现象可能原因排查方式解决方案Agent 反复调用同一个工具循环不结束工具返回结果不够明确模型无法推断下一步开启 verbose 日志观察每一步的模型输出优化工具返回信息补充结构化反馈设置 max_iterations 上限模型从不调用工具工具描述不清晰或模型不支持工具调用检查模型 API 文档是否支持 tool calling重写工具描述加入“什么时候用这个工具”的说明工具参数传错参数描述不清晰或模型被 prompt 干扰检查参数 schema 中的 description为每个参数写清楚格式、范围、示例值输出经常解析失败用了非标准的 JSON 输出格式查看原始输出日志改用框架自带的 Function Calling而不是让模型输出 JSON回答出现编造内容Agent 在无工具可用时强行作答检查工具列表是否完备给 Agent 加“不知道就承认”的约束或增加搜索/检索工具上下文太长报 token 超限未做历史消息压缩统计 token 使用量实现历史消息裁剪、摘要记忆Agent 执行了不该执行的操作工具权限边界设置不严检查工具注册表不要在工具列表中暴露不安全操作生产环境做工具级鉴权本地环境跑 LangChain 报依赖冲突版本不兼容查看完整报错堆栈升级框架或锁定版本优先使用 Python 3.10调试 Agent 有一个核心原则先看日志再猜原因。模型输出永远是排查的第一现场。很多“诡异问题”其实只要打开verboseTrue看一遍中间过程就立刻明白了。10. 最佳实践与工程建议从“能跑通 Demo”到“能上线生产”Agent 开发还有一段距离。下面这些规范是我认为值得提前养成的习惯。10.1 安全边界永远假设模型不可信Agent 的决策来自模型输出而模型输出是不可完全预测的。这要求开发者必须在代码层面设置安全边界工具注册表白名单化禁止模型动态创建工具。涉及系统命令、文件删除、支付、发邮件等高危操作一律走人工审批流。对模型的工具调用参数做校验和过滤。不要轻易把外部输入直接拼接到 prompt 中防止提示注入。10.2 成本控制每一次工具调用都是钱Agent 是多轮循环每轮都要调用一次模型这意味着一个复杂任务可能要消耗大量 token。控制成本的手段包括设置max_iterations上限。缓存中间结果对相同输入直接返回。使用更小、更便宜的模型处理简单任务。为不同工具编写更精炼的描述减少模型“犹豫”带来的多余调用。10.3 可观测性日志是 Agent 的唯一真相生产环境的 Agent 必须记录完整调用链路。建议至少记录以下信息用户原始输入。系统 prompt 版本。每轮模型输出思考过程。工具调用名称、参数、返回结果、耗时。最终回答。总 token 消耗。有了这些日志才能对 Agent 的效果进行评估、归因和持续优化。10.4 评估体系用什么指标判断 Agent 好坏一个 Agent 上线之前必须建立评测集。最简单的做法是准备 20 到 50 个典型问题人工标注期望输出每次改动 prompt 或模型后都跑一遍评测集对比结果。可参考的指标包括任务成功率最终结果是否满足用户需求。工具调用准确率是否在正确场景调用了正确工具。无回复率模型是否频繁承认自己不会。平均轮数完成一个任务需要多少次模型调用轮数越少成本越低。幻觉率生成内容是否有事实错误需要人工抽查。10.5 版本管理Prompt 变更也要走 Git把系统 prompt 当作代码的一部分写入 Git 仓库。每次修改都记录变更原因。在实际项目中prompt 的迭代频率远高于业务代码如果没有任何版本管理很容易出现“昨天还能用今天突然不行了”但找不到原因的情况。更严谨的团队会把 prompt 存放在配置中心线上动态调整避免改 prompt 需要重新发布服务。10.6 个人开发者学习路线建议如果你是初学者按下面的路径走投入产出比最高用 Coze 或 Dify 画一个可视化 Agent感受“模型 工具”的组合。用 Python OpenAI SDK 写一个不支持工具调用的极简 Agent比如 5.3 节的版本。用 LangChain 做一个支持工具调用的 Agent理解AgentExecutor的结构。给 Agent 加上 RAG 能力做一个“私有知识库问答机器人”。尝试把 Agent 的日志、记忆、评估体系完善起来。用 FastAPI 把 Agent 封装成 HTTP 服务供前端或其他系统调用。走到第 5 步时你已经超过 90% 的“收藏党”了。不需要看过任何一套 748 集的视频。11. 总结与下一步建议这篇文章讨论的核心其实是两件事第一Agent 开发的本质是让 LLM 在循环中调用工具解决开放性问题它不是简单的 API 调用第二Agent 入门的正确路径是先理解原理再动手做最小实现然后引入成熟框架最后考虑工程化。如果你现在刚看完这篇文章下一步可以从一个非常小的场景开始比如做一个“桌面便签助手”让 Agent 能创建、查询、删除本地文件中的笔记。这个项目用不了多少行代码但能让你完整经历工具定义、记忆管理、多轮对话、排错的全过程。真正值得投入精力的方向是RAG 在垂直领域的落地、多 Agent 协作的生产级可靠性、Agent 的可观测性与评测体系。这几个方向在未来两三年里都会有持续的需求。对于那些收藏了“全套教程”的朋友我的建议是不要试图看完直接找到第 20 集左右的“第一个实战项目”跟着做一遍卡住了再回看。用项目倒逼学习比线性刷视频有效得多。动手做一个能跑的 Agent胜过收藏十套教程。 AI Agent开发入门：别刷748集教程，先掌握核心框架
先别急着刷完 748 集Agent 开发入门的正确姿势打开 B 站搜索“AI Agent”你大概率会看到各种“全套教程”“从入门到就业”“看完这一套就够了”的标题。这些视频动辄几百集收藏夹吃灰率极高。问题不在于内容质量而在于学习方式——Agent 开发不是靠“刷完”就能学会的它和传统 CRUD 开发、前端开发、嵌入式开发有一个本质区别你无法用“看完”来代替“做出来”。这篇文章想解决的事情很明确不劝你收藏任何一套 748 集的视频而是帮你建立一个 Agent 开发的核心框架让你知道 Agent 到底是什么、核心原理有哪些、入手应该选什么框架、怎么写第一个能跑通的 Agent以及遇到问题应该去哪里排查。文章不会很长但每一段都值得你停下来想一想。如果你是一个刚接触 AI 应用开发的后端工程师、前端工程师或者正在纠结要不要转 AI 方向的在校学生这篇文章适合你。1. 这篇关于 AI Agent 开发的文章真正要解决什么先给一个判断Agent 开发是最近两年 AI 应用层最值得投入的方向但它同时也是被误解最多的方向。很多人以为 Agent 开发就是“调 API”把 GPT-4 的接口接进来加几句 system prompt 就算完事。如果你真这么做做出来的东西顶多算一个“带提示词的聊天机器人”和真正的 Agent 差得很远。也有人以为 Agent 开发需要极强的算法背景得先读三年论文才能动手。这也是误解。Agent 开发更多考验的是工程能力、任务拆解能力、对工具链的理解而不是数学推导能力。你不需要从零训练模型你需要的是把现有的大模型能力组合起来解决一个具体业务问题。那么Agent 开发到底解决了什么真实痛点举一个非常常见的场景。假设你是公司里负责运维的工程师每天要处理日志告警。过去你要写一堆 Python 脚本手动登录服务器执行命令分析日志再决定要不要告警。现在你可以做一个简单的 Agent给大模型接上日志查询工具的 API让模型自己判断“这个错误是什么级别”“要不要继续查上游服务状态”“最后生成一条告警摘要”。这个 Agent 能替你完成 80% 的重复判断你只需要处理它筛出来的真正严重的问题。类似的场景还有客服工单自动分类、代码仓库的 PR Review 助手、企业内部知识库问答、SQL 查询生成与执行、爬虫数据清洗等等。这些场景的共同点是有明确的输入输出、有可调用的工具、有需要模型进行推理和判断的空间。这就是 Agent 适合发挥的地方。读完这篇文章你将获得三条关键信息Agent 区别于传统程序的核心能力是什么。Agent 开发的完整架构与常用框架选型。一条从零到第一个可运行 Agent 的最小实践路径。2. 基础概念Agent 不是聊天机器人而是“会用工具的程序”要理解 Agent 开发必须先理解几个概念。这节会尽量用大白话讲清楚。2.1 LLMAgent 的大脑LLMLarge Language Model大语言模型是 Agent 的“大脑”。它负责理解用户的意图、生成计划、做出决策。没有 LLM 的 Agent 只是传统自动化脚本有了 LLM 的 Agent 才能“自己拿主意”。但 LLM 有一个天然短板它只会“想”和“说”不会“做”。让 GPT-4 写一段代码它可以写得很好但你让它直接去执行这段代码、读取你本地的文件、调用你的数据库它就无能为力了。除非你给它接上工具。2.2 ToolAgent 的手和脚Tool工具是 Agent 能对外部世界产生影响的手段。一个工具可以是一个函数、一个 API 接口、一个数据库查询、一个命令行执行器。举个例子。如果你给 Agent 接了一个search_web(query)工具它就能回答超出它训练数据时效的问题。如果你给它接了一个execute_sql(sql)工具它就能查你公司的数据库。如果你给它接了一个send_email(to, subject, body)工具它就能代替你发邮件。工具是 Agent 与外部世界交互的唯一方式。这也是 Agent 开发与传统开发最大的不同你不是把逻辑写死在代码里而是把工具提供给模型让模型自己决定调用哪个、什么时候调用、怎么传参数。2.3 PlanningAgent 的思考方式Planning规划是 Agent 最像“智能体”的部分。当用户给一个复杂任务时Agent 不是直接调用工具而是先拆解任务。比如用户说“帮我分析这个月的销售数据找出下滑原因并写一份报告”Agent 会先规划第一步找到销售数据表。第二步写 SQL 查询月度销售趋势。第三步分析哪个产品线下滑最明显。第四步搜索可能的竞品动态如果有联网工具。第五步生成报告。这个能力来自模型本身但也可以用代码方式强约束。常见的规划方式有两种一种是让模型自由发挥ReAct 模式另一种是在代码中定义好流程图Plan-and-Execute 模式。后面会详细说。2.4 MemoryAgent 的短期记忆与长期记忆Memory记忆决定了 Agent 能不能记得“上下文”。有两种记忆需要区分Context Window上下文窗口模型一次能处理的最大 token 数。这是“短期记忆”。Vector Store向量数据库把历史信息存成向量需要时检索回来。这是“长期记忆”。没有记忆的 Agent 每次调用都是“失忆”的。有了记忆Agent 才能在多轮对话中保持一致性或者从历史经验中学习。2.5 什么是真正意义上的 Agent综合上面几个概念可以给 Agent 下一个严格的定义Agent LLM Planning Tool Memory这四者缺一不可。如果你的程序只用了 LLM 做文本生成没有调用工具也没做规划那它只是一个聊天机器人。如果你的程序用了 LLM 做意图识别但决策逻辑全写在代码里那它只是一个加了 NLP 模块的传统程序。只有当你让 LLM 在循环中决定“下一步做什么、调用什么工具”你才算在开发 Agent。这个概念非常重要因为很多人学了很久 Agent 开发做出来的东西却只是“LLM API 的壳子”。2.6 Agent 与 Workflow 的区别还有一个容易混淆的概念是 Workflow。Workflow工作流是把步骤写死在代码里比如“用户输入 - 调用模型 - 输出结果”每一步顺序固定。而 Agent 是在运行时动态决定下一步做什么。前者适合流程稳定、不需要太多智能判断的场景后者适合开放性强、步骤不确定的场景。实际项目中两者常常混用。主流框架推荐的模式是用 Workflow 控制主流程在需要模型决策的地方用 Agent。这种混合架构在稳定性与灵活性之间取得了平衡也是我建议初学者采用的方式。维度传统 WorkflowAgent流程控制代码写死顺序固定模型动态决策步骤不固定确定性高结果可预期中低结果受模型影响适用场景流程稳定、重复执行开放性强、需要推理判断开发难度低中高可调试性好每一步可复现一般需要日志追踪模型行为对于初学者我的建议是先别急着追求“纯 Agent”先用 Workflow 的方式跑通一个任务然后逐步把需要推理判断的节点替换成 Agent。3. Agent 开发环境准备与前置条件在写第一个 Agent 之前先把环境准备好。这里以一个常见的技术栈为例。3.1 环境清单Agent 开发并不需要多高端的机器。你本地的电脑足够跑通大部分开源 Agent 框架和调用云 API 的示例。以下是推荐的环境和工具组合项目推荐选择说明操作系统Windows 10/11、macOS、Linux均可建议在命令行环境下学习编程语言Python 3.10生态最完善Agent 框架几乎都支持 Python包管理pip / poetry / uv个人项目用 pip 即可团队项目推荐 poetry 或 uv大模型 APIOpenAI、Anthropic、国产模型 API 等没有 API 可以用本地 Ollama 替代向量数据库可选Chroma、FAISS、Milvus做记忆功能时使用开发工具VS Code Python 插件 / JetBrains PyCharm不必特别纠结选顺手的使用版本管理Git GitHub必须有保存练习项目这里要特别说明一下文章中的代码示例主要使用 Python 3.10 和 LangChain 风格代码。版本号以你实际安装时的最新稳定版为准不建议盲从旧教程使用已弃用的类名和方法。3.2 安装 Python 虚拟环境Python 项目依赖很容易出现版本冲突所以强烈建议在每个项目里建立虚拟环境。以创建agent-dev项目为例mkdir agent-dev cd agent-dev python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活虚拟环境后你的命令行提示符前面会出现(venv)表示当前处于虚拟环境内。后续安装的包都只会装在这个目录里不会污染系统 Python。3.3 安装核心依赖先安装最基础的依赖pip install --upgrade pip pip install langchain langchain-openai python-dotenv如果你计划使用本地模型做实验还需要安装 Ollama并下载一个小体积模型。示例命令如下# 安装 OllamamacOS / Linux curl -fsSL https://ollama.com/install.sh | sh # 拉取一个轻量模型 ollama pull qwen2.5:7b说明如果你的网络环境访问外网模型服务有困难可以优先使用国内可用的模型 API 或本地 Ollama。代理与网络配置相关问题本文不涉及请在自己合法的网络环境中进行实验。3.4 配置模型 API 密钥在项目根目录创建.env文件把 API 密钥放进去。注意这个文件不要提交到 Git。# .env OPENAI_API_KEYsk-your-key-here # 如果使用其他兼容 OpenAI 接口的模型服务可增加以下配置 OPENAI_BASE_URLhttps://your-endpoint.example.com/v1然后在代码中加载这个文件# config.py import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY)如果你的密钥前缀是其他平台的同样通过环境变量管理。保持密钥不写入代码的习惯是生产环境的基本要求。到这里环境就准备好了。接下来进入核心流程。4. Agent 开发核心流程拆解这一节会拆解开发一个完整 Agent 的通用流程。不管用的是 LangChain、LlamaIndex、AutoGen 还是自研框架底层的思考方式是一致的。4.1 定义任务目标与边界写代码之前先想清楚你的 Agent 到底要解决什么问题输入是什么输出是什么允许调用哪些工具不允许调用哪些工具以“日志智能分析 Agent”为例任务根据用户输入的日志片段或日志查询条件自动分析异常原因并输出排查建议 输入日志文本或查询条件 输出异常摘要、可能原因、排查建议 允许工具日志查询 API、代码解释器 不允许工具发送邮件、删除日志这个边界定义非常重要。没有边界模型可能会在运行时做出你不想让它做的事情。Agent 开发中常见的“Prompt Injection提示注入”风险很大程度上要通过边界约束来缓解。4.2 选择基础模型与调用方式选择模型的时候主要考虑几个因素推理能力复杂任务需要更强推理能力的模型。上下文窗口处理超长文本时窗口要大。工具调用支持尽量选择原生支持 Function Calling / Tool Calling 的模型开发效率会高很多。响应速度与成本生产环境要评估。目前主流模型基本都支持工具调用。如果你用的是国产模型 API建议查阅对应文档确认工具调用的开通方式。4.3 定义工具集工具定义是 Agent 开发中工作量最大的部分之一。每个工具都要写清楚工具名称模型调用时用的标识。描述告诉模型这个工具是干什么的、什么时候用。参数结构使用时需要传入哪些参数。执行逻辑实际调用的函数体。举例写一个“查询城市天气”的工具import json from typing import Type from langchain_core.tools import BaseTool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str Field(description城市名称比如北京、上海) class WeatherTool(BaseTool): name: str get_weather description: str 查询指定城市当前天气情况适用于用户问天气时 args_schema: Type[BaseModel] WeatherInput def _run(self, city: str) - str: # 这里应该调用真实天气 API示例直接返回模拟数据 weather_data {北京: 晴22-30℃, 上海: 多云25-31℃} result weather_data.get(city, 暂不支持该城市查询) return json.dumps({city: city, weather: result}, ensure_asciiFalse)工具描述写得好不好直接决定模型能不能在正确时机调用它。描述太笼统模型就会犹豫描述太具体模型反而会局限。这是一个需要反复调优的部分。4.4 设计记忆与上下文管理如果你的 Agent 是多轮对话型的必须考虑记忆问题。一种简单的做法是把对话历史直接塞进 prompt。但上下文窗口有限塞不了太多轮。更高级的做法是短期记忆保留最近 N 轮对话。长期记忆把重要的历史信息抽取嵌入到向量数据库。摘要记忆每几轮对话生成一次摘要替代原始记录。在第一个项目里建议先用短期记忆跑通之后再加向量数据库。4.5 实现主循环Agent 的核心是一个循环简单描述为接收用户输入。把输入、历史、工具描述一起交给模型。模型返回“回答”或“工具调用请求”。如果模型决定调用工具执行工具把结果返回给模型。模型基于工具结果继续生成回到第 2 步。直到模型给出最终答案循环结束。这个模式通常叫 ReActReason Act。本质上就是让模型一边推理一边行动直到完成任务。下面用一个最小实现来演示这个循环。5. 完整示例零依赖实现一个可运行的 Agent考虑到初学者可能对框架有认知负担这一节先不引入 LangChain 等重框架而是用 Python 直接调用 OpenAI 兼容的 API实现一个最简单的支持工具调用的 Agent。这样做能帮助你理解 Agent 的底层逻辑不会因为框架封装太深而变成“只会调包”。5.1 项目结构agent-minimal/ ├── .env ├── config.py ├── tools.py ├── agent.py └── requirements.txt5.2 安装依赖pip install openai python-dotenv5.3 定义工具创建一个简单的“伪计算器”工具和一个“获取当前时间”工具# tools.py import datetime import json def calculator(expression: str) - str: 执行简单的四则运算表达式。 try: result eval(expression, {__builtins__: {}}, {}) return json.dumps({result: result}, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) def get_current_time() - str: 返回当前系统时间。 now datetime.datetime.now() return json.dumps({time: now.strftime(%Y-%m-%d %H:%M:%S)}, ensure_asciiFalse) # 工具注册表名字 - (函数, 描述) TOOLS { calculator: { function: calculator, description: 执行四则运算的数学计算器输入为数学表达式字符串, }, get_current_time: { function: get_current_time, description: 获取当前系统日期和时间无输入参数, }, }这里特别注意eval有安全隐患仅用于本地演示。实际项目中工具的代码要经过严格的安全审查涉及执行动态代码的能力要非常谨慎。5.4 实现 Agent 主循环# agent.py import json import os from openai import OpenAI from dotenv import load_dotenv from tools import TOOLS load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) SYSTEM_PROMPT 你是智能助手。你可以使用以下工具来帮助用户 {} 当用户需要调用工具时必须输出一个 JSON 对象格式如下 {{tool: 工具名, args: {{参数名: 参数值}}}} 不要输出任何其他文字。 当没有合适的工具时直接回答用户。 .format(json.dumps(TOOLS, ensure_asciiFalse, defaultstr)) def run_agent(user_input: str, max_steps: int 5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response client.chat.completions.create( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), messagesmessages, temperature0.2, ) content response.choices[0].message.content.strip() print(f[思考第 {step 1} 步], content) # 尝试解析 JSON判断是否需要调用工具 try: parsed json.loads(content) tool_name parsed.get(tool) tool_args parsed.get(args, {}) except json.JSONDecodeError: print( 最终回答, content) return content if tool_name not in TOOLS: print( 未知工具直接回答, content) return content # 调用工具 tool_func TOOLS[tool_name][function] try: tool_result tool_func(**tool_args) except Exception as e: tool_result json.dumps({error: str(e)}, ensure_asciiFalse) print(f[工具结果] {tool_name} - {tool_result}) # 把工具结果追加到对话中 messages.append({role: assistant, content: content}) messages.append({role: user, content: f工具执行结果{tool_result}。请根据结果继续回答或给出最终结论。}) print( 达到最大步数停止执行) return None if __name__ __main__: test_input 现在几点钟顺便帮我计算 (15 23) * 2 等于多少。 run_agent(test_input)5.5 运行与测试python agent.py预期输出类似[思考第 1 步] {tool: get_current_time, args: {}} [工具结果] get_current_time - {time: 2025-06-15 14:30:22} [思考第 2 步] {tool: calculator, args: {expression: (15 23) * 2}} [工具结果] calculator - {result: 76} [思考第 3 步] 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 23) * 2 结果是 76。 最终回答 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 23) * 2 结果是 76。这说明 Agent 成功实现了“推理 - 行动 - 观察结果 - 继续推理”的循环。这个最小示例有两个明显的缺点一是没有引入成熟的工具调用协议只是在 prompt 里要求模型输出 JSON二是很容易出现解析失败的情况。生产环境不建议这么写推荐用框架自带的 Function Calling 支持。6. 使用 LangChain 实现更规范的 Agent理解原理之后再看框架就轻松很多。LangChain 是目前 Agent 开发中使用最广泛的框架之一它把很多底层工作标准化了。6.1 安装 LangChain 相关依赖pip install langchain langchain-openai6.2 使用工具调用能力的 Agent 示例这里实现一个相同的功能但使用 LangChain 的create_tool_calling_agent方式这种方式与模型的 native tool calling 协议对接效果更稳定。# langchain_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate load_dotenv() # 1. 定义工具 tool def calculator(expression: str) - str: 适用于执行四则运算。输入一个数学表达式。 try: result eval(expression, {__builtins__: {}}, {}) return str(result) except Exception as e: return f计算错误: {e} tool def get_current_time() - str: 获取当前日期时间。 from datetime import datetime return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 2. 初始化模型 llm ChatOpenAI( modelos.getenv(OPENAI_MODEL, gpt-4o-mini), api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) # 3. 构建 Prompt prompt ChatPromptTemplate.from_messages([ (system, 你是可靠的助手使用工具帮助用户解决问题。), (human, {input}), (placeholder, {agent_scratchpad}), ]) # 4. 创建 Agent tools [calculator, get_current_time] agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 5. 运行 if __name__ __main__: response agent_executor.invoke({input: 现在几点了帮我算 (15 23) * 2}) print(最终输出, response)运行方式python langchain_agent.pyverboseTrue会在控制台打印出 Agent 的每一步推理和工具调用过程这是学习 Agent 开发最重要的调试手段之一。你会看到模型“思考”了哪些步骤、调用哪个工具、工具返回了什么、最终如何给出答案。6.3 关键配置项的解释LangChain 的 AgentExecutor 有几个参数值得注意max_iterations限制最大迭代步数防止模型陷入无限循环建议设置为 3 到 10。early_stopping_method达到最大步数时的处理方式默认是force生成一个回答。handle_parsing_errors解析错误时如何处理建议开启。return_intermediate_steps是否在结果中返回中间步骤便于追踪。生产环境建议开启配合日志系统。一个更安全的配置示例agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, return_intermediate_stepsTrue, )7. 主流 Agent 开发框架选型与对比LangChain 并不是唯一选择。不同的项目规模、团队技术栈和业务场景适合不同的框架。这里做一个客观对比。框架核心特点适用场景学习曲线LangChain组件丰富工具生态最完善支持多种 Agent 模式企业级应用复杂工作流中等LangGraph基于图结构的 Agent 编排支持循环、分支、状态管理需要精确控制流程的复杂 Agent较高LlamaIndex擅长 RAG检索增强生成数据连接器丰富知识库问答、文档分析中等AutoGen多 Agent 对话协作框架微软出品多 Agent 模拟、群聊协作中等Coze扣子低代码平台可视化编排快速原型非技术背景也能做低Dify开源 LLM 应用平台自带 RAG 与 Agent 能力团队快速搭建 AI 应用低至中自研完全可控但工作量大对稳定性、安全性要求极高的场景高一个常见误区是初学者一上来就选“最强大”的框架。实际上如果任务场景并不复杂用 Coze 甚至简单的 API 调用就能解决不必引入 LangChain 的重型编排能力。框架选型应该遵循“从简到繁”的原则。针对不同技术背景的开发者我给出如下建议后端 Java/C 背景优先考虑 LangChain4j 或者直接用 Python LangChain原因是你主力语言可能不是 PythonPython 生态更适合 AI 开发可以先用 Python 做原型后续再用 Java 重构。前端角色如果不懂后端可以考虑先学 Coze/Dify用低代码方式感受 Agent 逻辑再逐步学习 Python。算法背景直接上 LlamaIndex LangGraph配合自己的模型能力做效果调优。8. Agent 开发进阶方向RAG、多 Agent 与 Agent Skills8.1 RAG检索增强生成RAG 是 Agent 开发中绕不开的方向。它的核心思想是用户提问时不是直接让模型生成而是先从知识库中检索相关文档片段再把文档片段作为上下文交给模型生成答案。这样做的好处是回答基于事实资料减少幻觉。可以接入企业私有知识库。数据更新不需要重新训练模型。RAG 的基本链路是文档加载 - 文本切分 - 向量化 - 向量存储 - 检索 - LLM 生成。在实现 Agent 时RAG 往往作为一个“知识检索工具”接入 Agent 中。8.2 多 Agent 协作当单一 Agent 难以处理复杂任务时可以考虑多 Agent 架构。有几种常见模式主管-工人模式一个“主管 Agent”负责拆解任务分派给多个“工人 Agent”执行。辩论模式多个 Agent 对同一问题提出不同观点最终汇总结论。流水线模式一个 Agent 的输出是另一个 Agent 的输入。多 Agent 的好处是每个 Agent 可以专注在自己的领域降低单个 prompt 的复杂度。但代价是 token 消耗增加、调试难度上升。新手不建议一上来就做多 Agent先保证单个 Agent 稳定可靠再说。8.3 Agent Skills 与工具扩展“Skills”这个词在最近的 Agent 生态里很流行它本质上是一组可供 Agent 复用的技能包可以包含工具函数、prompt 模板、调用规范。比如“SQL 查询技能”可以包含如何连接数据库、如何校验 SQL 安全性、如何格式化查询结果等多个能力。可以简单理解一个 Skill 是“工具 使用说明 约束条件”的打包。它让 Agent 在面对某类任务时不只是一个孤立的函数而是有一套完整的方法论。实际开发中建议把工具按场景归类每个场景维护一个 Skill 包。这不仅能提高复用性也方便做版本管理和测试。9. 常见问题与排查思路Agent 开发与传统开发在调试上有很大不同。模型的不确定性导致代码“看起来没报错但结果不对”的情况非常常见。以下按出现频率排序最典型的几个问题。问题现象可能原因排查方式解决方案Agent 反复调用同一个工具循环不结束工具返回结果不够明确模型无法推断下一步开启 verbose 日志观察每一步的模型输出优化工具返回信息补充结构化反馈设置 max_iterations 上限模型从不调用工具工具描述不清晰或模型不支持工具调用检查模型 API 文档是否支持 tool calling重写工具描述加入“什么时候用这个工具”的说明工具参数传错参数描述不清晰或模型被 prompt 干扰检查参数 schema 中的 description为每个参数写清楚格式、范围、示例值输出经常解析失败用了非标准的 JSON 输出格式查看原始输出日志改用框架自带的 Function Calling而不是让模型输出 JSON回答出现编造内容Agent 在无工具可用时强行作答检查工具列表是否完备给 Agent 加“不知道就承认”的约束或增加搜索/检索工具上下文太长报 token 超限未做历史消息压缩统计 token 使用量实现历史消息裁剪、摘要记忆Agent 执行了不该执行的操作工具权限边界设置不严检查工具注册表不要在工具列表中暴露不安全操作生产环境做工具级鉴权本地环境跑 LangChain 报依赖冲突版本不兼容查看完整报错堆栈升级框架或锁定版本优先使用 Python 3.10调试 Agent 有一个核心原则先看日志再猜原因。模型输出永远是排查的第一现场。很多“诡异问题”其实只要打开verboseTrue看一遍中间过程就立刻明白了。10. 最佳实践与工程建议从“能跑通 Demo”到“能上线生产”Agent 开发还有一段距离。下面这些规范是我认为值得提前养成的习惯。10.1 安全边界永远假设模型不可信Agent 的决策来自模型输出而模型输出是不可完全预测的。这要求开发者必须在代码层面设置安全边界工具注册表白名单化禁止模型动态创建工具。涉及系统命令、文件删除、支付、发邮件等高危操作一律走人工审批流。对模型的工具调用参数做校验和过滤。不要轻易把外部输入直接拼接到 prompt 中防止提示注入。10.2 成本控制每一次工具调用都是钱Agent 是多轮循环每轮都要调用一次模型这意味着一个复杂任务可能要消耗大量 token。控制成本的手段包括设置max_iterations上限。缓存中间结果对相同输入直接返回。使用更小、更便宜的模型处理简单任务。为不同工具编写更精炼的描述减少模型“犹豫”带来的多余调用。10.3 可观测性日志是 Agent 的唯一真相生产环境的 Agent 必须记录完整调用链路。建议至少记录以下信息用户原始输入。系统 prompt 版本。每轮模型输出思考过程。工具调用名称、参数、返回结果、耗时。最终回答。总 token 消耗。有了这些日志才能对 Agent 的效果进行评估、归因和持续优化。10.4 评估体系用什么指标判断 Agent 好坏一个 Agent 上线之前必须建立评测集。最简单的做法是准备 20 到 50 个典型问题人工标注期望输出每次改动 prompt 或模型后都跑一遍评测集对比结果。可参考的指标包括任务成功率最终结果是否满足用户需求。工具调用准确率是否在正确场景调用了正确工具。无回复率模型是否频繁承认自己不会。平均轮数完成一个任务需要多少次模型调用轮数越少成本越低。幻觉率生成内容是否有事实错误需要人工抽查。10.5 版本管理Prompt 变更也要走 Git把系统 prompt 当作代码的一部分写入 Git 仓库。每次修改都记录变更原因。在实际项目中prompt 的迭代频率远高于业务代码如果没有任何版本管理很容易出现“昨天还能用今天突然不行了”但找不到原因的情况。更严谨的团队会把 prompt 存放在配置中心线上动态调整避免改 prompt 需要重新发布服务。10.6 个人开发者学习路线建议如果你是初学者按下面的路径走投入产出比最高用 Coze 或 Dify 画一个可视化 Agent感受“模型 工具”的组合。用 Python OpenAI SDK 写一个不支持工具调用的极简 Agent比如 5.3 节的版本。用 LangChain 做一个支持工具调用的 Agent理解AgentExecutor的结构。给 Agent 加上 RAG 能力做一个“私有知识库问答机器人”。尝试把 Agent 的日志、记忆、评估体系完善起来。用 FastAPI 把 Agent 封装成 HTTP 服务供前端或其他系统调用。走到第 5 步时你已经超过 90% 的“收藏党”了。不需要看过任何一套 748 集的视频。11. 总结与下一步建议这篇文章讨论的核心其实是两件事第一Agent 开发的本质是让 LLM 在循环中调用工具解决开放性问题它不是简单的 API 调用第二Agent 入门的正确路径是先理解原理再动手做最小实现然后引入成熟框架最后考虑工程化。如果你现在刚看完这篇文章下一步可以从一个非常小的场景开始比如做一个“桌面便签助手”让 Agent 能创建、查询、删除本地文件中的笔记。这个项目用不了多少行代码但能让你完整经历工具定义、记忆管理、多轮对话、排错的全过程。真正值得投入精力的方向是RAG 在垂直领域的落地、多 Agent 协作的生产级可靠性、Agent 的可观测性与评测体系。这几个方向在未来两三年里都会有持续的需求。对于那些收藏了“全套教程”的朋友我的建议是不要试图看完直接找到第 20 集左右的“第一个实战项目”跟着做一遍卡住了再回看。用项目倒逼学习比线性刷视频有效得多。动手做一个能跑的 Agent胜过收藏十套教程。