# Dify 智能体教程：添加工具、发布，再用代码调用 > Dify 的智能体应用是一个聊天应用，由模型决定用哪些工具。你写好提示词，添加网页搜索这类工具，需要的话再关联知识库，测试后发布。发布之后，你会得到网页应用链接、嵌入组件、带密钥的 API 和一个 MCP 服务器，Logs 标签页则显示人们怎样使用它。 Mindket 编辑部 · 发布于 2026-11-06 · 更新于 2026-11-06 · https://mindket.com/cn/learn/dify/dify-agent ## 要点 - 在提示词里写明每个工具的名字和适用的场合，因为调用什么由模型决定。 - 选原生支持工具调用的模型，并看一眼 Agent Settings 显示的模式。 - API 密钥只放在你的服务器上，给每个人传不同的 user 值。 - 上线之后看日志，把反复出现的弱回答变成标注。 ## Dify 里的两种智能体 智能体应用是一个聊天应用：模型自己推理任务、决定下一步做什么，需要时调用工具。你想让模型自己选做法、不用固定的步骤流程时，就用它。文档里的例子是一个数据分析助手，它会获取实时数据、画图表，并总结发现。这个词如果还陌生，[什么是 AI 智能体](https://mindket.com/cn/learn/prompt-engineering/what-is-an-ai-agent)有解释。 Dify 现在有两种。Studio 里的 Agent 应用在文档里带着 Legacy（旧版）标签。新版 Agent 还在测试阶段，在自己的沙箱里工作。这一课搭的是旧版应用，因为它的页面把每个设置都讲了一遍，最后一节再讲新版。 | 对比项 | 旧版 Agent 应用 | 新版 Agent（测试中） | | --- | --- | --- | | 状态 | 文档里标为 Legacy | 测试版，在 Docker Compose 上默认开启 | | 怎样行动 | 模型推理，并调用你添加的 Dify 工具 | 在自己的沙箱里工作：运行命令、安装程序、读写文件 | | 你给它什么 | 提示词、Dify 工具和知识库 | 提示词、技能、文件、工具、知识检索和环境变量 | | 怎样使用 | 作为聊天应用 | 单独作为聊天应用，或作为工作流里的一个步骤 | ## 写提示词 提示词告诉模型做什么、怎样回答、要遵守哪些规则。对智能体来说，它还引导模型怎样推理、什么时候去用工具，所以要把你期望的工作流程写清楚。文档列出五个要点：定义角色，指定输出格式，设置约束，按名字提到工具并说明什么时候用，把复杂任务拆成步骤。 变量让一个智能体适应很多用户。变量是提示词里的占位符，会显示成一个输入框，运行时它的值会被填进去。起草时输入 `/`，选“New Variable”。类型有 Short Text（最多 256 个字符）、Paragraph、Select、Number、Checkbox 和 API-based Variable，最后一种在运行时从外部 API 取值。不知道从哪里开始，可以点“Generate”按钮，让模型起草提示词，每次生成都会存成一个版本。下面是文档里带 domain 变量的例子。 ````text You are a data analyst specializing in {{domain}}. Help users explore and understand their data. When asked a question, use available data tools to fetch the relevant information. If the result suits a visual format, generate a chart. Explain your findings in plain language. Keep responses concise. If a question is ambiguous, ask for clarification before fetching data. ```` ## 添加工具和知识库 工具让模型不只会处理文字：获取实时数据、搜索网页、查询数据库。每次查询用不用工具、用哪个，由模型决定，所以要在提示词里写出工具名，并说明适用的场合。工具在“Integrations”>“Tools”下管理。需要认证的工具，可以用已有的凭据，也可以新建一个。Dify 还能导入 MCP 服务器的工具，MCP 是向 AI 应用提供工具的标准方式，[什么是 MCP](https://mindket.com/cn/blog/what-is-mcp)有解释。[工具那一课](https://mindket.com/cn/learn/harness-engineering/tools-for-ai-agents)讲了怎样的工具对智能体好用。 Agent Settings 里的“Maximum Iterations”限制模型对一个请求最多重复多少次“思考、调用工具、读取结果”的循环。多步骤的任务可以调高，但延迟和 token 成本也会增加。 想让回答建立在你自己的数据上，就添加知识库。模型会读每个知识库的描述，再决定要不要检索，所以提示词里不用提它，描述写得越详细，检索越准。Agent 应用没有应用级的检索设置，每个知识库用自己的设置，关联多个时，由智能体挑要查询哪一个，不会跨知识库重排序。[第 3 课](https://mindket.com/cn/learn/dify/dify-knowledge-base)搭了一个。 选模型要谨慎。文档推荐推理能力强、原生支持工具调用的模型，因为智能体要判断什么时候用工具、哪个工具合适、怎样读取结果。Agent Settings 对原生支持的模型显示 Function Calling，对其余的显示 ReAct，由 Dify 用提示词来引导工具的使用。 1. 在 Studio 里创建一个 Agent 应用。 2. 粘贴上面的提示词，再输入 `/`，选“New Variable”创建 `domain`。 3. 添加任务需要的工具。某个工具要求认证时，选一个凭据，或新建一个。 4. 答案必须来自你的数据时，添加知识库，并把它的描述写详细。 5. 打开 Agent Settings，看它显示的是 Function Calling 还是 ReAct，并设置 Maximum Iterations。 6. 在“Debug & Preview”里选一个模型开始对话。“Debug as Multiple Models”最多同时对比 4 个模型。 7. 点“Publish”。 | 工具类型 | 它带来什么 | 文档里的说明 | | --- | --- | --- | | Tool Plugin | Dify 和社区提供的现成工具，从 Marketplace 安装 | 有些要先配凭据，比如 Google 和 GitHub。Current Time 这类内置工具开箱即用 | | Swagger API | 没有插件的服务，通过它的 OpenAPI 规范导入 | 粘贴模式，或从网址导入，也可以从自带示例开始 | | Workflow | 以 User Input 节点开头的工作流，发布成工具 | 点“Publish”>“Workflow as Tool”。Chatflow 不能当工具用 | | MCP | 已连接的 MCP 服务器的工具 | 只支持使用 HTTP 传输的服务器 | ## 发布成网页应用、嵌入组件或 MCP 服务器 点“Publish”，Dify 就会根据你最新的配置创建一个网页应用和一个 API 端点。网页应用的链接在应用的“Access Point”标签页上。网页应用默认是公开的，所以任何拿到网址的人都能打开，用认证来限制访问是 Dify 企业版的功能。发布会替换线上的应用，用户在下一次互动时就会看到变化。 分享之前，先设置应用的名称、描述和图标，描述要控制在 160 个字符以内。聊天类应用，比如 Agent 应用，还可以放一段你自己写的输入框提示，最多 64 个字符。 要把网页应用放到你自己的网站上，打开“Access Point”标签页，在“Web App”卡片上点“Embed Into Site”，找到你的令牌。聊天气泡是一个悬浮按钮，通过 `window.difyChatbotConfig` 配置，iframe 则把应用显示在页面里。两者显示的都是已发布的网页应用，所以改动之后要重新发布。下面这段 iframe 代码来自文档。 同一个标签页上的“MCP Server”卡片默认是关闭的。打开后会生成一个服务器地址，Claude Desktop、Cursor 这类工具可以添加它。这个地址里含有凭据，要像对待 API 密钥一样对待它，泄露了就用重新生成按钮。 ````html ```` | 如果你想要 | 用 | 文档里的说明 | | --- | --- | --- | | 尽快得到用户反馈 | 网页应用 | 分享链接，几分钟内就能开始收集反馈 | | 把 AI 放进你自己的产品 | API | 界面、用户认证和数据处理都由你控制 | | 在已有网站上放聊天组件 | 嵌入 | 聊天气泡或内嵌框架，适用于任何网站技术 | | 让 AI 工具用上你的应用 | MCP 服务器 | Claude Desktop、Cursor 和其他 AI 开发环境都能使用 | ## 用代码调用智能体 你发布的每个应用同时也是一个 REST API，用 API 密钥从你自己的后端调用。密钥在应用内部创建，只对这一个应用有效，一个密钥服务所有终端用户，用每个人不同的 `user` 值来区分他们。只能从后端调用 API，因为放在前端代码或客户端应用里的密钥可能被提取并滥用。 在 Dify Cloud 上，基础网址是 `https://api.dify.ai/v1`，自托管的安装用自己的 API 基础网址。大多数请求把密钥放在 Bearer 令牌里。下面的第一个调用会返回应用的名称、描述、标签、作者和 `mode`。mode 决定该看哪份指南：Chatbot 或旧版 Agent 应用是 `chat` 或 `agent-chat`，新版 Agent 是 `agent`，Chatflow 是 `advanced-chat`，Workflow 是 `workflow`，Text Generator 是 `completion`。 旧版 Agent 应用只支持流式模式，它流式返回 `agent_thought` 和 `agent_message` 事件。新版 Agent 的 API 同样只支持流式，阻塞式请求会返回 400 错误。 ````bash curl https://api.dify.ai/v1/info \ -H "Authorization: Bearer $DIFY_API_KEY" ```` 1. 打开已发布的应用，在应用内部创建一个 API 密钥。 2. 把密钥作为 `DIFY_API_KEY` 存在你的服务器上。 3. 在服务器上运行上面的调用。文档展示的响应会给出应用名称和它的 mode。 4. 打开这个 mode 对应的指南，发送你的第一条聊天消息。 ## 查看日志 Logs 标签页显示一个应用真实的使用情况。聊天类应用，包括 Agent 应用，记录的是对话。它会记录网页应用、API，以及从 Home 页“WEB APPS”列表里打开的应用。编辑器里的测试会话，在 Chatflow 和 Workflow 应用里不记录，其他类型的应用会记录，列在团队成员的账号下面。 点一行就能打开整个对话。把鼠标移到某条回答上，可以看到它的 token 消耗和延迟，可以打开它背后的日志，对 Agent 应用来说里面有原始提示词和工具调用的每一轮，也可以给它评分。User Rate 统计终端用户的点赞和点踩，Op. Rate 统计你团队的。 日志里是完整的对话，所以在法律有要求的地方，要发布隐私政策。日志默认无限期保留。要清理对话消息，把 `ENABLE_CLEAN_MESSAGES` 设为 true，再用 `SANDBOX_EXPIRED_RECORDS_RETENTION_DAYS` 设置保留的天数，默认是 30。删除对话或旧日志，并不会删除用户上传的文件。 ## 标注：已知问题用你的答案 标注把一个问题和你想要的回复配成一对。打开标注回复后，Dify 会为每个问题搜索语义匹配的标注。匹配度超过相似度阈值，就返回你写好的回复，否则走正常的生成流程。 在“Orchestrate”>“Add Features”下打开它，再选相似度阈值和嵌入模型。阈值越高，要求匹配得越接近，更换嵌入模型会重新生成所有嵌入。创建标注的方式有：在日志或调试模式里把一条回答改成你想要的，用模板批量导入，或者在“Annotations”里手动添加。命中跟踪会显示哪些标注被用到了。总是错过你标注的问题，说明还有空白没覆盖。 ## 新版 Agent（测试中） 在“Agents”页面用“Create”>“Create from Blank”创建，填一个名称，还可以加上角色和描述。其余都在“Configure”里设置：模型、提示词、技能、文件、工具、知识检索和环境变量。技能是一个包含 `SKILL.md` 文件的包，用来教智能体一套做法。一个智能体最多可以加 20 个库技能，技能包默认最大 50 MB。 Build mode（构建模式）让你用聊天描述智能体，看它自己填好提示词、技能、文件和环境变量。点“Apply”保留这些改动，点“Discard”丢弃，两种选择都会结束构建模式。第一次 Apply 会在“Files”里生成一个 `build_note.md`，记录智能体设置了什么。 智能体可以单独作为聊天应用使用，你可以把它发布成网页应用，或者通过服务 API 调用；也可以放进工作流，由 Agent 节点交给它一个步骤。两种情况下，它的会话都汇总在 Logs 页面。 社区版的智能体运行环境，并不是为了在互不信任的用户或工作负载之间提供加固的安全边界。用于生产时，要把 `DIFY_AGENT_SERVER_SECRET_KEY` 和 `DIFY_AGENT_API_TOKEN` 换成你自己的随机值。[护栏那一课](https://mindket.com/cn/learn/harness-engineering/agent-guardrails)讲了沙箱和权限的通用做法。 **文档写明的智能体限制** - **2,000 个 token** 的历史，或 500 条消息，旧版 Agent 应用保留这么多 (来源：[Dify 文档（GitHub）：Agent（旧版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/agent.mdx), 2026-11-06 查阅) - **1 小时** 新版 Agent 一次运行默认的停止时间 (来源：[Dify 文档（GitHub）：Agent（新版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx), 2026-11-06 查阅) - **500** 新版 Agent 每次运行默认允许的模型调用次数 (来源：[Dify 文档（GitHub）：Agent（新版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx), 2026-11-06 查阅) - **50 MB** 智能体在回复里发回的每个文件的默认上限 (来源：[Dify 文档（GitHub）：Agent（新版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx), 2026-11-06 查阅) ## 常见错误 - 提示词里不提工具。文档建议写出每个工具的名字，并说明什么时候用。 - 选了不原生支持工具调用的模型。文档说，内置工具调用支持的模型执行这些决定更可靠，Agent Settings 会显示你得到的是哪种模式。 - 没有理由就调高 Maximum Iterations。值越高，延迟和 token 成本越高。 - 在前端代码里调用 API，密钥可能被提取并滥用。 - 改了应用却忘了重新发布。网页应用和嵌入组件只显示已发布的版本。 - 分享了网页应用链接，却以为它是私密的。 - 把 MCP 服务器地址贴到公开的聊天或代码仓库里，它含有凭据。 ## 自己试一试 - 问智能体一个需要用工具的问题，再打开这条回答的日志，看工具调用的每一轮。 - 改一下 `domain` 的值，再问同一个问题。 - 把一条回答改成你更想给出的回复，存成标注。打开标注回复，再问一个类似的问题。 ## 下一门课：浏览器智能体 Dify 的智能体调用你给它的工具。下一门课是[浏览器智能体](https://mindket.com/cn/learn/ai-browser-agents/what-are-browser-agents)：替你点击、输入和浏览的 AI。 ## 自测一下 1. 在旧版 Agent 应用里，哪个设置限制模型对一个请求最多运行多少轮“思考、调用工具、读取结果”的循环？ A. Score Threshold B. Debug as Multiple Models C. Maximum Iterations D. Input Placeholder 答案：C。 旧版 Agent 页面说，Agent Settings 里的 Maximum Iterations 限制模型对单个请求最多重复这个循环多少次。 2. 已发布的 Dify 应用的 API 密钥应该在哪里使用？ A. 网页的 JavaScript 里 B. 嵌入令牌里 C. MCP 服务器地址里 D. 只在你的后端 答案：D。 API 指南说只能从后端调用 API，因为放在前端代码或客户端应用里的密钥可能被提取并滥用。 3. 你的智能体网页应用已经嵌入网站。你改了它的提示词，但没有点“Publish”。访客看到的是哪个版本？ A. 已发布的版本，不含你的改动 B. 改过的提示词，马上生效 C. 在你重新发布之前显示错误页面 D. 你最后一次预览的版本 答案：A。 嵌入页面说所有嵌入方式用的都是已发布的网页应用，发布页说，点“Publish”才会用当前的配置替换线上的应用。没有发布的改动不属于线上的应用。 4. 打开标注回复后，一个问题与某条标注的匹配度超过相似度阈值，会发生什么？ A. 模型根据你的答案重新训练 B. Dify 返回你写好的回复，而不是重新生成 C. 日志条目被删除 D. Maximum Iterations 增加 答案：B。 标注系统页面说，匹配度超过相似度阈值就返回写好的回复，没有匹配则走正常生成。 ## 常见问题 ### Dify 里的智能体和工作流有什么区别？ 工作流按你连好的节点，依你定的顺序执行。智能体拿到的是工具和目标，由模型决定下一步做什么，更灵活，也更难预测。工作流适合可重复的步骤，智能体适合开放式的工作。 ### 能让 Dify 的网页应用变成私有的吗？ 文档把访问控制列为 Dify 企业版的功能：认证、成员级访问和外部用户管理。在其他版本里，要把这个链接当成谁收到谁就能打开的。 ### 嵌入的 Dify 聊天机器人为什么没有出现？ 聊天气泡的话，检查令牌是否和“Embed Into Site”下的一致，配置是否在嵌入脚本之前加载，浏览器控制台里有没有 JavaScript 错误。iframe 的话，检查网址里的令牌，以及你网站的内容安全策略。文档还建议你的网站和 Dify 都用 HTTPS。 ### 能在 Claude Desktop 或 Cursor 里用 Dify 应用吗？ 可以。在应用的“Access Point”标签页里打开“MCP Server”，Dify 会为它生成一个地址。Cursor 从 .cursor/mcp.json 的 mcpServers 对象里读取它，Claude Desktop 则在“Profile”>“Settings”>“Integrations”下把它添加为集成。 ### Dify 会保存我用户的对话吗？ Logs 标签页会保存，并带有 token 消耗、延迟和评分，除非你设置清理变量，否则保留期限不限。用户上传的文件，即使你删除了对话也还在。 ## 资料来源 - [Dify 文档（GitHub）：Agent（旧版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/agent.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Agent（新版）概览](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/overview.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Agent（新版）](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Dify 工具](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/workspace/tools.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：发布概览](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/README.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：嵌入网页应用](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/webapp/embedding-in-websites.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：网页应用设置](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/webapp/web-app-settings.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：MCP 服务器](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/publish/publish-mcp.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Dify API 入门](https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/get-started.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Agent API 指南](https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/agent.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：Chatbot 与旧版 Agent 的 API 指南](https://github.com/langgenius/dify-docs/blob/main/en/api-reference/guides/chat.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：日志](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/monitor/logs.mdx) (2026-11-06 查阅) - [Dify 文档（GitHub）：标注系统](https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/monitor/annotation-reply.mdx) (2026-11-06 查阅) [浏览 Kits](https://mindket.com/cn/kits)