Agents 端点对象结构

此页面适用于 agents endpoint。

示例

endpoints:
  agents:
    recursionLimit: 50
    maxRecursionLimit: 100
    disableBuilder: false
    # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
    # Add "programmatic_tools" with "execute_code" to enable Programmatic Tool Calling for MCP tools.
    # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]
    # (optional) File citation configuration for file_search capability
    maxCitations: 30 # Maximum total citations in responses (1-50)
    maxCitationsPerFile: 7 # Maximum citations from each file (1-10)
    minRelevanceScore: 0.45 # Minimum relevance score threshold (0.0-1.0)
    titleTiming: immediate
    skills:
      maxCatalogSkills: 20
    remoteApi:
      auth:
        oidc:
          enabled: false

此配置启用了用于 Agent 的构建器界面。

recursionLimit

Key	Type	Description	Example
recursionLimit	Number	设置代理在单次运行中可执行的默认步数。	Controls recursion depth to prevent infinite loops. When limit is reached, raises GraphRecursionError. This value can be configured from the UI up to the maxRecursionLimit.

默认值： 25

示例：

recursionLimit: 50

有关代理步骤的更多信息，请参阅 Max Agent Steps。

maxRecursionLimit

Key	Type	Description	Example
maxRecursionLimit	Number	设置代理在单次运行中可执行的最大步数。	Defines the upper limit for the recursionLimit that can be set from the UI. This prevents users from setting excessively high values.

默认值： 如果省略，则默认为 recursionLimit 的值；如果 recursionLimit 也被省略，则默认为 50。

示例：

maxRecursionLimit: 100

有关代理步骤的更多信息，请参阅 Max Agent Steps。

titleTiming

Key	Type	Description	Example
titleTiming	String	控制何时为 agents endpoint 生成对话标题。有效值："immediate" 或 "final"。	Defaults to "immediate".

默认值： "immediate"

可用值：

"immediate": 在请求开始时立即生成标题，与模型响应并行，并使用用户的首条消息。
"final"：推迟标题生成，直到完整响应完成。这保留了旧有的行为。

示例：

titleTiming: immediate

disableBuilder

Key	Type	Description	Example
disableBuilder	Boolean	控制智能体构建器界面的可见性与使用。	When set to `true`, disables the builder interface for the agent, limiting direct manual interaction.

默认值： false

示例：

disableBuilder: false

allowedProviders

Key	Type	Description	Example
allowedProviders	Array/List of Strings	指定允许与 Agents 功能配合使用的 endpoint 提供商列表（例如 "openAI"、"anthropic"、"google"）。	If defined, only agents configured with these providers can be initialized. If omitted or empty, all configured providers are allowed.

默认值： []（空列表，允许所有提供商）

注意： 必须是以下选项之一，或者是您在 configuration 中定义的自定义 endpoint 名称：- openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock

示例：

allowedProviders:
  - openAI
  - google

capabilities

Key	Type	Description	Example
capabilities	Array/List of Strings	指定可供所有用户在 agents endpoint 中使用的智能体功能。	Defines the agent capabilities that are available to all users for the agents endpoint. You can omit the capabilities you wish to exclude from the list.

默认值： ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]

Programmatic Tool Calling 是可选功能。仅当您的 Code Interpreter 部署包含 Tool Call Server 组件时，才需在 execute_code 旁边添加 programmatic_tools。

示例：

capabilities:
  - 'deferred_tools'
  # Optional: enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder.
  # Requires execute_code and a Code Interpreter deployment with the Tool Call Server component.
  # - 'programmatic_tools'
  - 'execute_code'
  - 'file_search'
  - 'web_search'
  - 'artifacts'
  - 'subagents'
  - 'actions'
  - 'context'
  - 'skills'
  - 'tools'
  - 'chain'
  - 'ocr'

注意： 此字段为可选字段。如果省略，默认行为是包含 default 中列出的所有功能。

skills

控制代理的 endpoint 级别 Skills 设置。

Key	Type	Description	Example
skills.maxCatalogSkills	Number	限制模型可见目录中可用的活跃 Skill 数量。必须介于 1 到 100 之间。	maxCatalogSkills: 20

默认值： 没有超出运行时目录限制的已配置上限。

示例：

skills:
  maxCatalogSkills: 20

这不会禁用 Skills。请使用 skills 功能以及针对每个 agent/model-spec 的技能范围界定来控制 Skills 是否可用。

maxCitations

Key	Type	Description	Example
maxCitations	Number	控制单个智能体响应中可包含的引用总数上限。	When using file_search capability, limits the total number of source citations returned to prevent overwhelming responses while ensuring comprehensive coverage.

默认值： 30

范围： 1-50

示例：

maxCitations: 30

maxCitationsPerFile

Key	Type	Description	Example
maxCitationsPerFile	Number	限制可从单个文件中提取的最大引用数量。	Ensures citation diversity by preventing any single file from dominating the citations, encouraging representation from multiple sources.

默认值： 7

范围： 1-10

示例：

maxCitationsPerFile: 7

minRelevanceScore

Key	Type	Description	Example
minRelevanceScore	Number	设置包含在响应中的来源的最低相关性评分阈值。	Filters out low-quality matches based on vector similarity scores. Higher values (e.g., 0.7) ensure only highly relevant sources are cited, while lower values (e.g., 0.0) include all sources regardless of quality.

默认值： 0.45（45% 相关性阈值）

范围： 0.0-1.0

示例：

minRelevanceScore: 0.45

文件引用配置示例

默认配置（平衡）

endpoints:
  agents:
    maxCitations: 30
    maxCitationsPerFile: 7
    minRelevanceScore: 0.45

提供全面的引用，同时防止回复过于冗长并过滤掉低质量的匹配结果。

严格配置（高质量）

endpoints:
  agents:
    maxCitations: 10
    maxCitationsPerFile: 3
    minRelevanceScore: 0.7

仅包含高度相关的引用，并严格限制以实现聚焦的响应。

全面配置（研究）

endpoints:
  agents:
    maxCitations: 50
    maxCitationsPerFile: 10
    minRelevanceScore: 0.0

针对详尽研究任务的最大化信息提取，包括所有来源，无论其相关性如何。

智能体功能 (Agent Capabilities)

capabilities 字段允许您为智能体启用或禁用特定功能。可用的功能包括：

deferred_tools: 允许智能体在运行时发现延迟加载的 MCP 工具，而不是预先将所有工具加载到上下文中。
programmatic_tools: 启用在 Agent Builder 中标记为 Programmatic 的 MCP 工具的程序化工具调用（Programmatic Tool Calling）。需要 execute_code 以及带有 Tool Call Server 组件的 Code Interpreter 部署。此功能为选择性加入，默认情况下不启用。
execute_code: 允许智能体执行代码。
file_search: 启用该功能后，Agent 可以搜索并与文件进行交互。启用后，引用行为将由 maxCitations、maxCitationsPerFile 和 minRelevanceScore 设置控制。
web_search: 为智能体启用网络搜索功能，允许其搜索并从互联网检索信息。
artifacts: 启用代理以生成交互式工件（React 组件、HTML、Mermaid 图表）。
subagents: 启用隔离上下文的子智能体运行。请参阅 Subagents。
actions: 允许智能体执行预定义的操作。
context: 启用聊天中的“作为文本上传”功能，以及代理的“文件上下文”功能，允许用户上传文件，并将其内容提取并直接包含在对话中。
skills: 在侧边栏中启用 Skills，支持手动 $ 调用、模型调用的 Skills 以及智能体技能白名单。请参阅 Skills。
tools: 授予智能体访问各种工具的权限。
chain: 启用代理链（Agent Chaining）的 Beta 功能，也称为智能体混合（Mixture-of-Agents，简称 MoA）工作流。
ocr: 可选功能，用于增强聊天中的“上传为文本”以及智能体的“文件上下文”功能，允许上传文件并使用 OCR 进行处理。需要配置 OCR 服务。

通过指定功能，您可以控制用户在与智能体交互时可使用的特性。

示例配置

以下是配置 agents endpoint 并设置自定义能力和文件引用功能的示例：

endpoints:
  agents:
    disableBuilder: false
    # File citation configuration
    maxCitations: 20
    maxCitationsPerFile: 5
    minRelevanceScore: 0.6
    # Custom capabilities
    capabilities:
      # Optional: enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder.
      # - 'programmatic_tools'
      - 'execute_code'
      - 'file_search'
      - 'skills'
      - 'subagents'
      - 'actions'
      - 'artifacts'
      - 'context'
      - 'ocr'
      - 'web_search'

在此示例中：

构建器界面已启用
文件引用总数限制为 20 个，每个文件最多 5 个。
仅包含相关度在 60% 以上的来源
LibreChat Agents 可以访问代码执行、文件搜索（带引用）、Skills、Subagents、actions、artifacts、文件上下文、OCR 服务（如果已配置）以及网络搜索功能。
除非你同时添加 programmatic_tools 和 execute_code 功能，否则 Programmatic Tool Calling 将保持禁用状态。

remoteApi

远程 Agent API 身份验证的配置。控制外部服务在调用 Agents API endpoint 时如何进行身份验证。

remoteApi.auth

Key	Type	Description	Example
auth	Object	Remote Agent API 的身份验证配置。	Supports API key and/or OIDC Bearer token authentication. If omitted, only API key auth is active.

remoteApi.auth.apiKey

Key	Type	Description	Example
enabled	Boolean	为 Remote Agent API 启用 API 密钥身份验证。	When true, requests with a valid LibreChat API key are accepted. Can be used alongside or instead of OIDC.

默认值： true

remoteApi.auth.oidc

Key	Type	Description	Example
enabled	Boolean	启用 OIDC Bearer 令牌身份验证。	When true, the middleware validates Bearer tokens against the configured OIDC issuer via JWKS.
issuer	String	OIDC 颁发者 URL。	The base URL of your OIDC provider, such as a Keycloak realm URL. Used for token issuer validation and JWKS discovery if jwksUri is not set.
jwksUri	String	JWKS endpoint URL。可选。	If omitted, resolved automatically via {issuer}/.well-known/openid-configuration. You can also set OPENID_JWKS_URL as an alternative.
audience	String	预期的令牌受众。当启用 OIDC 认证时为必填项。	Tokens must contain this value in their aud claim.
scope	String	必需的 scope 值。可选。	If set, the token must contain this value in its scp or scope claim. Use this to distinguish token intent across different APIs.

默认值： enabled: false

示例 - 仅 OIDC：

endpoints:
  agents:
    remoteApi:
      auth:
        apiKey:
          enabled: false
        oidc:
          enabled: true
          issuer: https://auth.example.com/realms/myrealm
          audience: my-client-id

示例 - 使用 API 密钥回退的 OIDC：

endpoints:
  agents:
    remoteApi:
      auth:
        apiKey:
          enabled: true
        oidc:
          enabled: true
          issuer: https://auth.example.com/realms/myrealm
          # jwksUri is optional and auto-discovered if omitted
          jwksUri: https://auth.example.com/realms/myrealm/protocol/openid-connect/certs
          audience: my-client-id

JWKS URI 的解析优先级为：显式 jwksUri，其次是 OPENID_JWKS_URL，最后是通过 {issuer}/.well-known/openid-configuration 进行自动发现。

OIDC 用户匹配使用 sub 声明作为主要查找依据，并回退到 email、preferred_username 或 upn 声明。匹配的用户必须已存在于 LibreChat 中。

Subagents

subagents 字段用于控制当 subagents 功能可用时，父 Agent 可以生成的独立子 Agent。

Key	Type	Description	Example
enabled	Boolean	当为 true 时，将子代理生成工具添加到此代理。默认：禁用。	enabled: true
allowSelf	Boolean	允许智能体在全新的隔离上下文中生成自身。默认值：true。	allowSelf: true
agent_ids	Array/List of Strings	此智能体可以生成的特定智能体。最多：10 个。	agent_ids: ["agent_researcher"]

subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'

有关面向用户的行为和限制，请参阅 Subagents。

注意事项

除非您正在使用 modelSpecs 来定义可供选择的智能体列表，否则不建议禁用构建器界面。
文件引用配置（maxCitations、maxCitationsPerFile、minRelevanceScore）仅在启用 file_search 功能时生效。
相关性分数是使用向量相似度计算得出的，其中 1.0 表示完全匹配，0.0 表示完全不相似。
引用限制有助于在全面的信息检索与响应质量及性能之间取得平衡。
context 功能无需 OCR 配置即可通过文本解析方法工作。配置 OCR 后可提升提取质量。
ocr 功能需要配置 OCR 服务（请参阅 OCR 配置）。

Agents 端点对象结构

本页内容