LibreChat is joining ClickHouse to power the open-source Agentic Data Stack 🎉 Learn more
LibreChat

Agents Endpoint Object Structure

This page applies to the agents endpoint.

Example

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

This configuration enables the builder interface for agents.

recursionLimit

KeyTypeDescriptionExample
recursionLimitNumberSets the default number of steps an agent can take in a run.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.

Default: 25

Example:

recursionLimit: 50

For more information about agent steps, see Max Agent Steps.

maxRecursionLimit

KeyTypeDescriptionExample
maxRecursionLimitNumberSets the absolute maximum number of steps an agent can take in a run.Defines the upper limit for the recursionLimit that can be set from the UI. This prevents users from setting excessively high values.

Default: If omitted, defaults to the value of recursionLimit or 50 if recursionLimit is also omitted.

Example:

maxRecursionLimit: 100

For more information about agent steps, see Max Agent Steps.

titleTiming

KeyTypeDescriptionExample
titleTimingStringControls when conversation titles are generated for the agents endpoint. Valid values: "immediate" or "final".Defaults to "immediate".

Default: "immediate"

Available Values:

  • "immediate": Generates the title as soon as the request starts, in parallel with the model response, using the user's first message.
  • "final": Defers title generation until the full response completes. This preserves the legacy behavior.

Example:

titleTiming: immediate

disableBuilder

KeyTypeDescriptionExample
disableBuilderBooleanControls the visibility and use of the builder interface for agents.When set to `true`, disables the builder interface for the agent, limiting direct manual interaction.

Default: false

Example:

disableBuilder: false

allowedProviders

KeyTypeDescriptionExample
allowedProvidersArray/List of StringsSpecifies a list of endpoint providers (e.g., "openAI", "anthropic", "google") that are permitted for use with the Agents feature.If defined, only agents configured with these providers can be initialized. If omitted or empty, all configured providers are allowed.

Default: [] (empty list, all providers allowed)

Note: Must be one of the following, or a custom endpoint name as defined in your configuration: - openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock

Example:

allowedProviders:
  - openAI
  - google

capabilities

KeyTypeDescriptionExample
capabilitiesArray/List of StringsSpecifies the agent capabilities available to all users for the 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.

Default: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]

Programmatic Tool Calling is opt-in. Add programmatic_tools alongside execute_code only when your Code Interpreter deployment includes the Tool Call Server component.

Example:

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'

Note: This field is optional. If omitted, the default behavior is to include all the capabilities listed in the default.

skills

Controls endpoint-level Skills settings for agents.

KeyTypeDescriptionExample
skills.maxCatalogSkillsNumberCaps the number of active accessible Skills exposed in the model-visible catalog. Must be between 1 and 100.maxCatalogSkills: 20

Default: No configured cap beyond the runtime catalog limit.

Example:

skills:
  maxCatalogSkills: 20

This does not disable Skills. Use the skills capability and per-agent/model-spec skill scoping to control whether Skills are available.

maxCitations

KeyTypeDescriptionExample
maxCitationsNumberControls the maximum total number of citations that can be included in a single agent response.When using file_search capability, limits the total number of source citations returned to prevent overwhelming responses while ensuring comprehensive coverage.

Default: 30

Range: 1-50

Example:

maxCitations: 30

maxCitationsPerFile

KeyTypeDescriptionExample
maxCitationsPerFileNumberLimits the maximum number of citations that can be extracted from any single file.Ensures citation diversity by preventing any single file from dominating the citations, encouraging representation from multiple sources.

Default: 7

Range: 1-10

Example:

maxCitationsPerFile: 7

minRelevanceScore

KeyTypeDescriptionExample
minRelevanceScoreNumberSets the minimum relevance score threshold for sources to be included in responses.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.

Default: 0.45 (45% relevance threshold)

Range: 0.0-1.0

Example:

minRelevanceScore: 0.45

File Citation Configuration Examples

Default Configuration (Balanced)

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

Provides comprehensive citations while preventing overwhelming responses and filtering out low-quality matches.

Strict Configuration (High Quality)

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

Only includes highly relevant citations with strict limits for focused responses.

Comprehensive Configuration (Research)

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

Maximum information extraction for exhaustive research tasks, including all sources regardless of relevance.

Agent Capabilities

The capabilities field allows you to enable or disable specific functionalities for agents. The available capabilities are:

  • deferred_tools: Allows agents to discover deferred MCP tools at runtime instead of loading every tool into context upfront.
  • programmatic_tools: 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. This capability is opt-in and is not enabled by default.
  • execute_code: Allows the agent to execute code.
  • file_search: Enables the agent to search and interact with files. When enabled, citation behavior is controlled by maxCitations, maxCitationsPerFile, and minRelevanceScore settings.
  • web_search: Enables web search functionality for agents, allowing them to search and retrieve information from the internet.
  • artifacts: Enables the agent to generate interactive artifacts (React components, HTML, Mermaid diagrams).
  • subagents: Enables isolated-context child agent runs. See Subagents.
  • actions: Permits the agent to perform predefined actions.
  • context: Enables "Upload as Text" functionality in chat, and "File Context" for agents, allowing users to upload files and have their content extracted and included directly in the conversation.
  • skills: Enables Skills in the side panel, manual $ invocation, model-invoked skills, and agent skill allowlists. See Skills.
  • tools: Grants the agent access to various tools.
  • chain: Enables Beta feature for agent chaining, also known as Mixture-of-Agents (MoA) workflows.
  • ocr: Optionally enhances "Upload as Text" in chat, and "File Context" for agents, allowing files to be uploaded and processed with OCR. Requires an OCR service to be configured.

By specifying the capabilities, you can control the features available to users when interacting with agents.

Example Configuration

Here is an example of configuring the agents endpoint with custom capabilities and file citation settings:

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'

In this example:

  • The builder interface is enabled
  • File citations are limited to 20 total, with maximum 5 per file
  • Only sources with 60%+ relevance are included
  • LibreChat Agents have access to code execution, file search (with citations), Skills, Subagents, actions, artifacts, file context, ocr services if configured, and web search capabilities
  • Programmatic Tool Calling remains disabled unless you add the programmatic_tools capability alongside execute_code

remoteApi

Configuration for Remote Agent API authentication. Controls how external services authenticate when calling the Agents API endpoints.

remoteApi.auth

KeyTypeDescriptionExample
authObjectAuthentication configuration for the Remote Agent API.Supports API key and/or OIDC Bearer token authentication. If omitted, only API key auth is active.

remoteApi.auth.apiKey

KeyTypeDescriptionExample
enabledBooleanEnable API key authentication for the Remote Agent API.When true, requests with a valid LibreChat API key are accepted. Can be used alongside or instead of OIDC.

Default: true

remoteApi.auth.oidc

KeyTypeDescriptionExample
enabledBooleanEnable OIDC Bearer token authentication.When true, the middleware validates Bearer tokens against the configured OIDC issuer via JWKS.
issuerStringOIDC issuer 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.
jwksUriStringJWKS endpoint URL. Optional.If omitted, resolved automatically via {issuer}/.well-known/openid-configuration. You can also set OPENID_JWKS_URL as an alternative.
audienceStringExpected token audience. Required when OIDC auth is enabled.Tokens must contain this value in their aud claim.
scopeStringRequired scope value. Optional.If set, the token must contain this value in its scp or scope claim. Use this to distinguish token intent across different APIs.

Default: enabled: false

Example - OIDC only:

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

Example - OIDC with API key fallback:

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 resolution priority is explicit jwksUri, then OPENID_JWKS_URL, then auto-discovery via {issuer}/.well-known/openid-configuration.

OIDC user matching uses the sub claim as primary lookup, with fallback to email, preferred_username, or upn claims. The matched user must already exist in LibreChat.

Subagents

The subagents field controls which isolated child agents a parent agent can spawn when the subagents capability is available.

KeyTypeDescriptionExample
enabledBooleanAdds the subagent spawn tool to this agent when true. Default: disabled.enabled: true
allowSelfBooleanAllows the agent to spawn itself in a fresh isolated context. Default: true.allowSelf: true
agent_idsArray/List of StringsSpecific agents this agent may spawn. Maximum: 10.agent_ids: ["agent_researcher"]
subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'

For user-facing behavior and limits, see Subagents.

Notes

  • It's not recommended to disable the builder interface unless you are using modelSpecs to define a list of agents to choose from.
  • File citation configuration (maxCitations, maxCitationsPerFile, minRelevanceScore) only applies when the file_search capability is enabled.
  • The relevance score is calculated using vector similarity, where 1.0 represents a perfect match and 0.0 represents no similarity.
  • Citation limits help balance comprehensive information retrieval with response quality and performance.
  • The context capability works without OCR configuration using text parsing methods. OCR enhances extraction quality when configured.
  • The ocr capability requires an OCR service to be configured (see OCR Configuration).

How is this guide?

Edit on GitHub

On this page

ExamplerecursionLimitmaxRecursionLimittitleTimingdisableBuilderallowedProviderscapabilitiesskillsmaxCitationsmaxCitationsPerFileminRelevanceScoreFile Citation Configuration ExamplesAgent CapabilitiesExample ConfigurationremoteApiremoteApi.authremoteApi.auth.apiKeyremoteApi.auth.oidcSubagentsNotes