> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建 Agent

> 创建 Agent 并塑造它的能力，可逐项手动配置，也可通过描述需求来构建

> [!NOTE]
>
> 新 Agent 目前处于 Beta 阶段。使用前需在集群中启用 agent-backend 与沙箱环境，部署方法见 [Agent Sandbox 部署](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/agent-sandbox.md)。
>
> 生产环境使用前，在 Helm values 中将 `agentBackend.serverSecretKey` 替换为你自己的随机值。

## 创建 Agent

在 **Agents** 页面点击 **创建** > **创建空白应用**，为 Agent 取名，也可选填角色（如「研究助理」）和描述。其余一切都在 **配置** 中完成。

若要通过共享的 DSL 文件创建 Agent，选择 **导入 DSL 文件**。工作空间的 [Skill 库](https://enterprise-docs.dify.ai/zh/3.13.x/use/build/skills.md) 中若有同名 Skill，会自动重新关联；内嵌 Skill 和文件不随 DSL 传递，导入后需自行添加。

> [!NOTE]
>
> **创建** 需要 **创建 Agent** 权限，**导入 DSL 文件** 需要 **导入与导出 Agent DSL** 权限。
>
> 所有者、管理者和编辑者默认同时持有这两项权限，其他成员可通过 [自定义角色](https://enterprise-docs.dify.ai/zh/3.13.x/use/workspace/roles-and-permissions#自定义角色) 获得。

## 配置能力

可逐项手动设置能力，也可进入 [构建模式](#build-by-chatting)，通过对话描述需求来构建。

你在 **配置** 中设置的一切都会保存为 Agent 的能力，供之后的每个任务使用。另外，Agent 在自己的沙箱中工作，过程中随时运行命令、处理文件。

Agent 的能力只能在这里修改：即使终端用户要求已发布的 Agent 更改自己的提示词、Skill 或工具，它也不会照做。

### 模型

选择 Agent 运行的对话模型。优先选推理能力强、原生支持工具调用的模型，因为 Agent 要自行判断何时行动、哪个工具合适、如何解读结果。

> [!NOTE]
>
> Agent 表现好不好，很大程度取决于模型，尽量选较新的模型。
>
> 旧模型可能用不好沙箱：常见的表现是 Agent 始终不去运行命令或安装工具，即使任务需要也不动手。

### 提示词

在提示词中设定 Agent 的角色和工作方式。具体说明它应如何推理、何时借助工具，以及要避免什么。

以下几点值得写进去：

* **角色与目标**：Agent 以什么身份行动，要达成什么。
* **工作方法**：处理典型任务时期望的步骤或顺序。
* **工具与文件的使用**：点名说明各自何时使用。
* **输出**：期望的格式、长度或语气。

你可将 Agent 指向特定的 Skill、文件或工具，也可把选择权留给它：

* **在提示词中引用**：输入 `/` 引用，Agent 会在你指定的位置直接用上它。适合某个步骤依赖特定资源的场景。
* **只添加不引用**：把它加到对应区域，何时使用由 Agent 自行决定。适合你更愿意相信 Agent 的判断、不想事事写死的场景。

### Skill

Skill 是 Agent 针对某项特定任务遵循的一套流程。提示词设定 Agent 的整体角色，而 Skill 只负责这一项任务。

例如，客服 Agent 的提示词可把它设定为处理各类问题的客服助手，而 `refund-requests` Skill 只处理退款：查询订单、仅处理 30 天内的退款，并在最后提供帮助中心链接。

点击 **添加**，再选择要添加哪一类 Skill：

* 选择 **从 Skill 库添加**，添加工作空间内共享的 [Skill 库中的 Skill](https://enterprise-docs.dify.ai/zh/3.13.x/use/build/skills.md)。每个 Agent 最多可添加 20 个此类 Skill，并会采用各 Skill 的最新发布版本。

* 选择 **上传 skill.zip**，将 `.zip` 或 `.skill` 包作为内嵌 Skill 添加给 Agent。内嵌 Skill 只属于该 Agent。

  包内需有 `SKILL.md`，大小默认不超过 50 MB，可通过 [`UPLOAD_SKILL_FILE_SIZE_LIMIT`](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables#upload_skill_file_size_limit) 调整。

  要与其他 Agent 共享内嵌 Skill，可 [将它加入 Skill 库](https://enterprise-docs.dify.ai/zh/3.13.x/use/build/skills.md#导入-skill)。

你也可在 [构建模式](#build-by-chatting) 中让 Agent 替你创建内嵌 Skill。

> [!TIP]
>
> 要让某个 Dify 工具或文件成为 Agent 自身能力的一部分，请将其直接添加给 Agent，而不是放进 Skill 包。

### 文件

文件是 Agent 工作时可查阅的参考文档，如规格说明、模板或指南。与 Skill 不同，文件只是供阅读的材料，不是可执行的流程。

大小上限按文件类型区分，均为默认值，可在 [环境变量](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables.md) 中调整：

| 文件类型 | 默认上限 | 环境变量 |
| :- | :- | :- |
| 文档 | 15 MB | `UPLOAD_FILE_SIZE_LIMIT` |
| 图片 | 10 MB | `UPLOAD_IMAGE_FILE_SIZE_LIMIT` |
| 视频 | 100 MB | `UPLOAD_VIDEO_FILE_SIZE_LIMIT` |
| 音频 | 50 MB | `UPLOAD_AUDIO_FILE_SIZE_LIMIT` |

你也可在 [构建模式](#build-by-chatting) 中让 Agent 创建文件并保存到这里。

> [!NOTE]
>
> Agent 创建并保存的文件，单个默认不超过 50 MB，可通过 `DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` 调整。详见 [环境变量](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-配置)。

### 工具

为 Agent 添加 [Dify 工具](https://enterprise-docs.dify.ai/zh/3.13.x/use/workspace/tools)，让它能在聊天之外采取行动：包括工作空间中的插件、自定义 API、工作流和 MCP 服务器。部分工具需先认证才能使用。

> [!TIP]
>
> 除了你在这里添加的 Dify 工具，Agent 需要时还能在沙箱内自行安装并运行命令行工具。这类工具不会出现在工具列表中。
>
> Agent 在 [构建模式](#build-by-chatting) 中安装的工具，发布后仍可使用；而在发布后的运行中安装的内容只是临时的。

### 环境变量

> [!WARNING]
>
> **安全提示：Agent 环境变量外传风险**
>
> 本提示适用于 Dify Enterprise 3.13.x，在为 Agent 配置了环境变量且允许网络访问时适用。
>
> Dify Enterprise 3.13.x 的 Agent 运行环境采用基于模式匹配的脱敏机制，以降低敏感环境变量值以明文形式出现在用户可见回复或工具执行输出中的可能性。但是，仅凭该机制可能无法可靠阻止能够访问相关变量值及网络的 Agent 在传输前对变量值进行编码，例如采用 Base64、十六进制、字符拆分或其他混淆方式，并将其传输至运行环境能够访问的网络端点。
>
> 部署方有责任根据其系统、数据及凭证的敏感程度，对 Agent 的权限和访问范围进行适当配置。我们强烈建议：
>
> * 避免向 Agent 环境注入长期有效的凭证。
> * 尽可能使用短期、最小权限令牌。
> * 将网络出口限制在完成任务所必需的最小范围。
>
> 这是单独使用基于模式匹配的脱敏机制时所固有的局限。

在 **高级设置** 中，你可添加 **环境变量**：Agent 工作时可在沙箱中读取的键值对。

假设你的 Agent 的几个 Skill 都要访问同一套订单系统：一个查库存、一个下订单、一个拉报表。把系统的地址以 `ORDER_API_URL` 为名存在这里，所有脚本都按这个名字读取。要从测试系统切换到正式系统，只需在这里改这一个值，各个 Skill 都会跟着切换。

可导入 `.env` 文件，一次添加多个。你也可在 [构建模式](#build-by-chatting) 中让 Agent 代为设置。

> [!NOTE]
>
> 这里存储的值可能出现在 Agent 读取的命令输出中。要遮盖其中的敏感内容，设置 `DIFY_AGENT_SHELL_REDACT_PATTERNS`。详见 [环境变量](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-配置)。

## 通过对话构建

除了逐项手动设置，你也可通过描述 Agent 该做什么来构建它：对话过程中，它会自行配置好 Skill、文件和环境变量。

例如，你可以这样开场：

```text wrap theme={null}
帮我构建一个会议纪要 Agent：把原始会议记录整理成结构化纪要，包含参会人、决议和行动项。
```

与你对话的就是真实运行的 Agent：边构建边测试，看它如何反应，并在同一场构建对话中继续打磨。

Agent 工作时会直接修改面板中的配置，所有更改都会列在 **Build 草稿** 中。点击 **应用** 保留这些更改，或点击 **放弃** 全部丢弃。两者都会退出构建模式并清空对话。

> [!NOTE]
>
> **放弃** 会丢弃本次构建对话中的一切：对配置以及 [**文件系统**](#文件系统) 中长期文件的所有更改。

构建模式下配置面板是只读的，想改什么直接告诉 Agent 即可。

### 文件系统

在构建模式下，Agent 的工作会在沙箱里留下真实的文件：生成的产物（Artifacts）、自行安装的程序，以及过程中用到的其他内容。构建对话期间，点击右上角的 **文件系统** 即可浏览。

因为构建对话就是在塑造 Agent 本身，所以它添加的内容（比如起草的模板、安装的工具）默认为 **长期** 文件，在之后的每一次对话和工作流运行中均可用。实际上，这些文件和提示词、Skill 一样，都是 Agent 配置的一部分。

对于一次性的工作，比如测试文件或只用一次的转换工具，可在对话中直接告诉 Agent，例如「把这个文件设为临时」：它会归入 **临时** 文件，并在本次构建对话结束后清除。

在发布后的运行中，Agent 添加的任何内容都是临时的，因此运行中发生的一切都不会改变 Agent 本身。

### 构建笔记

在构建对话中，Agent 会把配置内容记录在「构建笔记」里，即一个 `build_note.md` 文件，在你首次点击 **应用** 后出现在 **文件** 中。

这份笔记会随 Agent 的配置一起保存。每次新对话开始时，Agent 都会重新读取笔记，将它与你的 **提示词** 组合成自己的指令。

应用之后，打开构建笔记，看看 Agent 记录了什么：

* 内容符合预期，就无需再动。

* 要修改笔记内容，可回到构建模式让 Agent 修订。

  > [!NOTE]
  >
  > Agent 只维护自动生成的构建笔记：下载后再上传的副本只是普通文件，下次构建对话会另外生成一份新笔记。

* 有遗漏的话，补充到 **提示词** 中。

* 想让 Agent 从头重新记录，可在 **文件** 中删除这份笔记。

在多次构建对话之间，这份笔记也相当于 Agent 的记忆。比如你在一次对话中定好了会议纪要 Agent 的格式，之后再开一次对话补充行动项负责人时，它会在已有格式和决定的基础上继续，而不是从头再来。

## 预览

将右侧面板从 **构建** 切换到 **预览**，即可以发布后终端用户看到的样子试用 Agent：回复干净整洁，Chat 功能生效。

在预览中对话不会改动 Agent 的任何配置，适合作为发布前的最后检查。

## 发布

编辑内容会自动保存为草稿。Agent 就绪后，发布即可让该版本上线。可随时打开版本历史，回看或恢复早期版本。

> [!NOTE]
>
> 恢复版本时，Agent 沙箱中的长期文件也会一并恢复到该版本。

> [!TIP]
>
> 要打磨聊天体验，可在 **Chat 功能** 中添加欢迎语、建议问题、语音等附加功能。详见 [应用工具箱](https://enterprise-docs.dify.ai/zh/3.13.x/use/build/additional-features.md)。

在 **访问点** 标签页中，可将它托管为 Web 应用并获得可分享的链接、嵌入你的网站，或在你的代码中通过 [服务 API](https://enterprise-docs.dify.ai/zh/3.13.x/develop/api/guides/agent.md) 调用。还可通过 [Web 应用访问控制](https://enterprise-docs.dify.ai/zh/3.13.x/use/publish/webapp/web-app-access.md) 设置谁能访问该 Web 应用。

> [!WARNING]
>
> 会话隔离程度取决于集群运行沙箱的方式。在启用 sandbox gateway 的标准部署中，每个 Agent 会话都有独立的沙箱 Pod，文件系统按会话隔离。
>
> 若部署采用共享沙箱的替代模式，所有会话共享同一个沙箱容器，终端用户之间的隔离较弱，请谨慎将 Agent 暴露给需要相互隔离的终端用户。

你也可将 Agent 请进工作流的 [Agent 节点](https://enterprise-docs.dify.ai/zh/3.13.x/use/nodes/agent.md#new-agent)，负责其中一步。

若要把 Agent 分享到其他工作空间，可将它导出为 DSL 文件。对方工作空间有同名 Skill 时，Skill 库中的 Skill 会自动重新关联；内嵌 Skill 和文件不包含在内，需一同分享。

### 运行限制

* **时长**

  单次 Agent 运行无论从哪个访问点发起（Web 应用、服务 API 或工作流），默认都会在 1 小时后被终止，未完成的回复会被清除。

  若运行被中断，可重试或把任务拆分成更小的步骤。要运行更长时间，将 `APP_MAX_EXECUTION_TIME`、`WORKFLOW_MAX_EXECUTION_TIME` 和 `DIFY_AGENT_RUN_TIMEOUT_SECONDS` 都调高到目标时长以上。

  这些变量的说明详见 [环境变量](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables.md)。

* **模型请求次数**

  Agent 每次调用模型都会计入单次运行 500 次的上限，推理越密集、工具用得越多，消耗越快。

  可尝试把任务拆分成更小的步骤，让每次运行保持在上限之内。

* **回复文件**

  Agent 在回复中发回的文件，单个默认不超过 50 MB，超出的文件不会被送达。

  若 Agent 需要产出更大的文件，调高 `DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT`。详见 [环境变量](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/environment-variables.md#agent-backend-配置)。

## 故障排查

> **Agents 页面中找不到某个 Agent，或无法编辑它**
>
> 若其他成员能看到某个 Agent 而你看不到，说明你不在它的允许访问成员列表中。请负责管理该 Agent 的人在 Agent 的 **访问权限** 中把你加入。
>
> 若能打开 Agent 却无法编辑，请对方把你在该 Agent 上的 **访问权限** 从 **按角色权限** 切换为包含 **编辑 Agent 信息与配置** 的权限集，例如内置的 **编辑内容**。该权限集只在这个 Agent 上替代你角色的权限。

> **节点列表中没有 Agent 节点**
>
> 在 Chatflow 应用中看不到该节点则属正常：新 Agent 节点仅在 Workflow 应用中可用。

> **Agent 运行一开始就失败**
>
> 若每次运行都立即报错，可能是集群缺少 Agent 所需的服务：agent-backend 服务或沙箱运行时。
>
> 所需组件及检查方法见 [Agent Sandbox 部署](https://enterprise-docs.dify.ai/zh/3.13.x/deploy/advanced-configuration/agent-sandbox.md)。

> **使用 OpenAI 兼容模型时，Agent 报错或从不调用工具**
>
> 通过 OpenAI 兼容端点提供的模型（如 vLLM 部署）往往缺少完整的原生工具调用支持，而无论在构建对话还是发布后的运行中，Agent 都依赖这一能力。
>
> 选择原生支持工具调用的模型。若兼容模型仍然报错，在供应商的模型设置中检查 **token 参数名**：部分较新的模型要求使用 `max_completion_tokens`，自动判断可能不准确。
>
> 部分 OpenAI 官方模型在开启推理的情况下，无法通过 Chat Completions 协议调用工具。此时可在供应商凭据中将 **API 协议** 改为 Responses API。

> **Agent 报错或忽略上传的图片**
>
> 无论 Agent 的模型是否支持视觉能力，**Chat 功能** 中都可开启图片上传。模型不支持视觉时，Agent 可能在处理图片时报错，或当作没有收到图片来回复。
>
> 改用支持视觉的模型：选择模型时留意 Vision 标签。

> **Agent 无法获取内网中的文件或页面**
>
> 沙箱的外网访问经由代理转发，代理默认拦截私有网络地址。公网 URL 可正常访问；内网资料请改为添加到 Agent 的 [文件](#files) 中。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.