> ## 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 部署](/zh/3.12.x/deploy/advanced-configuration/agent-sandbox)。

  生产环境使用前，在 Helm values 中将 `agentBackend.serverSecretKey` 替换为你自己的随机值。
</Note>

## 创建 Agent

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

若要用他人分享的 DSL 文件创建 Agent，改选 **导入 DSL 文件** 即可。DSL 文件不包含 Skill 和文件。

<Info>
  创建和管理 Agent 需要 **管理 Agents** 权限，所有者、管理者、编辑者角色默认拥有。详见 [权限参考](/zh/3.12.x/use/workspace/permission-reference)。
</Info>

## 配置能力

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

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

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

### 模型

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

<Note>
  Agent 表现好不好，很大程度取决于模型，尽量选较新的模型。

  旧模型可能用不好沙箱：常见的表现是 Agent 始终不去运行命令或安装工具，即使任务需要也不动手。
</Note>

### 提示词

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

以下几点值得写进去：

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

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

* **在提示词中引用**：输入 `/` 引用，Agent 会在你指定的位置直接用上它。适合某个步骤依赖特定资源的场景。

* **只添加不引用**：把它加到对应区域，何时使用由 Agent 自行决定。适合你更愿意相信 Agent 的判断、不想事事写死的场景。

### Skill

Skill 是你为 Agent 打包的一套完整流程：把某项专门任务所需的指令、参考材料和脚本捆绑在一起，定义一次即可反复使用。

提示词设定的是 Agent 的整体角色，而 Skill 是它只在特定任务需要时才取用的作业指南，就像交给能干员工的一份 SOP。Agent 自带通用能力，Skill 则为这项工作提供你规定的确切步骤、材料和工具，让产出符合你的预期。

例如，一个 `marketing-copy` Skill 可打包你的风格指南、品牌素材和检查清单，省得每次重新解释。

Skill 包只能是 `.zip` 或 `.skill` 文件，不超过 50 MB，且包内要有 `SKILL.md`。关于包格式和构建方法，参见 [Agent Skills](https://agentskills.io/home)。你也可在 [构建模式](#通过对话构建) 中让 Agent 替你创建 Skill。

### 文件

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

文件适合少量需要 Agent 完整阅读、严格遵循的文档；要让它在大量资料中检索，应改为连接 [知识库](#知识检索)。

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

| 文件类型 | 默认上限   | 环境变量                           |
| :--- | :----- | :----------------------------- |
| 文档   | 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` |

<Info>
  在这里添加的文件会保存为 Agent 能力的一部分；Agent 在沙箱中创建的文件则会在任务结束后清除。
</Info>

你也可在 [构建模式](#通过对话构建) 中让 Agent 创建文件并保存到这里。

### 工具

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

<Tip>
  除了你在这里添加的 Dify 工具，Agent 需要时还能在沙箱内自行安装并运行命令行程序。

  这类工具不会出现在工具列表中；与工作目录中的文件不同，它们一经安装，后续任务可继续使用。
</Tip>

### 知识检索

连接 Agent 工作时可搜索的 [知识库](/zh/3.12.x/use/knowledge/readme)。

检索只取回与查询相关的内容，因此适合远超 [文件](#文件) 容量的大量资料。知识库还是工作空间级资产：可供其他应用共用，也可与其数据来源保持同步。

为每个知识库设置查询方式：

* **Agent 决定**：Agent 根据对话自行编写搜索查询。

  适合问题多变、希望由它判断该查什么的场景，比如用户问什么就查什么的文档助手。

* **自定义查询**：固定一条每次都执行的查询。

  适合某个来源始终按同一方式搜索的场景，比如不管用户怎么问，退货助手都固定检索退货政策。

在 **检索设置** 中调整结果的排序和过滤方式：

* **Rerank**：用重排序模型按相关性重新排序，或用 **权重设置** 在语义与关键词匹配之间分配权重。

  <Info>
    仅当所有已连接的知识库都采用高质量索引、共用同一个嵌入模型且均非外部知识库时，才会显示权重设置。

    只要其中一个为经济索引、外部知识库或使用不同的嵌入模型，该选项就不会出现。
  </Info>

* **Top K**：重排序后最多保留的结果数量。

* **Score 阈值**：结果入选所需的最低相似度。阈值越高越严格，越低覆盖越广。

要将搜索限定在特定文档内，可启用 [元数据](/zh/3.12.x/use/knowledge/metadata) 过滤。

### 高级设置

<Warning>
  **安全提示：Agent 环境变量外传风险**

  本提示适用于 Dify Enterprise 3.12.x，在为 Agent 配置了环境变量且允许网络访问时适用。

  Dify Enterprise 3.12.x 的 Agent 运行环境采用基于模式匹配的脱敏机制，以降低敏感环境变量值以明文形式出现在用户可见回复或工具执行输出中的可能性。但是，仅凭该机制可能无法可靠阻止能够访问相关变量值及网络的 Agent 在传输前对变量值进行编码，例如采用 Base64、十六进制、字符拆分或其他混淆方式，并将其传输至运行环境能够访问的网络端点。

  部署方有责任根据其系统、数据及凭证的敏感程度，对 Agent 的权限和访问范围进行适当配置。我们强烈建议：

  * 避免向 Agent 环境注入长期有效的凭证。
  * 尽可能使用短期、最小权限令牌。
  * 将网络出口限制在完成任务所必需的最小范围。

  这是单独使用基于模式匹配的脱敏机制时所固有的局限。
</Warning>

**环境变量** 是 Agent 运行时可读取的键值对，例如工具需要的端点或 API 密钥。

它们存放在 Agent 的沙箱中，因此你可借助它们把密钥交给命令行工具或 Skill，而不必写进提示词。将值标记为 **Secret** 可保持掩码显示；也可导入 `.env` 文件，一次添加多个。

你也可在 [构建模式](#通过对话构建) 中让 Agent 代为设置。

<Tip>
  要打磨聊天体验，可在 **Chat 功能** 中添加欢迎语、建议问题、语音等附加功能。详见 [应用工具箱](/zh/3.12.x/use/build/additional-features)。
</Tip>

## 通过对话构建

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

例如，你可以这样开场：

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

与你对话的就是真实运行的 Agent：边构建边测试，看它如何反应，并在同一场构建对话中继续打磨。要查看它正在处理的文件，点击 **文件系统**；这些文件会在退出构建模式后清除。

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

<Note>
  **放弃** 只会还原配置。Agent 已在沙箱中执行的操作（如安装的程序）无法撤销。
</Note>

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

### 构建笔记

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

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

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

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

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

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

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

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

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

## 预览

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

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

## 发布

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

<Note>
  恢复版本只会回滚 Agent 的配置。沙箱环境没有版本记录：安装的工具等环境更改会保持原样。
</Note>

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

<Warning>
  会话隔离程度取决于集群运行沙箱的方式。在启用 sandbox gateway 的标准部署中，每个 Agent 会话都有独立的沙箱 Pod，文件系统按会话隔离。

  若部署采用共享沙箱的替代模式，所有会话共享同一个沙箱容器，终端用户之间的隔离较弱，请谨慎将 Agent 暴露给需要相互隔离的终端用户。
</Warning>

<Info>
  Agent 的 API 仅支持流式返回。只有工作空间所有者和管理员可开启或关闭 API 访问。
</Info>

你也可将 Agent 请进工作流的 [Agent 节点](/zh/3.12.x/use/nodes/agent#新-agent)，负责其中一步。

上线后，在 **日志** 中查看它的对话，在 **监控** 中查看用量、质量、速度和成本。

若要把 Agent 分享到其他工作空间，可将它导出为 DSL 文件。导出的文件不包含 Skill 和文件。