Dify手搓AIAgent全流程：从零搭建到避坑实战，小白也能轻松上手！

1. 先搞清楚 Dify 里的 AIAgent 到底在干什么很多人第一次打开 Dify 的工作流画布看到开始、LLM、知识库、条件分支这些节点会觉得“这不就是个流程图工具吗”。但当你真正想做一个能自己判断、自己调工具、自己决定下一步的 AIAgent 时问题就来了模型怎么知道该调用哪个工具调用完结果怎么回到对话里多个工具之间怎么串起来Dify 给出的答案是 Agent 节点 FunctionCalling 策略 MCP 工具接入。简单说Agent 节点负责“思考”FunctionCalling 策略负责“决定调哪个工具”MCP 负责“把外部能力接进来”。三者配合你就能在 Dify 里手搓出一个能查地图、查天气、查数据库的 AIAgent。这篇内容面向零基础开发者从工作流编排讲到 MCP 接入再给出可复制的配置骨架和统一 Key/API 通道的 settings.json 示例。你不需要先精通大模型原理跟着步骤走就能跑通第一个 Agent 应用。2. TaoToken 前置统一 Key 与 API 通道准备在 Dify 里驱动 Agent 的模型需要 API Key。如果你同时用多个模型供应商每个都去申请 Key、配环境变量、改 base_url维护成本会很高。我自己的做法是用 TaoToken 做统一通道一个 Key 走多个模型Dify 里只需要填一次。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接填到 Dify 的模型配置里即可。你需要先拿到 API Key。进入控制台创建 Key 的路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完成后复制以 sk- 开头的字符串。这个 Key 后面会同时用在 Dify 模型配置和本地 settings.json 里。如果你只是想在 Dify 里快速验证模型能不能通可以先用模型对话页面发一条消息测试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认返回正常后再回到 Dify 配置。注意Dify 的模型供应商配置里OpenAI-API-compatible 类型的 base_url 填 https://taotoken.net/api 不要带末尾斜杠也不要带 UTM 参数。3. 可复制配置Dify 工作流 MCP settings.json3.1 工作流骨架开始 → Agent → 结束先建一个最简单的三节点工作流。开始节点接收用户输入Agent 节点做策略决策结束节点输出结果。这个骨架和 excerpt 里的案例结构一致但我会把每个配置项讲清楚。开始节点只需要一个变量比如 user_query类型选文本。Agent 节点的配置是核心逐项说明模型选择在 Dify 模型供应商里选 OpenAI-API-compatiblebase_url 填 https://taotoken.net/api API Key 填刚才创建的 sk- 字符串模型名填你实际要用的比如 qwen 系列或 claude 系列。保存后 Dify 会做一次连通性校验。工具配置点击 Agent 节点里的“”添加工具。如果你已经配好了 MCP 服务这里会列出 MCP 提供的工具函数。没有配 MCP 的话也可以先用 Dify 内置工具测试。指令配置用 Jinja 语法引用上游变量。比如你是一个出行规划助手。用户的问题是{{#start.user_query#}} 请先解析地点坐标再规划路线最后用简洁中文输出换乘方案。查询配置填 {{#start.user_query#}}把用户输入传给 Agent。最大迭代次数默认 5 到 10 都可以。太小会导致工具没调完就停太大可能循环。建议先设 8。输出变量如果结束节点只需要文本保持默认即可。需要结构化输出时再定义 JSON schema。结束节点引用 Agent 输出的 text 字段。3.2 MCP 工具接入的关键参数MCP 接入在 Dify 里通常通过插件或外部服务配置。以高德 MCP 为例你需要拿到 MCP 服务的 SSE 地址或 stdio 启动命令。Dify 的 MCP 配置界面里填{ mcpServers: { amap: { url: 你的 MCP SSE 地址, transport: sse } } }配置完成后Agent 节点的工具列表里会出现 maps_geo、maps_direction_transit_integrated 等函数。如果工具列表是空的说明 MCP 服务没连上先检查地址和网络。3.3 settings.json 统一通道示例如果你在本地用 Claude Code 或其他支持 settings.json 的工具可以把 TaoToken 作为统一通道写进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这个配置的作用是让本地工具走同一个 API 通道和 Dify 里用的 Key 保持一致。换模型时只改 ANTHROPIC_MODEL 字段不用重新申请 Key。如果你需要长期跑编码类 Agent可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要稳定调用、多模型切换的场景。4. 验证请求从输入到工具调用的完整链路配置完成后在 Dify 预览窗口输入一条测试问题比如“佛山千灯湖地铁站到磨碟沙地铁站怎么走”。点击运行后观察 Agent 节点的执行记录。正常情况下你会看到类似这样的调用链第一次调用 maps_geo参数是“佛山千灯湖地铁站”返回坐标和城市“佛山”。第二次调用 maps_geo参数是“磨碟沙地铁站”返回坐标和城市“广州”。第三次调用 maps_direction_transit_integrated输入两组坐标和城市返回换乘方案。最后 Agent 整合结果输出“先乘广佛线至西塱站换乘广州 8 号线至磨碟沙站全程约 55 分钟”。如果你在本地用 curl 验证 TaoToken 通道是否通可以这样请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 你好}] }返回 200 且 body 里有 choices 字段说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多写了路径。5. 本篇常见错排查5.1 Agent 节点报“模型不可用”最常见的原因是 base_url 填错。Dify 的 OpenAI-API-compatible 配置里base_url 应该是 https://taotoken.net/api 不要写成 https://taotoken.net/api/v1 。Dify 会自动拼接 /v1/chat/completions。多写一层路径会导致 404。另一个原因是模型名不在 TaoToken 支持的列表里。先去模型对话页面确认可用模型名再填到 Dify。5.2 MCP 工具列表为空先确认 MCP 服务本身是否启动。如果是 SSE 方式用浏览器或 curl 访问 SSE 地址看是否有 event stream 返回。如果是 stdio 方式检查启动命令的路径和权限。Dify 侧检查插件版本。Agent 策略插件需要从插件市场安装最新版旧版本可能不识别 MCP 工具。安装地址在 Dify 插件市场搜索“Agent 策略”即可。5.3 Agent 循环调用同一个工具把最大迭代次数调小比如从 10 降到 5。同时在指令里明确“如果已经获取到坐标不要重复调用 maps_geo”。FunctionCalling 策略依赖模型判断指令写得越具体循环概率越低。5.4 结束节点拿不到输出检查结束节点的变量引用是否指向 Agent 节点的输出字段。如果 Agent 输出变量名是 text结束节点就引用 {{#agent.text#}}。变量名不匹配会得到空值。5.5 settings.json 不生效本地工具的 settings.json 路径因工具而异。Claude Code 通常在用户目录下的 .claude/settings.json。改完后重启工具让环境变量重新加载。如果仍然不生效检查 JSON 格式是否合法逗号、引号是否写错。6. 继续搭建你的下一个 Agent跑通这个三节点工作流之后你可以往里面加更多东西。比如在开始节点后面加一个知识库检索节点让 Agent 先查文档再调工具或者在结束节点前加一个条件分支根据 Agent 输出决定走人工审核还是直接返回。Dify 的 Agent 策略插件和 MCP 工具生态还在快速迭代。我自己的习惯是每配一个新工具先用最小工作流验证工具本身能不能调通再把它塞进复杂流程里。这样出问题时排查范围小不会一上来就面对十几个节点互相甩锅。如果你在配置 Dify 模型时遇到 Key 或通道问题可以直接去 API Keys 页面重新生成一个 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的请求示例。Claude Code 相关的配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。先把一个能跑通的 Agent 跑起来比读十篇架构文章都有用。