看到很多人想学 AI Agent但一开始都会被各种名词绕晕大模型、提示词、Function Calling、RAG、工作流、多智能体……资料看了一堆真正要自己动手做一个“能干活”的智能体时又不知道代码该从哪写起。这篇文章打算用一套完整且能落地的思路把 AI Agent 的核心原理、环境准备、代码实现以及 Dify 这类低代码平台的使用方法串起来。不管你是刚接触 AI 开发的大学生还是想在公司内部落地智能体应用的工程师都可以把它当作一份入门到实战的参考笔记。近几年 AI 领域变化非常快工具和平台也在不断更新所以本文不会去堆一堆容易被淘汰的琐碎操作而是尽量把底层概念和设计思路讲清楚。先搞懂这些后面无论换成哪个框架、哪个平台你都能很快上手。1. AI Agent 到底是什么为什么零基础也能学1.1 从一个业务场景说起普通程序、大模型和智能体的区别假设你要做一个售后客服机器人它需要完成“查订单状态→判断是否需要理赔→生成处理结果”这类任务。如果用普通程序写流程会非常固定接收输入、用正则或关键词匹配、查数据库、输出结果。遇到用户换一种问法程序可能就听不懂了。如果把这个任务直接丢给大模型大模型确实能理解自然语言也能生成回答但它拿不到你的订单数据无法查询真实订单状态只能根据训练数据“猜”回答结果并不可靠甚至会出现编造信息的情况。AI Agent 的解决思路是让大模型当“大脑”负责理解用户意图、拆解任务、判断下一步做什么同时给它接上“手脚”也就是各种工具比如订单查询接口、数据库查询接口、API 服务等。用户说“帮我看看我的订单到哪里了”Agent 会先理解这句话决定调用查询订单的工具拿到真实数据后再组织语言回复用户。所以可以这样理解对象核心特点能做什么普通程序规则写死逻辑固定按照代码逻辑重复执行大模型有语言理解和生成能力回答问题、写文案、翻译、总结AI Agent能理解目标、调用工具、自我反思查数据、操作接口、自动完成任务这也是 AI Agent 价值最大的地方它把大模型的语言能力和真实世界里的数据、接口、系统连接在一起让 AI 不仅能“说”还能“做”。1.2 AI Agent 的核心组成业内讨论 AI Agent 时通常会提到五个核心模块大模型LLM负责理解、推理、生成是 Agent 的“大脑”。规划Planning把一个复杂目标拆成多个子任务并决定执行顺序。记忆Memory保存用户偏好、历史对话、临时状态。记忆又分短期记忆和长期记忆。工具ToolsAgent 可以调用的外部能力比如查询天气、搜索网页、执行代码、调用数据库、访问 REST API。行动Action真正执行结果或反馈给用户的动作。一个典型的运行过程是用户输入目标 → 大模型理解并规划 → Agent 选择合适工具 → 调用工具拿到结果 → 大模型根据结果判断是否完成 → 如果没完成继续调用工具直到完成或达到上限。1.3 AI Agent 的常见应用场景目前 AI Agent 已经在不少业务场景中落地这里举几个比较典型的例子客服与售前咨询自动判断用户意图查询订单、物流、库存生成回复或转人工。日志与数据分析通过自然语言让 Agent 查询 Elasticsearch、数据库或数据仓库自动产出分析结论。自动化办公读取邮件、生成周报、整理表格、安排日程。代码助手根据需求写代码、跑测试、修复报错。销售助手分析客户画像生成跟进话术甚至自动记录 CRM。企业知识库问答结合 RAG检索增强生成让 Agent 基于内部文档回答问题。这些场景背后都有一套类似的方法论大模型负责决策工具负责执行。1.4 零基础学习 AI Agent 的路线参考如果你完全是从零开始建议按照下面这个方向推进第 1 天搞懂大模型 API 的基本用法写一个最简单的对话程序。第 2 天学习 Function Calling函数调用让模型能调用自定义函数。第 3 天给 Agent 加工具和记忆做一个能查询天气或查询订单的小例子。第 4 天学习 Dify、Coze 等低代码平台用拖拽方式搭建一个客服智能体。第 5 天把前面的能力整合成一个完整项目比如日志分析 Agent 或知识库问答 Agent。这篇文章的整体结构也是按照这条路线来设计的。2. 环境准备与版本说明2.1 基础运行环境学习 AI Agent 开发需要准备一个 Python 开发环境。建议使用 Python 3.10 或更高版本因为新的类型注解和异步能力在新版本中更稳定。你本机需要安装Python 3.10pip 包管理工具一个代码编辑器推荐 VS Code 或 PyCharm一个终端环境Windows 下可以使用 PowerShell 或 CMDmacOS/Linux 下使用自带终端即可建议在项目目录下创建独立的虚拟环境python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活虚拟环境后再安装依赖避免污染全局环境。2.2 大模型 API 的获取方式目前 OpenAI 的接口格式已经成为事实标准很多国内外大模型服务都提供与 OpenAI 兼容的 API。为了写代码演示你需要准备一个 API Key并在代码中通过环境变量配置不建议把密钥硬编码进项目文件。如果你的网络环境无法直接访问 OpenAI 服务也可以选择国内支持 OpenAI 兼容接口的大模型服务商或者使用本地模型工具比如 Ollama。本文中的代码主要使用 OpenAI 兼容接口的写法换模型服务时通常只需要修改base_url、api_key和model三个参数。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。2.3 需要安装的 Python 依赖为了让示例代码尽量简单只需要两个核心依赖# requirements.txt openai1.0.0 requests2.31.0安装命令pip install -r requirements.txt如果你后面要做 RAG 或向量检索还需要安装向量数据库相关依赖这里先不做展开。2.4 示例项目目录结构为了便于后续扩展维护建议把项目拆成下面这种结构agent-demo/ ├── requirements.txt ├── config.py ├── tools/ │ ├── __init__.py │ ├── time_tool.py │ ├── order_tool.py │ └── es_tool.py └── agent.py当然第一次跑通示例时也可以先写成一个agent_demo.py文件理解核心逻辑后再拆分。3. Agent 核心概念拆解大模型、Function Calling、记忆与规划很多教程上来就直接甩框架代码新手很容易看懵。这里先把几个关键概念拆开讲清楚。3.1 大模型在 Agent 中扮演什么角色大模型在 Agent 里主要承担决策层的工作。它负责理解用户请求、判断该调用哪个工具、根据工具返回结果生成最终答案。这里需要注意一个容易误解的地方大模型本身不能直接执行函数或访问数据库它只能“生成文本”。所谓的 Function Calling本质上是让模型输出一段结构化内容描述它想调用哪个函数、参数是什么。这段内容会交给 Agent 代码去执行执行结果再拼回给模型继续推理。你可以把大模型理解成一个“项目经理”它负责分配任务、整理结果但具体干活的是“工具”。3.2 什么是 ReAct 模式ReAct 是 Reasoning推理和 Acting行动的结合是目前 Agent 常用的一种控制模式。它的核心循环是思考当前问题我已知什么我还需要什么。行动调用某个工具获取信息。观察拿到工具返回结果。再思考、再行动直到完成任务。举个例子用户问“北京市今天适合出门吗”Agent 的推理过程可能是思考我需要知道北京的天气情况。行动调用 get_weather(city北京)。观察返回“多云15℃~25℃空气质量良”。思考天气不错可以给出建议。回答适合出门但建议带上外套。ReAct 让 Agent 的决策过程变得可观测、可追踪这也是后续做日志和排查的基础。3.3 什么是 Function Calling工具调用Function Calling 是 OpenAI 等模型提供的一种结构化输出能力。开发者可以在一份tools参数中声明多个工具包括工具名称、描述、参数结构。模型在收到用户输入后会根据描述决定是否调用工具。下面是一个最小示例展示了如何声明一个获取当前时间的时间工具from openai import OpenAI client OpenAI( api_key你的 API Key, base_urlhttps://api.openai.com/v1 ) TOOLS [ { type: function, function: { name: get_current_time, description: 获取当前系统时间, parameters: { type: object, properties: {}, required: [] } } } ] resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 现在几点}], toolsTOOLS ) print(resp.choices[0].message)如果模型判断需要调用工具message.tool_calls里会包含工具名称和参数 JSON。我们拿到这个信息后在代码里执行真正的函数然后把结果以role: tool的消息传回给模型。3.4 记忆短期记忆、长期记忆与向量数据库Agent 记忆分为两类短期记忆指当前对话上下文。通常直接把多轮消息放进messages列表传给模型。缺点是上下文长度有限超过限制就需要做摘要或截断。长期记忆指跨会话保存的用户偏好、业务知识。常见方案包括数据库存储、向量数据库检索。RAG检索增强生成就是典型的长期记忆应用先把文档切分成小块向量化后存入向量数据库用户提问时先检索相似片段再作为上下文喂给模型。零基础阶段先理解“给模型更多相关上下文回答就会更准确”就够了。3.5 规划任务拆分与多智能体协作复杂任务比如“分析最近一周的线上日志并生成报告”靠一个简单的工具调用循环可能不够。这时需要 Agent 具备规划能力把任务拆成多个步骤查询日志索引列表。按时间范围过滤日志。统计错误关键词出现次数。生成分析报告。更复杂的场景会用到多智能体一个 Agent 负责任务调度多个子 Agent 分别负责查询、分析、写作。多智能体是进阶方向零基础阶段先把单 Agent 跑通更重要。3.6 低代码平台Dify 和 Coze 的工作流思路对于不想从零写代码的同学Dify 和 Coze 这类低代码平台是非常友好的选择。它们的核心思路是可视化的编排 Agent 工作流通常包含模型节点、知识检索节点、工具节点、条件判断节点、代码节点。在 Dify 中创建一个 Agent 应用基本路径是创建一个空白应用选择 Agent 类型。配置模型供应商的 API Key。编写系统提示词设定 Agent 的角色、目标、约束。添加工具比如内置工具或自定义 OpenAPI 工具。调试并发布应用。低代码平台适合快速验证想法也适合非开发人员使用。不过遇到复杂的业务逻辑、定制化数据流或性能要求很高的场景代码开发仍然更灵活。4. 完整实战从零实现一个可运行的 Agent下面我们动手写一个最小但完整的 Agent 示例。这个 Agent 可以调用三个工具查询当前时间、做简单的数学计算、查询订单状态。4.1 安装依赖在项目目录下创建虚拟环境并安装依赖pip install -r requirements.txt4.2 编写工具函数新建agent_demo.py先将工具函数写好。为了安全起见数学计算我们不用原生的eval而是用 Python 的ast模块做限制避免任意代码执行风险。import ast import operator import json import os from datetime import datetime from openai import OpenAI def get_current_time() - str: 获取当前系统时间 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) def safe_eval_expr(expr: str) - float: 安全解析数学表达式只允许数字、四则运算、幂和取模 allowed_operators { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Pow: operator.pow, ast.Mod: operator.mod, ast.USub: operator.neg, ast.UAdd: operator.pos, } def _parse(node): if isinstance(node, ast.Expression): return _parse(node.body) if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)): return node.value if isinstance(node, ast.BinOp) and type(node.op) in allowed_operators: left _parse(node.left) right _parse(node.right) return allowed_operators[type(node.op)](left, right) if isinstance(node, ast.UnaryOp) and type(node.op) in allowed_operators: return allowed_operators[type(node.op)](_parse(node.operand)) raise ValueError(不支持的表达式) return _parse(ast.parse(expr, modeeval)) def query_order_status(order_id: str) - str: 查询订单状态真实项目中可以替换成数据库或业务接口 mock_orders { 1001: 已发货预计明天送达, 1002: 支付成功待发货, 1003: 已取消, } return mock_orders.get(order_id, 未查询到该订单)这些工具函数有几个特点每个函数职责单一模型可以根据描述选择调用。函数返回的是字符串方便直接拼到模型上下文里。工具是普通 Python 函数后续替换成真实 API 也非常方便。4.3 注册 Agent 工具列表接下来定义tools参数让模型知道有哪些工具可用。TOOLS [ { type: function, function: { name: get_current_time, description: 获取当前系统时间比如用户问现在几点、今天日期时使用, parameters: { type: object, properties: {}, required: [] } } }, { type: function, function: { name: safe_eval_expr, description: 计算数学表达式比如加减乘除幂运算参数 expr 是一个数学表达式字符串, parameters: { type: object, properties: { expr: { type: string, description: 数学表达式例如 (12 6) * 3 } }, required: [expr] } } }, { type: function, function: { name: query_order_status, description: 根据订单号查询订单状态, parameters: { type: object, properties: { order_id: { type: string, description: 订单号 } }, required: [order_id] } } } ]工具描述非常关键。描述写得越清晰模型就越不容易选错工具。比如“现在几点”和“今天日期”都可以对应get_current_time描述里就要写清楚。4.4 编写 Agent 主循环下面是最核心的部分Agent 主循环。def run_agent(user_input: str, max_rounds: int 5): client OpenAI( api_keyos.getenv(OPENAI_API_KEY, 你的 API Key), base_urlos.getenv(OPENAI_BASE_URL, https://api.openai.com/v1) ) messages [ { role: system, content: 你是一个智能助手可以根据用户问题调用工具。请把工具返回的结果整理成清晰的中文回答。 }, {role: user, content: user_input} ] model os.getenv(AGENT_MODEL, gpt-4o-mini) for _ in range(max_rounds): resp client.chat.completions.create( modelmodel, messagesmessages, toolsTOOLS, ) choice resp.choices[0] message choice.message # 没有工具调用说明模型已经准备好最终回答 if not message.tool_calls: return message.content or # 把模型的工具调用请求加入上下文 dumped message.model_dump() messages.append({ role: dumped[role], content: dumped.get(content), tool_calls: dumped.get(tool_calls), }) # 执行每一个工具调用 for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments or {}) if tool_name get_current_time: result get_current_time() elif tool_name safe_eval_expr: try: result str(safe_eval_expr(tool_args.get(expr, ))) except Exception as e: result f计算失败: {e} elif tool_name query_order_status: result query_order_status(tool_args.get(order_id, )) else: result f未知工具: {tool_name} messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) # 循环继续让模型基于工具结果生成下一步 return messages[-1][content] if messages else 达到最大轮数未生成最终结果这段代码的逻辑可以这样理解把system和用户的输入拼成messages列表。调用模型传入tools。如果模型没有返回tool_calls说明已经可以生成最终答案直接返回。如果模型返回了工具调用就遍历每个调用执行对应的 Python 函数。把执行结果以role: tool的消息加回上下文。继续循环调用模型让模型基于工具结果继续推理。设置最大轮数防止 Agent 陷入死循环。4.5 运行示例在代码末尾加一段测试逻辑if __name__ __main__: test_input 请帮我计算 (12 6) * 3 的结果然后再看看订单 1001 的状态 print(run_agent(test_input))运行python agent_demo.py预期输出的效果类似(12 6) * 3 的结果是 54。 订单 1001 当前状态已发货预计明天送达。这里模型可能会分两步完成先调用一次工具计算表达式再调用一次工具查询订单。如果你的模型比较聪明也可能在一个循环里连续调用两个工具。无论哪种方式只要工具结果正确最终回答都是可靠的。4.6 进阶把 Elasticsearch 日志查询做成 Agent 工具很多公司会把日志写入 Elasticsearch想用自然语言查询日志也是一种高频需求。我们可以把这个能力封装成一个工具函数。注意这里的代码只是示例思路需要根据你的实际 ES 地址、索引名、认证方式调整。import requests def query_es_logs(index: str, keywords: str, size: int 10) - str: 通过 ES REST API 查询日志只读搜索接口。 es_url os.getenv(ES_URL, http://localhost:9200) es_user os.getenv(ES_USER, ) es_password os.getenv(ES_PASSWORD, ) url f{es_url}/{index}/_search body { query: { query_string: { query: keywords } }, size: size } auth None if es_user and es_password: auth (es_user, es_password) resp requests.post(url, jsonbody, authauth, timeout10) resp.raise_for_status() data resp.json() hits data.get(hits, {}).get(hits, []) return json.dumps([h[_source] for h in hits], ensure_asciiFalse, indent2)然后把这个函数注册到TOOLS列表里描述可以写成根据索引名和关键词查询 Elasticsearch 日志返回日志 JSON 列表。当用户需要排查日志、统计错误、分析线上问题时使用。安全方面要特别强调生产环境的 ES 不要直接暴露在公网查询账号应使用最小权限只授予只读索引权限禁止让 Agent 拥有删除索引或写入恶意数据的权限。所有的日志查询操作应在授权环境下进行并保留操作审计记录。5. 使用 Dify 快速搭建一个零代码 Agent对于不想一开始就写代码的同学Dify 是一个非常合适的入口。它把模型、工具、知识库、工作流都可视化可以快速验证业务想法。5.1 为什么零基础可以先从 Dify 入手我见过不少同学一上来就啃 LangChain 源码结果几天下来还在跟概念搏斗。低代码平台最大的价值是让你用最少的代码把 Agent 的完整链路跑一遍。你需要理解的概念并不多模型供应商Dify 里配置模型 API Key 的地方。应用类型Agent 和 ChatflowAgent 适合自由式对话Chatflow 适合固定流程。工具模型可以调用的外部能力。知识库上传文档后Dify 会自动做切片和向量化供模型检索。5.2 用 Dify 搭建一个 Agent 应用的大致步骤Dify 的界面可能随时调整但核心步骤是稳定的进入 Dify 控制台创建空白应用应用类型选择“Agent”。在“模型供应商”中配置 API Key 和模型名称。在“编排”页面编写系统提示词。提示词里可以指定角色、业务目标、禁止事项。添加工具。Dify 内置了一些常见工具也支持自定义 OpenAPI Schema 工具。开启模型调试在右侧对话框测试。发布应用拿到 API 访问地址或嵌入页面代码。举个例子如果你想做一个“上传文件后自动提取内容并总结”的智能体可以在知识库中先上传示例文件然后在工作流里添加“文档提取”节点把提取结果传给 LLM 节点做总结。这个流程本身不复杂关键是把每个节点的输入输出接对。5.3 低代码平台的局限低代码平台虽然上手快但也要知道它的边界业务逻辑非常复杂时可视化节点会变得臃肿难维护。高并发调用时平台自带服务可能成为瓶颈而且按调用量计费成本需要评估。需要深度对接公司内部系统时往往还是要写自定义工具或代码节点。模型行为评估、灰度发布、AB 测试等能力平台不一定全部具备。所以比较合理的学习路线是先用 Dify 跑通第一个 Agent 应用理解流程再回到代码学习掌握更深层的控制能力。6. 常见问题与排查思路学习 Agent 开发的过程中报错是家常便饭。这里整理一些高频问题方便你快速对照排查。问题现象常见原因解决思路调用 API 返回 401 或 403API Key 错误、没有权限、账号欠费检查环境变量或配置文件中的 Key确认模型服务是否可用提示 model 不存在模型名称写错或当前服务商不支持该模型在模型服务商的控制台查看可用模型列表模型不调用工具直接回答问题tools 参数没有传对或工具描述不够清晰检查 tools 参数结构把工具描述写得更具体并给出使用示例工具调用后拿不到结果工具函数抛异常或者 tool_call.id 没正确回传打印工具执行日志确认函数返回类型是字符串检查 messages 里 tool 消息是否带 tool_call_id模型输出反复调用同一个工具形成死循环工具结果没有让模型得到足够信息或最大轮数没有限制增加 max_rounds 限制检查工具返回内容是否足够在提示词中要求模型避免重复调用上下文超长多轮对话或工具结果太长超过模型上下文限制截断历史消息对长文本做摘要使用向量检索只带回相关片段Dify 中配置模型后不生效模型供应商配置保存失败或应用级别未重新获取配置到模型供应商页面重新测试连接刷新编排页面后重试排查问题最有效的方法是加日志。在工具调用前后打印出工具名称、参数、返回结果大部分问题都能一眼看出来。print(f[Agent] 调用工具: {tool_name}, 参数: {tool_args}) print(f[Agent] 工具返回: {result})7. 最佳实践与工程化建议7.1 工具设计原则工具的职责要单一。一个工具只做一件事情命名要能直接体现用途描述要写清使用场景和参数含义。工具返回内容尽量精简不要一次性把几千条数据全部丢给模型否则既浪费 token又可能让模型抓不住重点。必要的时候在工具内部先做聚合统计只返回结论和少量明细。7.2 提示词管理系统提示词会影响 Agent 的行为边界。建议在提示词里明确这些内容你是谁面向什么业务。你的目标是什么。哪些事情不做。使用工具时需要注意什么。输出格式要求比如必须用中文、必须带上数据来源。提示词可以当成一份长期维护的配置建议放到独立的.md或.yaml文件中不要直接硬编码在业务代码里。7.3 安全性Agent 开发最容易被忽视的就是安全。需要重点关注这几个方面API Key 一律使用环境变量或密钥管理服务保存禁止提交到 Git 仓库。工具函数要对用户输入做校验尤其是涉及文件路径、表达式、SQL、命令执行的场景避免注入风险。涉及数据库或 ES 的操作使用最小权限账号只授予只读权限并且限定允许访问的索引或表。涉及生产环境变更必须先经过测试环境验证、流程审批和备份。记录完整的操作审计日志一旦出现问题可以追溯。上面的日志查询 Agent 就是一个典型例子查询工具本身是只读的但如果你不小心把 ES 地址和密钥写进前端页面或者账号权限过大风险就随之而来。7.4 可观测性与评估Agent 是一个多步骤的系统任何一个环节出错都会影响最终结果。建议在项目早期就建立日志体系每次用户请求生成一个 request_id。记录模型的输入输出、tool_calls、工具执行耗时和结果。记录失败原因分类统计失败率。建立固定的评估测试集比如 50 条典型用户问题每次修改提示词或工具逻辑后统一回归测试。有了评估集之后你才能知道“这次修改到底让效果变好了还是变差了”而不是靠感觉调参。8. 总结与下一步学习方向这篇文章从概念开始介绍了 AI Agent 是什么、由哪些模块组成然后从零实现了一个可以调用多个工具的 Agent最后介绍了 Dify 低代码平台的使用思路以及常见问题和工程化建议。如果看完之后只能记住一句话我希望是Agent 的核心不是堆砌代码而是设计好大模型的决策边界和工具的执行效率。大模型负责“想”工具负责“做”把这两部分设计清楚Agent 的可靠性就会大幅提升。接下来你可以继续学习这几个方向RAG 深入掌握文本切分、向量化、检索排序做一个真正的企业知识库问答 Agent。多智能体编排学习如何让多个 Agent 协作处理复杂任务。Prompt 工程提升模型对工具和输出的控制精度。LangChain / LlamaIndex了解主流框架的设计思想但不要盲目依赖框架先把底层原理搞清楚。模型本地化部署学习 Ollama 等工具了解如何在没有外网条件下使用开源模型。如果你能把这个最小 Agent 跑起来恭喜你已经跨过 AI Agent 开发的第一道门槛。后面无非是在记忆、工具、编排方式上做加法。希望这篇文章能帮你省掉一些查资料的弯路也欢迎在学习过程中把你遇到的具体报错整理出来带着报错信息去排查往往进步最快。