想系统入门 AI Agent 智能体开发却总是被各种概念、框架、平台绕晕网上教程很多但要么偏理论看不懂要么直接甩代码不讲原理。这篇文章围绕 Agent 开发整理了一套完整的零基础学习路径从核心概念、工具选型到 Dify 低代码搭建、Python 手写最小 Agent再到部署排错全部覆盖。无论你是学生、测试、运维还是后端开发都可以照着一步步实践。1. AI Agent 是什么先理解智能体的核心概念1.1 从一个提问场景理解 Agent先看一个最简单的对比。传统聊天机器人用户帮我查一下北京今天的天气 机器人好的正在为你查询……然后根据训练数据或固定接口返回结果AI Agent智能体用户帮我安排明天上午的行程如果下雨就改成室内活动并提醒我带伞 Agent 1. 调用天气接口查询明天天气 2. 发现上午有雨 3. 调用日历工具查看已有安排 4. 把原定的室外活动调整为室内 5. 生成提醒内容并发给用户这个例子里Agent 做的不只是“生成文字”而是理解目标、拆解任务、调用工具、做出决策最后完成一个闭环。这也是“智能体”和“聊天机器人”最本质的区别。1.2 Agent 与大模型、工作流的区别很多人会把“大模型”“RAG”“工作流”“Agent”这几个词混在一起这里先做一个简单区分概念核心作用举例大模型文本生成、理解、推理GPT、DeepSeek、QwenRAG让模型基于外部知识回答检索文档后回答工作流固定步骤的自动化流程if-else 判断按固定顺序执行Agent模型自主决策动态规划执行步骤根据目标自行选择调用哪些工具工作流和 Agent 的区别最容易被忽略。工作流是“写死的流程”先做什么、再做什么、失败怎么办都是开发时定义好的。Agent 则是“动态决策”模型根据用户输入自己决定先调用哪个工具、是否需要多轮调用、最终怎么组织答案。从项目落地角度看如果业务场景非常固定工作流更稳定、成本更可控如果场景开放、变化多Agent 的灵活性优势就体现出来了。1.3 Agent 的四大核心组件目前业界普遍认为一个完整的 Agent 至少包含四个部分大模型LLM大脑负责理解、推理、生成。规划Planning把目标拆分成子任务决定执行顺序。记忆Memory保存上下文、短期对话信息、长期知识。工具Tools模型可以调用的外部能力如搜索、计算、API、数据库。如果把 Agent 比作一个员工大模型是“脑子”规划能力是“做事思路”记忆是“工作笔记”工具是“手里的工具包”后面所有代码和平台配置本质上都是在组合这四个部分。2. 零基础入门路线5 天学习计划怎么安排2.1 第 1 天理解概念体验现成 Agent第一天不需要写代码重点是把概念建立起来。建议做三件事使用 Coze扣子、Dify 云服务等平台体验通过可视化界面创建 Agent。找一个现成的 Agent 应用比如翻译助手、客服助手观察它的回答过程。记录 Agent 的“思考”过程比如它调用了哪些工具、输出了什么中间结果。第一天结束你应该能回答这几个问题Agent 和普通聊天机器人的区别是什么Agent 在处理一个任务时会经历哪些步骤什么场景适合用 Agent什么场景不适合2.2 第 2 天掌握提示词与函数调用Agent 的行为高度依赖提示词Prompt同时很多 Agent 能力来自函数调用Function Calling / Tool Calling。第二天学习重点写系统提示词告诉 Agent 它的角色、能力边界、回答风格。理解 Function Calling 的作用让模型输出“要调用哪个函数、传什么参数”再由程序真正执行。学习 JSON 格式的输入输出因为模型和工具之间主要通过 JSON 通信。2.3 第 3 天使用低代码平台搭建 Agent推荐从 Dify 或 Coze 入手。低代码平台的价值在于不需要先掌握复杂编程就能体验 Agent 的完整开发流程包括选择大模型配置提示词添加工具设置知识库调试对话发布为 API 或分享链接第三天可以完成一个小项目搭建一个“会议室预订助手”让它能够查询空闲会议室、预订会议室、发送通知。2.4 第 4 天用代码开发自己的 Agent有了平台经验之后再用代码实现一遍理解底层原理。推荐学习路径直接调用大模型 API写一个最简的“模型问答”脚本。在脚本中加入工具调用逻辑实现一个最小 Agent 循环。使用主流 Agent 框架如 LangChain、LlamaIndex 或国产框架重写一遍。第四天不用追求复杂关键是理解 Agent 循环接收输入 - 模型推理 - 可能调用工具 - 再次推理 - 输出结果。2.5 第 5 天部署与实战项目最后一天做一个小型完整项目并部署到服务器或云平台。可以参考的方向日志分析 Agent让 Agent 通过 ES REST API 查询日志、总结异常。销售助手 Agent根据客户咨询信息生成跟进建议。企业知识库 Agent结合 RAG让 Agent 基于企业内部文档回答问题。部署时重点关注API 密钥管理、日志记录、超时处理、并发控制。3. 环境准备与工具选型3.1 开发环境开发 Agent 对电脑配置要求不高建议环境如下操作系统Windows 10/11、macOS、Linux 均可Python 版本建议 Python 3.10 或更高包管理工具pip 或 condaIDEVS Code、PyCharm 均可网络需要能正常访问大模型 API如果你是零基础推荐先装 Anaconda再用 conda 创建独立环境避免不同项目之间的依赖冲突。conda create -n agent python3.10 conda activate agent pip install --upgrade pip3.2 大模型 API 选择目前国内可用的模型 API 很多。常见的选择包括DeepSeek API通义千问 API智谱 GLM APIOpenAI 兼容接口不同模型的函数调用能力、上下文长度、价格差异都比较大。建议先选一个兼容 OpenAI SDK 的模型因为网上资料最多迁移成本低。这里提醒一点大模型 API 是按 token 计费的。在学习和调试阶段尽量用小的测试样例避免反复调用产生不必要的费用。3.3 Agent 开发框架对比框架特点适合人群LangChain生态最丰富组件多有 Python 基础想深入定制LlamaIndex侧重 RAG 和知识库做文档问答类项目Dify低代码平台可视化编排非程序员、快速验证业务Coze扣子字节跳动出品插件丰富快速搭建、国内生态好自研最小框架只依赖模型 API想彻底理解原理的人不建议零基础一上来就研究 LangChain 源码容易劝退。先用 Dify 或 Coze 建立体感再用 Python 手写最小 Agent 理解原理最后再接触大型框架。3.4 项目目录结构示例后面章节的实战代码建议按下面结构组织agent-demo/ ├── main.py # 主程序 ├── tools.py # 工具定义 ├── config.py # 配置 ├── requirements.txt # 依赖 └── .env # 环境变量密钥4. 核心原理拆解Agent 是如何调用工具的4.1 Function Calling 是什么Function Calling函数调用是 Agent 最关键的能力之一。它的工作方式并不是“模型直接帮你执行代码”而是你提前告诉模型“有哪些函数可以用每个函数的参数是什么”。模型根据用户问题输出一个结构化的“函数调用请求”。程序收到这个请求真正去执行对应函数。把函数执行结果返回给模型。模型结合结果生成最终回答。举个例子用户说“帮我算一下 23 乘以 17 的结果”。如果不用工具大模型可能算错如果定义了计算工具模型会先输出{ name: calculator, arguments: { a: 23, b: 17 } }然后程序调用真正的计算函数得到结果 391再交给模型组织成自然语言回答。4.2 一个最简的 Agent 循环所有 Agent不管用多复杂的框架核心都是这个循环while True: 1. 把用户消息 历史上下文 工具描述 发给大模型 2. 模型返回 - 如果结果中带工具调用 - 执行工具把结果追加到对话中回到第 1 步 - 如果没有工具调用 - 这是最终答案跳出循环 3. 展示最终答案这个循环用伪代码表示messages [{role: system, content: system_prompt}] messages.append({role: user, content: user_input}) while True: response llm.chat(messages) if response.tool_calls: for call in response.tool_calls: result execute_tool(call.name, call.arguments) messages.append({ role: tool, name: call.name, content: result }) else: print(response.content) break理解了这个循环你就理解了绝大多数 Agent 框架的核心逻辑。LangChain、Dify、Coze只是在这个循环外面包装了更丰富的记忆管理、工具注册、错误处理能力。4.3 Tool 的定义与注册在代码层面一个工具通常包含工具名称工具描述告诉模型什么情况下用它参数列表包含参数名、类型、说明实际执行函数工具描述非常重要因为大模型是“读描述”来决定是否调用这个工具的。描述写得模糊模型就会在错误场景调用工具。例如一个查询天气的工具描述应该写清楚def get_weather(city: str): 根据城市名称查询实时天气支持中文城市名例如北京、上海。 # 这里替换为真实天气 API 调用 return {city: city, weather: 晴, temperature: 25}工具描述和参数说明越清晰Agent 调用的准确率就越高。5. 实战案例一基于 Dify 零代码搭建一个 AI Agent5.1 为什么推荐 DifyDify 是一个开源的低代码大模型应用开发平台支持可视化编排 Agent、工作流、知识库并且可以一键发布为 API。对于零基础入门者来说Dify 能帮你跳过大量代码细节先看清 Agent 的完整结构。Dify 支持两种使用方式官方云服务注册后直接用适合体验。本地部署通过 Docker 部署到自己的服务器适合企业项目。5.2 创建应用并选择模型登录 Dify 后按下面步骤创建 Agent点击“创建空白应用”。应用类型选择“Agent”。填写应用名称比如“客服助手”。进入应用配置页后选择模型提供商填入自己的 API Key。在 Dify 中模型 API Key 在“设置 - 模型供应商”中配置。建议把多个模型都配置上方便后续切换对比。5.3 编写系统提示词在“编排”页面最重要的就是“系统指令”部分。推荐写法包含四个要素角色定义任务目标工作流程约束回答风格示例你是一名企业客服助手负责解答用户关于产品使用、订单状态和售后政策的问题。 工作流程 1. 先尝试根据已有知识回答。 2. 如果遇到不确定的问题使用“订单查询”或“知识库检索”工具。 3. 如果工具无法解决礼貌告知用户转人工客服渠道。 回答要求 - 使用简洁、友好的语气。 - 涉及订单号时必须通过工具核实后再回答。 - 不要编造不存在的订单信息。这里的核心原则是给 Agent 设定边界避免它“自由发挥”导致回答不可控。5.4 添加工具与知识库Dify 内置了一些常用工具也支持自定义工具。自定义工具时通常需要提供工具名称工具描述OpenAPI 规范描述接口地址、请求方式、参数如果你是零基础可以先使用内置工具比如“网页搜索”“计算器”等。后续再学习如何把自己的 REST API 接入进来。如果 Agent 需要回答企业私有问题还需要配置知识库在“知识库”中上传文档。选择分段方式和索引方式。在 Agent 的编排中将知识库引用进来。5.5 调试与发布Dify 页面右侧有调试窗口可以直接测试 Agent 的效果。调试时建议多试几种输入常规问题看回答是否准确。复杂问题看是否触发了工具调用。模糊问题看是否回答了“不知道”而不是乱编。测试通过后点击“发布”可以生成 API 访问地址供其他系统调用。6. 实战案例二用 Python 从零实现一个最小 Agent6.1 项目说明这一节通过代码实现一个最小可运行的 Agent。它支持两个工具计算器查询当前时间通过这个项目你能深入理解 Agent 循环的运行机制。6.2 安装依赖创建一个虚拟环境然后安装 OpenAI SDK。多数国内模型的 API 都兼容 OpenAI 格式因此统一使用这个 SDK。pip install openai python-dotenv在项目根目录创建.env文件API_KEY你的API密钥 BASE_URLhttps://api.openai.com/v1 MODEL_NAMEgpt-4o-mini如果你的模型是 OpenAI 兼容接口把BASE_URL改成对应服务的地址即可。6.3 定义工具创建tools.py定义两个工具函数同时提供工具描述信息# 文件路径agent-demo/tools.py import datetime import json def get_current_time(): 获取当前日期和时间 now datetime.datetime.now() return now.strftime(%Y-%m-%d %H:%M:%S) def calculate(expression: str): 计算数学表达式例如 23*17、(12)*3 try: # 注意eval 仅在示例环境中使用生产中请用安全方式解析表达式 result eval(expression, {__builtins__: {}}, {}) return json.dumps({expression: expression, result: result}) except Exception as e: return json.dumps({expression: expression, error: str(e)}) TOOLS [ { type: function, function: { name: get_current_time, description: 获取当前日期和时间当用户询问当前时间时使用, parameters: { type: object, properties: {}, required: [] } } }, { type: function, function: { name: calculate, description: 计算数学表达式当用户需要做算术运算时使用, parameters: { type: object, properties: { expression: { type: string, description: 数学表达式例如 23*17 } }, required: [expression] } } } ] def execute_tool(name: str, arguments: str): 根据工具名和 JSON 参数执行工具 args json.loads(arguments) if name get_current_time: return get_current_time() elif name calculate: return calculate(args[expression]) else: return json.dumps({error: f未知工具: {name}})需要说明的是示例中的eval只是为了演示原理生产环境不能用eval建议使用ast.literal_eval或专门的表达式解析库。6.4 编写主程序创建main.py实现 Agent 循环# 文件路径agent-demo/main.py import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOLS, execute_tool load_dotenv() client OpenAI( api_keyos.getenv(API_KEY), base_urlos.getenv(BASE_URL), ) MODEL_NAME os.getenv(MODEL_NAME) SYSTEM_PROMPT ( 你是一个有帮助的智能助手。 你可以使用工具来获取当前时间或执行数学计算。 如果不需要工具直接回答用户。 ) def run_agent(user_input: str): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] max_rounds 5 for _ in range(max_rounds): response client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolsTOOLS, ) message response.choices[0].message if message.tool_calls: messages.append(message) for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args tool_call.function.arguments tool_result execute_tool(tool_name, tool_args) messages.append({ role: tool, tool_call_id: tool_call.id, name: tool_name, content: tool_result, }) else: return message.content return 已达最大轮数结束对话。 if __name__ __main__: while True: user_input input(你) if user_input.lower() in (exit, quit): break answer run_agent(user_input) print(Agent, answer)这段代码的核心逻辑把用户输入加入消息列表。把工具描述通过tools参数传给模型。如果模型返回tool_calls说明它希望调用工具。执行工具后把工具结果以role: tool的形式追加回对话。再次调用模型直到它不再要求调用工具。6.5 运行与验证在终端执行python main.py测试以下输入你现在几点了 Agent当前时间是 2026-01-15 10:30:25。 你帮我算 23*17 Agent23 乘以 17 的结果是 391。 你你好 Agent你好有什么我可以帮你的吗第一个问题触发get_current_time工具第二个问题触发calculate工具第三个问题则直接回答。这个现象说明你的 Agent 已经具备了“自主判断何时使用工具”的能力。7. 常见问题与排查思路在 Agent 开发和调试过程中下面几类问题出现频率最高。问题现象常见原因解决思路模型不调用工具工具描述不清晰或模型不支持 Function Calling检查工具描述确认模型 API 是否支持 tools 参数工具返回结果后Agent 回答错误工具结果没有正确拼接到对话上下文检查role: tool消息是否携带了正确的tool_call_idAPI 返回 401 错误API Key 错误或没有权限检查.env中的密钥确认账户有余额请求超时网络问题或模型响应慢增加超时时间检查网络连通性上下文过长多轮工具调用后消息太多对历史消息做截断或摘要工具参数格式错误模型生成的 JSON 参数不规范在工具解析时增加异常处理必要时让模型重新生成低代码平台工具不生效工具未授权或参数映射不对在平台中重新配置工具授权检查参数名与接口要求一致7.1 模型不调用工具怎么办这是初学者最常见的困惑。排查顺序确认你使用的模型支持 Function Calling。部分轻量模型不支持该能力。确认tools参数正确传递。注意不同 SDK 版本参数名可能不同。检查工具描述是否明确。描述里要写清楚“什么时候用”以及“用户问题里可能出现的关键词”。尝试在系统提示词中引导例如“如果需要获取实时数据请调用对应工具”。7.2 工具结果被模型忽略怎么办如果模型调用了工具但最终回答没使用工具结果最常见的原因是对话消息顺序或角色标记不对。正确的消息顺序应该是system - user - assistant带 tool_calls - tool工具结果 - assistant最终回答如果tool消息丢失或者tool_call_id没对上模型就无法关联工具结果。7.3 如何降低调试成本大模型 API 按 token 计费调试时推荐使用价格较低的模型。控制上下文长度避免携带大量历史记录。使用缓存机制相同请求不重复调用。在代码中打印每次调用的 token 用量便于估算成本。8. 最佳实践与工程建议8.1 提示词是 Agent 的灵魂同样的工具和代码提示词不同Agent 效果差异巨大。写系统提示词时建议遵循以下原则明确角色告诉 Agent 它是什么。定义边界哪些事情可以做哪些事情不能做。给出流程先做什么后做什么。指定输出格式需要结构化输出时明确要求 JSON。强调安全涉及用户隐私、订单信息时必须通过工具核实。8.2 工具设计要“小而专”每个工具只做一件事不要写一个又大又模糊的“万能工具”。好的工具查询订单状态(订单号) 查询商品库存(商品ID) 计算运费(地址, 商品重量)不好的工具处理业务(参数)工具粒度越细模型越容易理解调用准确率越高后续也更容易维护。8.3 做好异常处理与兜底Agent 是概率系统不可能保证 100% 正确。工程上必须预设兜底策略工具调用失败时捕获异常并返回友好的错误信息。模型连续多次调用工具仍未结束时强制终止循环。对不确定的问题允许 Agent 回答“我不知道”而不是编造。用户输入包含敏感信息时增加脱敏处理。8.4 日志与可观测性生产环境中的 Agent 必须有日志。推荐至少记录用户原始输入模型每次返回的内容工具调用的名称、参数、结果每次调用的 token 消耗最终的响应内容和耗时这些日志不仅能帮你排错还能帮助你评估 Agent 的效果并持续优化提示词。8.5 安全与权限控制Agent 能调用工具也意味着它可能访问到敏感系统。在生产环境中必须遵循最小权限原则每个 Agent 只拥有完成业务必需的工具权限。API 密钥使用环境变量或密钥管理服务保存不要硬编码到代码里。涉及删除、修改、转账等高风险操作时增加二次确认机制。对 Agent 调用外部 API 的频率做限流。定期审查 Agent 的工具调用日志及时发现异常行为。8.6 效果评估不能靠感觉Agent 开发完成后建议建立一个简单的测试集。比如准备 20 到 50 个典型问题包含必须调用工具的问题普通问答问题边界与模糊问题异常输入问题每次修改提示词或工具定义后都跑一遍测试集对比前后效果。这样你的优化是可持续的而不是“调完一个用例另一个用例又坏了”。9. 总结与下一步学习路线写到这里你已经完整走过了 AI Agent 从概念到实战的入门路径。回顾一下我们主要掌握了以下几个方面理解了 Agent 的核心概念大模型、规划、记忆、工具。规划了 5 天入门路线从体验平台到写代码再到部署。掌握了 Function Calling 的核心机制并用 Python 实现了一个最小 Agent。学习了如何使用 Dify 零代码快速搭建 Agent。知道了如何排查模型不调用工具、上下文过长、工具结果丢失等常见问题。了解了生产环境中 Agent 的工程化注意事项包括提示词设计、日志、安全、评估。如果你现在能独立在 Dify 上搭建一个含工具和知识库的 Agent也能用 Python 写一个调用工具的小程序那说明你已经迈过了 Agent 开发最难的入门阶段。接下来可以继续学习的方向记忆机制深化把短期记忆升级为长期记忆比如接入向量数据库存储历史会话。多 Agent 协作让多个 Agent 分工合作比如一个负责规划、一个负责执行、一个负责审查。Agent 与大模型微调结合针对特定业务场景用高质量数据微调模型提升工具调用准确率。生产级部署学习容器化部署、日志采集、链路追踪、灰度发布。RAG 与 Agent 结合让 Agent 不仅能调工具还能动态检索企业知识库。最后给你一个建议不要一头扎进复杂框架的源码里。先做出一个能跑、能测试、能上线的小项目再在真实业务问题驱动下逐步深入。Agent 开发并不神秘它的核心就是“模型 工具 循环”的组合。把最小闭环跑通后面的路会越走越宽。如果这篇文章对你有帮助可以收藏备用。动手写一个你自己的最小 Agent比看十篇教程都管用。 AI Agent智能体开发零基础入门：核心概念、工具与实战路径
想系统入门 AI Agent 智能体开发却总是被各种概念、框架、平台绕晕网上教程很多但要么偏理论看不懂要么直接甩代码不讲原理。这篇文章围绕 Agent 开发整理了一套完整的零基础学习路径从核心概念、工具选型到 Dify 低代码搭建、Python 手写最小 Agent再到部署排错全部覆盖。无论你是学生、测试、运维还是后端开发都可以照着一步步实践。1. AI Agent 是什么先理解智能体的核心概念1.1 从一个提问场景理解 Agent先看一个最简单的对比。传统聊天机器人用户帮我查一下北京今天的天气 机器人好的正在为你查询……然后根据训练数据或固定接口返回结果AI Agent智能体用户帮我安排明天上午的行程如果下雨就改成室内活动并提醒我带伞 Agent 1. 调用天气接口查询明天天气 2. 发现上午有雨 3. 调用日历工具查看已有安排 4. 把原定的室外活动调整为室内 5. 生成提醒内容并发给用户这个例子里Agent 做的不只是“生成文字”而是理解目标、拆解任务、调用工具、做出决策最后完成一个闭环。这也是“智能体”和“聊天机器人”最本质的区别。1.2 Agent 与大模型、工作流的区别很多人会把“大模型”“RAG”“工作流”“Agent”这几个词混在一起这里先做一个简单区分概念核心作用举例大模型文本生成、理解、推理GPT、DeepSeek、QwenRAG让模型基于外部知识回答检索文档后回答工作流固定步骤的自动化流程if-else 判断按固定顺序执行Agent模型自主决策动态规划执行步骤根据目标自行选择调用哪些工具工作流和 Agent 的区别最容易被忽略。工作流是“写死的流程”先做什么、再做什么、失败怎么办都是开发时定义好的。Agent 则是“动态决策”模型根据用户输入自己决定先调用哪个工具、是否需要多轮调用、最终怎么组织答案。从项目落地角度看如果业务场景非常固定工作流更稳定、成本更可控如果场景开放、变化多Agent 的灵活性优势就体现出来了。1.3 Agent 的四大核心组件目前业界普遍认为一个完整的 Agent 至少包含四个部分大模型LLM大脑负责理解、推理、生成。规划Planning把目标拆分成子任务决定执行顺序。记忆Memory保存上下文、短期对话信息、长期知识。工具Tools模型可以调用的外部能力如搜索、计算、API、数据库。如果把 Agent 比作一个员工大模型是“脑子”规划能力是“做事思路”记忆是“工作笔记”工具是“手里的工具包”后面所有代码和平台配置本质上都是在组合这四个部分。2. 零基础入门路线5 天学习计划怎么安排2.1 第 1 天理解概念体验现成 Agent第一天不需要写代码重点是把概念建立起来。建议做三件事使用 Coze扣子、Dify 云服务等平台体验通过可视化界面创建 Agent。找一个现成的 Agent 应用比如翻译助手、客服助手观察它的回答过程。记录 Agent 的“思考”过程比如它调用了哪些工具、输出了什么中间结果。第一天结束你应该能回答这几个问题Agent 和普通聊天机器人的区别是什么Agent 在处理一个任务时会经历哪些步骤什么场景适合用 Agent什么场景不适合2.2 第 2 天掌握提示词与函数调用Agent 的行为高度依赖提示词Prompt同时很多 Agent 能力来自函数调用Function Calling / Tool Calling。第二天学习重点写系统提示词告诉 Agent 它的角色、能力边界、回答风格。理解 Function Calling 的作用让模型输出“要调用哪个函数、传什么参数”再由程序真正执行。学习 JSON 格式的输入输出因为模型和工具之间主要通过 JSON 通信。2.3 第 3 天使用低代码平台搭建 Agent推荐从 Dify 或 Coze 入手。低代码平台的价值在于不需要先掌握复杂编程就能体验 Agent 的完整开发流程包括选择大模型配置提示词添加工具设置知识库调试对话发布为 API 或分享链接第三天可以完成一个小项目搭建一个“会议室预订助手”让它能够查询空闲会议室、预订会议室、发送通知。2.4 第 4 天用代码开发自己的 Agent有了平台经验之后再用代码实现一遍理解底层原理。推荐学习路径直接调用大模型 API写一个最简的“模型问答”脚本。在脚本中加入工具调用逻辑实现一个最小 Agent 循环。使用主流 Agent 框架如 LangChain、LlamaIndex 或国产框架重写一遍。第四天不用追求复杂关键是理解 Agent 循环接收输入 - 模型推理 - 可能调用工具 - 再次推理 - 输出结果。2.5 第 5 天部署与实战项目最后一天做一个小型完整项目并部署到服务器或云平台。可以参考的方向日志分析 Agent让 Agent 通过 ES REST API 查询日志、总结异常。销售助手 Agent根据客户咨询信息生成跟进建议。企业知识库 Agent结合 RAG让 Agent 基于企业内部文档回答问题。部署时重点关注API 密钥管理、日志记录、超时处理、并发控制。3. 环境准备与工具选型3.1 开发环境开发 Agent 对电脑配置要求不高建议环境如下操作系统Windows 10/11、macOS、Linux 均可Python 版本建议 Python 3.10 或更高包管理工具pip 或 condaIDEVS Code、PyCharm 均可网络需要能正常访问大模型 API如果你是零基础推荐先装 Anaconda再用 conda 创建独立环境避免不同项目之间的依赖冲突。conda create -n agent python3.10 conda activate agent pip install --upgrade pip3.2 大模型 API 选择目前国内可用的模型 API 很多。常见的选择包括DeepSeek API通义千问 API智谱 GLM APIOpenAI 兼容接口不同模型的函数调用能力、上下文长度、价格差异都比较大。建议先选一个兼容 OpenAI SDK 的模型因为网上资料最多迁移成本低。这里提醒一点大模型 API 是按 token 计费的。在学习和调试阶段尽量用小的测试样例避免反复调用产生不必要的费用。3.3 Agent 开发框架对比框架特点适合人群LangChain生态最丰富组件多有 Python 基础想深入定制LlamaIndex侧重 RAG 和知识库做文档问答类项目Dify低代码平台可视化编排非程序员、快速验证业务Coze扣子字节跳动出品插件丰富快速搭建、国内生态好自研最小框架只依赖模型 API想彻底理解原理的人不建议零基础一上来就研究 LangChain 源码容易劝退。先用 Dify 或 Coze 建立体感再用 Python 手写最小 Agent 理解原理最后再接触大型框架。3.4 项目目录结构示例后面章节的实战代码建议按下面结构组织agent-demo/ ├── main.py # 主程序 ├── tools.py # 工具定义 ├── config.py # 配置 ├── requirements.txt # 依赖 └── .env # 环境变量密钥4. 核心原理拆解Agent 是如何调用工具的4.1 Function Calling 是什么Function Calling函数调用是 Agent 最关键的能力之一。它的工作方式并不是“模型直接帮你执行代码”而是你提前告诉模型“有哪些函数可以用每个函数的参数是什么”。模型根据用户问题输出一个结构化的“函数调用请求”。程序收到这个请求真正去执行对应函数。把函数执行结果返回给模型。模型结合结果生成最终回答。举个例子用户说“帮我算一下 23 乘以 17 的结果”。如果不用工具大模型可能算错如果定义了计算工具模型会先输出{ name: calculator, arguments: { a: 23, b: 17 } }然后程序调用真正的计算函数得到结果 391再交给模型组织成自然语言回答。4.2 一个最简的 Agent 循环所有 Agent不管用多复杂的框架核心都是这个循环while True: 1. 把用户消息 历史上下文 工具描述 发给大模型 2. 模型返回 - 如果结果中带工具调用 - 执行工具把结果追加到对话中回到第 1 步 - 如果没有工具调用 - 这是最终答案跳出循环 3. 展示最终答案这个循环用伪代码表示messages [{role: system, content: system_prompt}] messages.append({role: user, content: user_input}) while True: response llm.chat(messages) if response.tool_calls: for call in response.tool_calls: result execute_tool(call.name, call.arguments) messages.append({ role: tool, name: call.name, content: result }) else: print(response.content) break理解了这个循环你就理解了绝大多数 Agent 框架的核心逻辑。LangChain、Dify、Coze只是在这个循环外面包装了更丰富的记忆管理、工具注册、错误处理能力。4.3 Tool 的定义与注册在代码层面一个工具通常包含工具名称工具描述告诉模型什么情况下用它参数列表包含参数名、类型、说明实际执行函数工具描述非常重要因为大模型是“读描述”来决定是否调用这个工具的。描述写得模糊模型就会在错误场景调用工具。例如一个查询天气的工具描述应该写清楚def get_weather(city: str): 根据城市名称查询实时天气支持中文城市名例如北京、上海。 # 这里替换为真实天气 API 调用 return {city: city, weather: 晴, temperature: 25}工具描述和参数说明越清晰Agent 调用的准确率就越高。5. 实战案例一基于 Dify 零代码搭建一个 AI Agent5.1 为什么推荐 DifyDify 是一个开源的低代码大模型应用开发平台支持可视化编排 Agent、工作流、知识库并且可以一键发布为 API。对于零基础入门者来说Dify 能帮你跳过大量代码细节先看清 Agent 的完整结构。Dify 支持两种使用方式官方云服务注册后直接用适合体验。本地部署通过 Docker 部署到自己的服务器适合企业项目。5.2 创建应用并选择模型登录 Dify 后按下面步骤创建 Agent点击“创建空白应用”。应用类型选择“Agent”。填写应用名称比如“客服助手”。进入应用配置页后选择模型提供商填入自己的 API Key。在 Dify 中模型 API Key 在“设置 - 模型供应商”中配置。建议把多个模型都配置上方便后续切换对比。5.3 编写系统提示词在“编排”页面最重要的就是“系统指令”部分。推荐写法包含四个要素角色定义任务目标工作流程约束回答风格示例你是一名企业客服助手负责解答用户关于产品使用、订单状态和售后政策的问题。 工作流程 1. 先尝试根据已有知识回答。 2. 如果遇到不确定的问题使用“订单查询”或“知识库检索”工具。 3. 如果工具无法解决礼貌告知用户转人工客服渠道。 回答要求 - 使用简洁、友好的语气。 - 涉及订单号时必须通过工具核实后再回答。 - 不要编造不存在的订单信息。这里的核心原则是给 Agent 设定边界避免它“自由发挥”导致回答不可控。5.4 添加工具与知识库Dify 内置了一些常用工具也支持自定义工具。自定义工具时通常需要提供工具名称工具描述OpenAPI 规范描述接口地址、请求方式、参数如果你是零基础可以先使用内置工具比如“网页搜索”“计算器”等。后续再学习如何把自己的 REST API 接入进来。如果 Agent 需要回答企业私有问题还需要配置知识库在“知识库”中上传文档。选择分段方式和索引方式。在 Agent 的编排中将知识库引用进来。5.5 调试与发布Dify 页面右侧有调试窗口可以直接测试 Agent 的效果。调试时建议多试几种输入常规问题看回答是否准确。复杂问题看是否触发了工具调用。模糊问题看是否回答了“不知道”而不是乱编。测试通过后点击“发布”可以生成 API 访问地址供其他系统调用。6. 实战案例二用 Python 从零实现一个最小 Agent6.1 项目说明这一节通过代码实现一个最小可运行的 Agent。它支持两个工具计算器查询当前时间通过这个项目你能深入理解 Agent 循环的运行机制。6.2 安装依赖创建一个虚拟环境然后安装 OpenAI SDK。多数国内模型的 API 都兼容 OpenAI 格式因此统一使用这个 SDK。pip install openai python-dotenv在项目根目录创建.env文件API_KEY你的API密钥 BASE_URLhttps://api.openai.com/v1 MODEL_NAMEgpt-4o-mini如果你的模型是 OpenAI 兼容接口把BASE_URL改成对应服务的地址即可。6.3 定义工具创建tools.py定义两个工具函数同时提供工具描述信息# 文件路径agent-demo/tools.py import datetime import json def get_current_time(): 获取当前日期和时间 now datetime.datetime.now() return now.strftime(%Y-%m-%d %H:%M:%S) def calculate(expression: str): 计算数学表达式例如 23*17、(12)*3 try: # 注意eval 仅在示例环境中使用生产中请用安全方式解析表达式 result eval(expression, {__builtins__: {}}, {}) return json.dumps({expression: expression, result: result}) except Exception as e: return json.dumps({expression: expression, error: str(e)}) TOOLS [ { type: function, function: { name: get_current_time, description: 获取当前日期和时间当用户询问当前时间时使用, parameters: { type: object, properties: {}, required: [] } } }, { type: function, function: { name: calculate, description: 计算数学表达式当用户需要做算术运算时使用, parameters: { type: object, properties: { expression: { type: string, description: 数学表达式例如 23*17 } }, required: [expression] } } } ] def execute_tool(name: str, arguments: str): 根据工具名和 JSON 参数执行工具 args json.loads(arguments) if name get_current_time: return get_current_time() elif name calculate: return calculate(args[expression]) else: return json.dumps({error: f未知工具: {name}})需要说明的是示例中的eval只是为了演示原理生产环境不能用eval建议使用ast.literal_eval或专门的表达式解析库。6.4 编写主程序创建main.py实现 Agent 循环# 文件路径agent-demo/main.py import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOLS, execute_tool load_dotenv() client OpenAI( api_keyos.getenv(API_KEY), base_urlos.getenv(BASE_URL), ) MODEL_NAME os.getenv(MODEL_NAME) SYSTEM_PROMPT ( 你是一个有帮助的智能助手。 你可以使用工具来获取当前时间或执行数学计算。 如果不需要工具直接回答用户。 ) def run_agent(user_input: str): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] max_rounds 5 for _ in range(max_rounds): response client.chat.completions.create( modelMODEL_NAME, messagesmessages, toolsTOOLS, ) message response.choices[0].message if message.tool_calls: messages.append(message) for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args tool_call.function.arguments tool_result execute_tool(tool_name, tool_args) messages.append({ role: tool, tool_call_id: tool_call.id, name: tool_name, content: tool_result, }) else: return message.content return 已达最大轮数结束对话。 if __name__ __main__: while True: user_input input(你) if user_input.lower() in (exit, quit): break answer run_agent(user_input) print(Agent, answer)这段代码的核心逻辑把用户输入加入消息列表。把工具描述通过tools参数传给模型。如果模型返回tool_calls说明它希望调用工具。执行工具后把工具结果以role: tool的形式追加回对话。再次调用模型直到它不再要求调用工具。6.5 运行与验证在终端执行python main.py测试以下输入你现在几点了 Agent当前时间是 2026-01-15 10:30:25。 你帮我算 23*17 Agent23 乘以 17 的结果是 391。 你你好 Agent你好有什么我可以帮你的吗第一个问题触发get_current_time工具第二个问题触发calculate工具第三个问题则直接回答。这个现象说明你的 Agent 已经具备了“自主判断何时使用工具”的能力。7. 常见问题与排查思路在 Agent 开发和调试过程中下面几类问题出现频率最高。问题现象常见原因解决思路模型不调用工具工具描述不清晰或模型不支持 Function Calling检查工具描述确认模型 API 是否支持 tools 参数工具返回结果后Agent 回答错误工具结果没有正确拼接到对话上下文检查role: tool消息是否携带了正确的tool_call_idAPI 返回 401 错误API Key 错误或没有权限检查.env中的密钥确认账户有余额请求超时网络问题或模型响应慢增加超时时间检查网络连通性上下文过长多轮工具调用后消息太多对历史消息做截断或摘要工具参数格式错误模型生成的 JSON 参数不规范在工具解析时增加异常处理必要时让模型重新生成低代码平台工具不生效工具未授权或参数映射不对在平台中重新配置工具授权检查参数名与接口要求一致7.1 模型不调用工具怎么办这是初学者最常见的困惑。排查顺序确认你使用的模型支持 Function Calling。部分轻量模型不支持该能力。确认tools参数正确传递。注意不同 SDK 版本参数名可能不同。检查工具描述是否明确。描述里要写清楚“什么时候用”以及“用户问题里可能出现的关键词”。尝试在系统提示词中引导例如“如果需要获取实时数据请调用对应工具”。7.2 工具结果被模型忽略怎么办如果模型调用了工具但最终回答没使用工具结果最常见的原因是对话消息顺序或角色标记不对。正确的消息顺序应该是system - user - assistant带 tool_calls - tool工具结果 - assistant最终回答如果tool消息丢失或者tool_call_id没对上模型就无法关联工具结果。7.3 如何降低调试成本大模型 API 按 token 计费调试时推荐使用价格较低的模型。控制上下文长度避免携带大量历史记录。使用缓存机制相同请求不重复调用。在代码中打印每次调用的 token 用量便于估算成本。8. 最佳实践与工程建议8.1 提示词是 Agent 的灵魂同样的工具和代码提示词不同Agent 效果差异巨大。写系统提示词时建议遵循以下原则明确角色告诉 Agent 它是什么。定义边界哪些事情可以做哪些事情不能做。给出流程先做什么后做什么。指定输出格式需要结构化输出时明确要求 JSON。强调安全涉及用户隐私、订单信息时必须通过工具核实。8.2 工具设计要“小而专”每个工具只做一件事不要写一个又大又模糊的“万能工具”。好的工具查询订单状态(订单号) 查询商品库存(商品ID) 计算运费(地址, 商品重量)不好的工具处理业务(参数)工具粒度越细模型越容易理解调用准确率越高后续也更容易维护。8.3 做好异常处理与兜底Agent 是概率系统不可能保证 100% 正确。工程上必须预设兜底策略工具调用失败时捕获异常并返回友好的错误信息。模型连续多次调用工具仍未结束时强制终止循环。对不确定的问题允许 Agent 回答“我不知道”而不是编造。用户输入包含敏感信息时增加脱敏处理。8.4 日志与可观测性生产环境中的 Agent 必须有日志。推荐至少记录用户原始输入模型每次返回的内容工具调用的名称、参数、结果每次调用的 token 消耗最终的响应内容和耗时这些日志不仅能帮你排错还能帮助你评估 Agent 的效果并持续优化提示词。8.5 安全与权限控制Agent 能调用工具也意味着它可能访问到敏感系统。在生产环境中必须遵循最小权限原则每个 Agent 只拥有完成业务必需的工具权限。API 密钥使用环境变量或密钥管理服务保存不要硬编码到代码里。涉及删除、修改、转账等高风险操作时增加二次确认机制。对 Agent 调用外部 API 的频率做限流。定期审查 Agent 的工具调用日志及时发现异常行为。8.6 效果评估不能靠感觉Agent 开发完成后建议建立一个简单的测试集。比如准备 20 到 50 个典型问题包含必须调用工具的问题普通问答问题边界与模糊问题异常输入问题每次修改提示词或工具定义后都跑一遍测试集对比前后效果。这样你的优化是可持续的而不是“调完一个用例另一个用例又坏了”。9. 总结与下一步学习路线写到这里你已经完整走过了 AI Agent 从概念到实战的入门路径。回顾一下我们主要掌握了以下几个方面理解了 Agent 的核心概念大模型、规划、记忆、工具。规划了 5 天入门路线从体验平台到写代码再到部署。掌握了 Function Calling 的核心机制并用 Python 实现了一个最小 Agent。学习了如何使用 Dify 零代码快速搭建 Agent。知道了如何排查模型不调用工具、上下文过长、工具结果丢失等常见问题。了解了生产环境中 Agent 的工程化注意事项包括提示词设计、日志、安全、评估。如果你现在能独立在 Dify 上搭建一个含工具和知识库的 Agent也能用 Python 写一个调用工具的小程序那说明你已经迈过了 Agent 开发最难的入门阶段。接下来可以继续学习的方向记忆机制深化把短期记忆升级为长期记忆比如接入向量数据库存储历史会话。多 Agent 协作让多个 Agent 分工合作比如一个负责规划、一个负责执行、一个负责审查。Agent 与大模型微调结合针对特定业务场景用高质量数据微调模型提升工具调用准确率。生产级部署学习容器化部署、日志采集、链路追踪、灰度发布。RAG 与 Agent 结合让 Agent 不仅能调工具还能动态检索企业知识库。最后给你一个建议不要一头扎进复杂框架的源码里。先做出一个能跑、能测试、能上线的小项目再在真实业务问题驱动下逐步深入。Agent 开发并不神秘它的核心就是“模型 工具 循环”的组合。把最小闭环跑通后面的路会越走越宽。如果这篇文章对你有帮助可以收藏备用。动手写一个你自己的最小 Agent比看十篇教程都管用。