Agents Endpoint Object Structure

This page applies to the agents endpoint.

Example

endpoints:
  agents:
    recursionLimit: 50
    maxRecursionLimit: 100
    maxToolCallArgBytes: 65536
    maxDeltaEventsPerTurn: 100000
    maxToolCallArgBytesByTool:
      create_file: 131072
    disableBuilder: false
    # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
    # Opt-in capabilities: "programmatic_tools", "stateful_code_sessions", "run_in_background", and "tool_intents".
    # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "memory", "ask_user_question", "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
    activityLabel: true
    activityModel: gpt-4.1-nano
    activityPhaseLabel: true
    activityPhaseMaxPerRun: 5
    skills:
      maxCatalogSkills: 20
    toolApproval:
      enabled: true
      mode: default
      deny: ['mcp:*:delete_*']
      ask: ['mcp:*:*']
    checkpointer:
      type: mongo
      ttl: 86400
    remoteApi:
      auth:
        oidc:
          enabled: false

This configuration enables the builder interface for agents.

recursionLimit

Default: 25

Example:

recursionLimit: 50

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

maxRecursionLimit

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.

Stream circuit breakers

These settings stop an Agent run when a provider stream appears to be producing runaway tool arguments or an unbounded sequence of delta events.

LibreChat uses a 64 KiB global argument limit and ships a 128 KiB override for create_file, whose legitimate payloads are often larger. Entries in maxToolCallArgBytesByTool merge over that built-in override. If either guard trips, LibreChat aborts the in-flight provider stream and reports which limit was exceeded.

maxToolCallArgBytes: 65536
maxDeltaEventsPerTurn: 100000
maxToolCallArgBytesByTool:
  create_file: 262144
  large_import: 524288

To disable every argument-size guard, set both the global limit and the shipped create_file override to 0:

maxToolCallArgBytes: 0
maxToolCallArgBytesByTool:
  create_file: 0

titleTiming

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

activityLabel

Set activityLabel: true to group each block of Agent reasoning and tool calls under a generated one-line header. Use activityModel, activityEndpoint, activityPrompt, activityMaxPerRun, and activityCharLimit to control the additional model call and its cost. See Agent Activity Groups for the full field reference and precedence rules.

activityLabel: true
activityEndpoint: openAI
activityModel: gpt-4.1-nano
activityMaxPerRun: 20
activityCharLimit: 600
activityPhaseLabel: true
activityPhaseMaxPerRun: 5

activityPhaseLabel can independently add one collapsed parent summary around each run phase that contains at least two logical activities. Use activityPhaseModel, activityPhaseEndpoint, activityPhasePrompt, and activityPhaseMaxPerRun to tune those calls; activityCharLimit is shared with child activity labels.

disableBuilder

Default: false

Example:

disableBuilder: false

allowedProviders

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

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

programmatic_tools, stateful_code_sessions, run_in_background, and tool_intents are opt-in and must be added explicitly. Programmatic tools and stateful sessions also require execute_code and a compatible Code Interpreter deployment. Background code execution requires run_in_background, execute_code, and Code Interpreter.

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'
  - 'memory'
  - 'ask_user_question'
  - 'tools'
  - 'chain'
  - 'ocr'
  # Optional: reuse one Code Interpreter workspace per conversation.
  # - 'stateful_code_sessions'
  # Optional: allow selected eligible MCP and Code Interpreter tools to run as background tasks.
  # - 'run_in_background'
  # Optional: show live model-written intent labels for native and selected MCP tools.
  # - 'tool_intents'

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

toolApproval

Controls human review for Agent tool calls. This feature is disabled by default. When enabled, matching calls pause until the user submits an allowed decision, such as approving, rejecting, or editing the arguments.

Patterns use glob matching. MCP tools can be scoped with mcp:<server>:<tool>; for example, mcp:github:* matches every tool from the github server. Evaluation gives deny the highest priority, including in bypass mode.

toolApproval:
  enabled: true
  mode: default
  allow:
    - 'mcp:analytics:read_*'
  deny:
    - 'mcp:*:delete_*'
  ask:
    - 'mcp:*:*'
  reason: 'Review {tool} before it runs.'

Hooks are loaded once at server startup and execute in the LibreChat process. Each entry accepts a module, an optional tool-name matcher regex, and an optional options object passed to the module's builder. Only load code you trust. Per-role or tenant overrides do not reload hook modules; implement contextual behavior inside the hook.

toolApproval:
  enabled: true
  hooks:
    - module: '@acme/librechat-approval-hook'
      matcher: '^mcp:production:'
      options:
        requireTicket: true

checkpointer

Configures storage for Agent runs paused by tool approval or Ask User. When either feature needs a checkpointer and this block is omitted, LibreChat uses the primary MongoDB with a 24-hour decision window.

checkpointer:
  type: mongo
  ttl: 86400

Use type: memory only for a single-process development deployment. A paused run stored in memory cannot resume after a restart or on another replica.

MongoDB checkpoints log a warning when serialized state exceeds 8 MiB and reject a durable pause above 15 MiB, leaving headroom below MongoDB's 16 MiB document limit. Large inlined media or tool outputs are common causes; start a new conversation or reduce its context if a run reports CHECKPOINT_TOO_LARGE.

skills

Controls endpoint-level Skills settings for agents.

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

Default: 30

Range: 1-50

Example:

maxCitations: 30

maxCitationsPerFile

Default: 7

Range: 1-10

Example:

maxCitationsPerFile: 7

minRelevanceScore

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.
• stateful_code_sessions: Lets opted-in agents reuse one Code Interpreter workspace per conversation. Requires execute_code, a compatible Code Interpreter deployment, and the per-agent Advanced setting. This capability is highly experimental, is not enabled by default, and may change substantially during experimentation; do not treat its current behavior or configuration as a stable production contract.
• 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.
• memory: Lets agents use set_memory and delete_memory when memory is configured and the user has access. Enabled by default; removed at runtime when memory is disabled.
• ask_user_question: Lets agents pause to ask one to four related questions in a single form and resume with the answers. Enabled by default.
• 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.
• run_in_background: Makes Code Interpreter execution and shell tools background-eligible by default and enables per-tool background opt-in for MCP tools. An agent can explicitly opt Code Interpreter out. The setting permits background execution; the model decides per call whether to use it. Requires execute_code and a configured Code Interpreter deployment for code. This capability is not enabled by default.
• tool_intents: Adds live model-written intent labels to eligible tool calls. Native tools, including Code Interpreter tools, opt in automatically; MCP tools can be enabled individually or in bulk in the Agent Builder. Model specs use describeIntent. This capability is not enabled by default.

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'
      # Optional: makes Code Interpreter background-eligible and enables selected MCP tools.
      # - 'run_in_background'
      # Optional: enables live intent labels for native and selected MCP tools.
      # - 'tool_intents'
      - '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
• Background tool calls remain disabled unless you add run_in_background; Code Interpreter tools then become eligible by default, while MCP tools still require per-tool selection
• Tool intent labels remain disabled unless you add tool_intents; native tools then opt in automatically, while MCP tools still require per-tool selection

remoteApi

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

remoteApi.auth

remoteApi.auth.apiKey

Default: true

remoteApi.auth.oidc

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

Subagents

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

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).