Agents: 构建自定义 AI 助手

LibreChat 的 AI Agents 功能提供了一个灵活的框架，用于创建由各种模型提供商驱动的自定义 AI 助手。

此功能类似于 OpenAI 的 Assistants API 和 ChatGPT 的 GPTs，但具有更广泛的模型支持和无需代码的实现方式，让您可以构建具备专业能力的复杂助手。

入门指南

要创建一个新的 Agent，请从 endpoint 菜单中选择“Agents”，并打开侧边栏（Side Panel）中的 Agent Builder 面板。

创建表单包含：

• Avatar: 上传自定义头像以个性化您的智能体
• Name: 为您的智能体选择一个独特的名称
• Description: 关于您 Agent 用途的可选详细信息
• Instructions: 定义代理行为的系统指令
• Model: 从可用的提供商和模型中选择

可以通过侧边栏顶部的下拉菜单选择现有的 Agent。

• 也可以在聊天输入框中使用“@”提及。

模型配置

模型参数界面允许对您的智能体响应进行微调：

• Temperature (0-1 刻度，用于控制响应的创造性)
• 最大上下文 token 数
• 最大输出令牌数
• 其他特定于提供商的设置

智能体功能 (Agent Capabilities)

注意： 所有功能均可通过 librechat.yaml 配置文件进行切换。更多信息请参阅 docs/configuration/librechat_yaml/object_structure/agents#capabilities。

Code Interpreter

启用后，Code Interpreter 功能允许您的智能体执行以下操作：

• 在多种语言中执行代码，包括：
  • Python, JavaScript, TypeScript, Go, C, C++, Java, PHP, Rust 和 Fortran
• 通过 LibreChat Code Interpreter API 安全地处理文件
• 无需本地设置、配置或沙盒部署即可运行代码
• 无缝处理文件上传和下载
• 关于 Code Interpreter API 的更多信息
  • 由开源 code-interpreter 服务（自托管）提供支持

文件搜索

File Search 功能支持：

• RAG (Retrieval-Augmented Generation) 功能
• 对上传的文档进行语义搜索
• 基于文件内容的上下文感知响应
• 在 Agent 和聊天会话级别均支持文件附件

文件上下文

File Context 功能允许您的 agent 将从文件中提取的文本存储为其系统指令的一部分：

• 在保持文档结构和格式的同时提取文本
• 处理复杂的布局，包括多栏文本和混合内容
• 处理表格、公式以及其他专业内容
• 处理多语言内容
• 文本存储在数据库中代理的 instructions 中。
• 无需 OCR 服务 - 默认使用文本解析，并提供回退方法
• 由 OCR 增强 - 如果配置了 OCR，图像和扫描文档的提取质量将会提高
• 使用与“作为文本上传”相同的处理逻辑：OCR > STT > 文本解析
• 关于 OCR 配置的更多信息

注意： 文件上下文包含提取到智能体系统指令中的文本。对于单个对话中的临时文档提问，请改用聊天界面中的 Upload as Text。

Model Context Protocol (MCP)

MCP 是一个开放协议，它标准化了应用程序向大语言模型 (LLMs) 提供上下文的方式，充当了 AI 工具和数据源的通用适配器。

有关更多信息，请参阅 MCP 的相关文档。

带有 MCP 工具的 Agents

1. 在您的 librechat.yaml 文件中配置 MCP 服务器
2. 重启 LibreChat 以初始化连接
3. 创建或编辑一个 Agent
4. 点击 Agent Builder 面板中的 "Add Tools" 按钮，打开如下图所示的 Tools Dialog。
5. 选择您想要添加的 MCP 服务器——每个服务器将作为一个单独的条目显示
6. 保存您对 Agent 所做的更改

在此示例中，我们已将 Spotify MCP server 添加到了一个 agent 中。

管理 MCP Tools

一旦将 MCP 服务器添加到智能体中，您可以微调哪些特定工具可用：

• 添加 MCP 服务器后，展开它以查看所有可用工具
• 根据需要勾选或取消勾选单个工具
• 例如，Spotify MCP server 提供了约 20 种工具（搜索、播放控制、播放列表管理等）。
• 这种细粒度的控制允许您将智能体限制在仅使用它们所需的工具上。

了解更多：

• 配置 MCP 服务器
• Model Context Protocol 简介

延迟工具

延迟工具（Deferred tools）允许智能体访问许多 MCP 工具，而无需预先将它们全部加载到 LLM 上下文中。相反，延迟工具可以通过**工具搜索（Tool Search）**机制在运行时被发现。

当代理（agent）可以访问许多拥有数十个工具的 MCP 服务器时，这一点尤其有用——因为加载所有这些工具会消耗大量的上下文窗口，并降低响应质量。

工作原理：

• 标记为 "deferred" 的工具将从初始 LLM 上下文中排除。
• 系统会自动添加一个 ToolSearch 工具，允许 LLM 按需发现并加载延迟加载的工具。
• 一旦被发现，该工具将在对话的剩余部分中可用。

配置延迟工具 (deferred tools)：

1. 打开 Agent Builder 并添加 MCP tools
2. 点击任意 MCP 工具上的下拉菜单
3. 切换“延迟加载” — 延迟的工具会显示一个时钟图标

注意： deferred_tools 功能默认处于启用状态。可以通过 librechat.yaml 代理配置 进行切换。

程序化工具调用

程序化工具调用 (PTC) 允许智能体从 Code Interpreter 沙盒内部执行选定的 MCP 工具，而不是直接从模型调用每个工具。模型会接收一个由 Code Interpreter 支持的编排工具，编写沙盒代码来调用生成的工具函数，并可以在返回答案之前使用循环、条件判断、重试和结果处理。

这对于多步工具工作流非常有用，例如查询多个资源、对结果进行分页、比较输出，或在智能体解释工具响应之前对其进行转换。

配置编程工具：

1. 在 librechat.yaml agents capabilities 中同时启用 programmatic_tools 和 execute_code。
2. 在智能体上启用 Code Interpreter。
3. 添加 MCP 工具，扩展 MCP 服务器，并为单个工具或整个服务器切换 Programmatic（编程）模式。编程工具会显示一个代码图标。

注意： programmatic_tools 是可选功能，并未包含在默认的智能体能力列表中。PTC 还需要部署带有 Tool Call Server 组件的 Code Interpreter。只有为智能体注册的工具才能在沙盒中被调用；未注册的工具调用将被拒绝。

Skills

Skills 允许 Agent 从 SKILL.md 定义中加载可重用的指令。它们可以通过在聊天中输入 $ 手动选择，由模型通过技能目录自动发现，或者设置为在每一轮对话中始终应用。

有关创作、调用和访问控制的详细信息，请参阅 Skills。

Artifacts

Artifacts 功能使您的 agent 能够生成并显示交互式内容：

• 创建 React 组件、HTML 代码和 Mermaid 图表
• 在单独的 UI 窗口中显示内容，以获得更好的清晰度和交互体验
• 在 Agent 级别配置特定于 Artifact 的指令
• 关于 Artifacts 的更多信息

启用后，默认会添加特定于使用 artifacts 的额外指令。选项包括：

• 启用 shadcn/ui 说明：添加有关使用 shadcn/ui 组件（一套使用 Radix UI 和 Tailwind CSS 构建的可复用组件集合）的说明。
• 自定义提示词模式 (Custom Prompt Mode)：启用后，将不会包含默认的 Artifacts 系统提示词，允许您提供自己的自定义指令。

在 Agent 级别配置 artifacts 是首选方法，因为它相比传统的全局配置提供了更细粒度的控制。

如果您启用了 Custom Prompt Mode，则应在您的指令中至少包含基本的 artifact 格式。

以下是一个所需最小指令的简单示例：

When creating content that should be displayed as an artifact, use the following format:

:::artifact{identifier="unique-identifier" type="mime-type" title="Artifact Title"}

```
Your artifact content here
```

:::

For the type attribute, use one of:

- "text/html" for HTML content
- "application/vnd.mermaid" for Mermaid diagrams
- "application/vnd.react" for React components
- "image/svg+xml" for SVG images

工具

Agents 也可以通过各种内置工具进行增强：

• OpenAI Image Tools：使用 GPT-Image-1 进行图像生成与编辑
• Gemini Image Tools：使用 Gemini 图像模型进行图像生成和图像上下文编辑
• DALL-E-3：根据文本描述生成图像
• Stable Diffusion / Flux：文本生成图像
• Wolfram：计算与数学能力
• OpenWeather：天气数据检索
• Google Search：访问网络搜索功能
• Calculator：数学计算
• Tavily Search：具有多样化数据源集成的高级搜索 API
• Azure AI Search：从 Azure AI Search 索引中检索信息
• Traversaal：一个为 LLM Agent 设计的强大搜索 API

创建带有图像工具的 Agent

1. 将图像工具凭据添加到 .env 中，例如用于 OpenAI Image Tools 的 IMAGE_GEN_OAI_API_KEY。
2. 重启 LibreChat 以加载新的环境变量。
3. 从 endpoint 菜单中选择 Agents。
4. 从侧边栏打开 Agent Builder 并创建或编辑一个 agent。
5. 打开智能体的 Tools 列表，选择 OpenAI Image Tools、Gemini Image Tools、DALL-E-3、Stable Diffusion 或 Flux，然后保存智能体。
6. 与该 agent 开始对话，并要求它生成或编辑一张图片。

有关完整的图像设置指南，包括 IMAGE_GEN_OAI_MODEL 等模型变量，请参阅 图像生成与编辑。

• 可以使用 librechat.yaml 配置文件禁用 Tools：
  • 更多信息

Actions

通过 Actions 功能，您可以根据 OpenAPI specs 动态创建工具，并将其添加到您的 Agents 中。

点击上方的按钮将打开一个表单，您可以在其中输入 OpenAPI 规范 URL 并创建操作：

• 可以通过 librechat.yaml 配置文件禁用 Actions：
  • 更多信息
• 可以为代理操作将单个域名加入白名单：
  • 更多信息
• Note that you can add add the 'x-strict': true flag at operation-level in the OpenAPI spec for actions. If using an OpenAI model supporting it, this will automatically generate function calls with 'strict' mode enabled.
  • 严格模式仅支持 JSON 的部分子集。请阅读 https://platform.openai.com/docs/guides/structured-outputs 以了解详情。

Agent Chain

Agent Chain 功能支持代理混合 (Mixture-of-Agents, MoA) 方法，允许您创建一系列协同工作的代理：

• 为复杂任务创建专业智能体链
• 链中的每个 agent 都可以访问先前 agent 的输出
• 配置代理链的最大步数
• 注意： 从 Agent Builder 中的 Advanced Settings 面板访问此功能。
• 注意： 此功能目前处于测试阶段，可能会有所变动
  • 当前可链接的智能体最大数量为 10 个，但未来可能会支持配置。

此功能为 LibreChat 引入了分层的 Mixture-of-Agents 架构，其中每个智能体都将上一层所有智能体的输出作为辅助信息来生成其响应，正如 同名“Mixture-of-Agents”论文 中所述。

子代理 (Subagents)

子代理（Subagents）允许代理将专注的任务委派给独立的子运行（child run）。子运行拥有其独立的上下文窗口和工具执行流程，随后将精简的结果返回给父代理，而不是用所有的中间步骤填满父代理的上下文。

子代理（Subagents）与代理链（Agent Chain）不同：代理链将多个代理作为图的参与者进行协调，而子代理则是由代理作为工具调用而生成的，用于范围受限的委派。有关设置和限制，请参阅 Subagents。

高级设置

代理的高级设置（位于代理表单的“高级”视图中），不包含“能力”（capabilities）部分。

最大代理步骤 (Max Agent Steps)

此设置允许您限制代理在一次“运行”（run）中可以采取的步骤数量，这指的是在给出最终响应之前的代理循环。

如果未进行配置，默认值为 25 步，但您可以根据需要进行调整。对于管理员，您可以在 librechat.yaml 文件中设置全局默认值以及全局最大值。

“步骤”（step）是指一次 AI API 请求或一轮工具使用（根据 LLM 在单次请求中提供的工具调用数量，可能涉及 1 个或多个工具）。

单次非工具响应为 1 步。单轮工具使用通常为 3 步：

1. API 请求 -> 2. 工具使用（1 个或多个工具） -> 3. 后续 API 请求

文件管理

Agents 支持多种处理文件的方式：

在聊天界面中

与智能体聊天时，你有四种上传选项：

1. 上传图片

   • 上传图片以实现对原生视觉模型的支持
   • 将图像直接发送给模型提供商

2. 作为文本上传 (需要 context 功能)

   • 在对话中提取并包含完整的文档内容
   • 默认使用文本解析；如果已配置，则通过 OCR 增强。
   • 内容仅存在于当前对话中
   • 请参阅 Upload as Text

3. 用于文件搜索的上传（需要 file_search 功能，且已开启）

   • 使用带有向量存储的语义搜索 (RAG)
   • 通过工具使用返回相关数据块
   • 非常适合大型文档/多个文件
   • 对于结构化数据（CSV、Excel、JSON 等）效果不佳

4. 代码解释器上传（需要 execute_code 功能，并已开启）

   • 将文件添加到代码解释器环境
   • 最适合处理结构化数据（CSV、Excel、JSON 等）
   • 更多关于 Code Interpreter 的信息

在 Agent Builder 中

在配置 Agent 时，您可以附加不同类别的文件：

1. 图像上传：用于智能体可以引用的视觉内容
2. 文件搜索上传 (File Search Upload)：用于 RAG 功能的文档
3. Code Interpreter Upload: 用于代码处理的文件
4. 文件上下文: 包含提取文本的文档，用于补充 Agent 指令

File Context 使用 context 功能，其工作方式与 "Upload as Text" 完全相同——默认使用文本解析，并在配置后通过 OCR 增强。文本在上传时被提取并存储在 agent 的指令中。这非常适合为 agent 提供来自文档、PDF、代码文件或包含文本的图像的持久知识。

处理优先级： OCR > STT > 文本解析（与“作为文本上传”相同）

注意： 提取的文本将作为智能体系统指令的一部分包含在内。

共享与权限

Agents 使用 LibreChat 的细粒度 access control 系统。每个 Agent 都有其自己的访问控制列表 (ACL)，并且可以与特定的 users、groups、roles 共享，或者 publicly（公开）共享，每种共享方式都可以设置特定的权限级别。

访问角色

当共享 Agent 时，受让人会被分配以下三种角色之一：

无论 ACL 如何设置，原始作者和管理员始终保留完全控制权。

共享 Agent

1. 在 Agent Builder 中打开该 agent
2. 点击页脚中的 Share 按钮（当你是创建者、管理员，或已被授予该特定 agent 的 SHARE 权限时可见）
3. 在人员选择器中搜索用户、组或角色，并为每个对象分配一个角色
4. 您可以选择性地切换 Public（公开）开关，使该 Agent 对实例上的所有用户可见（需要 SHARE_PUBLIC 功能权限）。

有关主体、权限位以及 ACL 如何与基于角色的功能权限组合的完整详细信息，请参阅 Access Control。

管理员控制

管理员可以在 agent builder UI 中访问全局权限设置：

• 启用/禁用所有用户的智能体共享功能
• 控制 Agent 使用权限
• 管理智能体创建权限
• 配置平台范围的设置

为您实例创建的第一个账户即为管理员。如果您需要添加额外的管理员，您可以访问 MongoDB 并更新该用户的个人资料：

db.users.updateOne(
  { email: 'USER_EMAIL_ADDRESS' },
  { $set: { role: 'ADMIN' } }
)

也可以通过配置禁用所有用户的代理功能，更多信息。

功能级权限（谁可以_使用_、创建、共享_或_公开共享 Agent）可在 LibreChat Admin Panel 中针对每个角色（包括任何自定义角色）进行管理。librechat.yaml 中的 interface.agents 代码块仍然可以在启动时为内置的 USER 角色设定默认值，但建议今后通过管理面板进行编辑。

用户级共享

个人用户可以：

• 与特定用户、群组或角色共享他们的 Agent（如果其角色已启用 SHARE 功能）
• 使智能体对实例上的所有人可见（如果启用了 SHARE_PUBLIC）
• 为每位接收者授予不同的访问权限（Viewer / Editor / Owner）
• 随时可以通过共享对话框重新共享或撤销访问权限

注意事项

• 只有拥有编辑权限的用户才能查看指令、模型参数、附加文件和工具。
  • Agent 可能会通过对话泄露任何附加的数据（无论是指令还是文件），因此在授予 Editor/Owner 权限或将 Agent 公开之前，请确保您的指令能够有效防范此类风险。
• 只有原始作者、管理员以及拥有所有者权限的被授权人才能删除共享的 Agent。
• 除非已共享，否则 Agent 仅对作者本人可见。

可选配置

LibreChat 允许管理员通过 librechat.yaml 文件配置代理的使用：

• 为所有用户（包括管理员）禁用 Agents：更多信息
• 使用以下内容自定义 agent 功能：更多信息

最佳实践

• 为您的智能体提供清晰、具体的指令
• 请仔细考虑哪些工具对于您的用例是必要的
• 在四个上传类别中适当地组织文件
• 在共享 Agent 之前请检查权限设置
• 在向其他用户部署之前，请彻底测试您的 Agent。

回顾

1. 从 endpoint 下拉菜单中选择 "Agents"
2. 打开 Agent Builder 面板
3. 填写所需的 Agent 详细信息
4. 配置所需功能（Code Interpreter、File Search、File Context 等）
5. 添加必要的工具和文件
6. 如果需要，请设置共享权限
7. 创建并开始使用您的智能体

在与智能体聊天时，您可以：

• 使用“Upload as Text”将完整文档内容包含在对话中（默认进行文本解析，并可通过 OCR 增强）。
• 使用“Upload for File Search”对文档进行语义搜索（需要 RAG API）
• 将文件添加到智能体的“文件上下文”（File Context），以将文件的全部内容作为智能体系统指令的一部分包含在内。

需要迁移 (v0.8.0-rc3+)

迁移执行的操作

代理权限迁移将您的代理从简单的所有权模型转换为具有多个权限级别的复杂的基于 ACL 的系统：

• OWNER: 对 Agent 的完全控制权
• EDITOR: 可以查看并修改该 Agent
• VIEWER: 对 Agent 的只读访问权限

如果不运行此迁移，现有的 Agent 将无法通过新的具备权限感知能力的 API endpoint 进行访问。

运行迁移

根据您的部署方式选择相应的命令：

1. 对于默认的 docker-compose.yml（如果您使用 docker compose up 来启动应用）：

预览更改（试运行）：

docker compose exec api npm run migrate:agent-permissions:dry-run

执行迁移：

docker compose exec api npm run migrate:agent-permissions

自定义批处理大小（针对大型数据集）：

docker compose exec api npm run migrate:agent-permissions:batch

2. 针对 deploy-compose.yml

如果您按照 Ubuntu Docker Guide 操作：

预览更改（试运行）：

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions:dry-run"

执行迁移：

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions"

自定义批处理大小（针对大型数据集）：

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions:batch"

3. 用于本地开发（从项目根目录）：

预览更改（试运行）：

npm run migrate:agent-permissions:dry-run

执行迁移：

npm run migrate:agent-permissions

自定义批处理大小（针对大型数据集）：

npm run migrate:agent-permissions:batch

迁移过程中会发生什么

• 私有 Agent：仅对其创建者可见（获得 OWNER 权限）
• 共享智能体 (Shared Agents)：如果一个智能体之前已被共享，它将作为公共智能体（共享给所有用户）接收相应的 ACL 条目。
• 系统检测：LibreChat 会在启动时自动检测未迁移的智能体并显示警告

您可以通过 Agent Builder UI 调整生成的智能体权限。

Agents API (Beta)

LibreChat agents 也可以通过 API 以编程方式访问，使外部应用程序和脚本能够使用兼容 OpenAI 的 SDK 或 Open Responses 格式与您的 agent 进行交互。

请参阅 Agents API 文档 以获取设置和使用详情。

下一步是什么？

LibreChat Agents 为该应用开启了一个新时代，未来可以通过针对特定任务和工作流程的 Agents 来简化您在 LibreChat 中的使用体验。

未来的更新将包括：

• 对当前 Agent 体验的常规改进
• 用于复杂工作流的多智能体编排
• 能够为各种功能自定义 Agent：标题生成（聊天会话命名）、记忆管理（用户上下文/历史记录）以及提示词增强（输入辅助/预测）
• 更多工具，可配置的工具参数，动态工具创建。

此外，此次更新为 LibreChat 引入了一种全新的范式，其底层架构为应用程序提供了急需的更新，在优化用户体验的同时也提升了整体应用性能。

为了强调一项显著的优化，使用传统 endpoint（在撰写本文时，指 Agents 和 AWS Bedrock 之外的任何 endpoint 选项）生成约 1000 个 token 的 AI 内容，将传输约 1 MB 的数据。

使用 Agent 时，同样的生成过程仅会传输约 52 kb 的数据，数据传输量减少了 95%，这大大减轻了服务器和用户设备的负载。

LibreChat 中的 AI Agents 提供了一种强大的方式来创建专业助手，无需编程知识，同时保持了与您首选的 AI 模型和提供商协作的灵活性。

#LibreChat #AIAssistants #NoCode #OpenSource