Skip to main content
LibreChat’s Agents feature provides powerful autonomous AI assistants that can use tools, search files, execute code, and chain operations to accomplish complex tasks.

​
Overview

Agents are AI-powered assistants that can:

Use Tools

Execute code, search the web, call APIs, and use custom tools

Search Files

Find and analyze information across uploaded documents

Chain Operations

Hand off to specialized agents for multi-step workflows

Maintain Context

Remember conversation history and file attachments

​
Creating Agents

Agents can be created through the UI or configured in your librechat.yaml:

​
Through the UI

1

Click New Agent

Click the “New Agent” button in the interface
2

Configure Agent

Set name, description, instructions, and model
3

Add Capabilities

Enable tools like code execution, file search, web search
4

Save and Use

Save your agent and start chatting

​
Through Configuration

Configure agent capabilities in librechat.yaml:
librechat.yaml
endpoints:
  agents:
    # Recursion limits for agent operations
    recursionLimit: 50
    maxRecursionLimit: 100
    
    # Disable the builder interface
    disableBuilder: false
    
    # Citation settings
    maxCitations: 30
    maxCitationsPerFile: 7
    minRelevanceScore: 0.45
    
    # Available capabilities
    capabilities:
      - deferred_tools
      - execute_code
      - file_search
      - actions
      - tools

​
Agent Capabilities

​
Execute Code

Agents can write and execute Python code to analyze data, perform calculations, and generate visualizations: 
# Agent can analyze data from uploaded files
import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv('sales_data.csv')
print(df.describe())
plt.plot(df['month'], df['revenue'])
plt.savefig('revenue_trend.png')
Configuration in agent tool resources: 
tool_resources: {
  execute_code: {
    file_ids: ['file-123', 'file-456']
  }
}
Agents can search through uploaded documents using vector embeddings:
  1. Upload Documents: Attach PDFs, text files, code files
  2. Vector Indexing: Files are automatically indexed with embeddings
  3. Semantic Search: Agent searches using natural language queries
  4. Citation Generation: Results include source citations with page numbers
Configure file search resources: 
tool_resources: {
  file_search: {
    vector_stores: [
      {
        file_ids: ['file-789', 'file-012'],
        name: 'Company Documentation'
      }
    ]
  }
}
Citation Settings:
​
maxCitations
number
default:"30"
Maximum total citations to include in responses
​
maxCitationsPerFile
number
default:"7"
Maximum citations from a single file
​
minRelevanceScore
number
default:"0.45"
Minimum relevance threshold (0.0-1.0) for including sources
Agents can search the web and retrieve current information:
librechat.yaml
webSearch:
  # Search provider
  serperApiKey: '${SERPER_API_KEY}'
  searxngInstanceUrl: '${SEARXNG_INSTANCE_URL}'
  
  # Content scraper
  firecrawlApiKey: '${FIRECRAWL_API_KEY}'
  firecrawlApiUrl: '${FIRECRAWL_API_URL}'
  
  # Reranking
  jinaApiKey: '${JINA_API_KEY}'
  cohereApiKey: '${COHERE_API_KEY}'
Enable web search in agent capabilities: 
tools: ['web_search']

​
Actions (API Calls)

Agents can call external APIs using OpenAPI specifications:
librechat.yaml
actions:
  allowedDomains:
    - 'swapi.dev'
    - 'api.example.com'
    - 'https://secure.api.com:8443'
SSRF Protection: If not configured, SSRF targets (localhost, private IPs) are blocked. To allow internal targets, explicitly add them to allowedDomains.
Add actions to your agent: 
actions: [
  {
    name: 'Get Weather',
    description: 'Fetch current weather data',
    url: 'https://api.weather.com/openapi.json'
  }
]

​
Deferred Tools

Tools can be loaded on-demand for better performance: 
tool_options: {
  defer_loading: true  // Load tools only when needed
}
Deferred tools improve agent initialization time by loading tool definitions only when they’re about to be used.

​
Agent Providers

Agents work with multiple AI providers: 
provider: openAI
model: gpt-4o
model_parameters:
  temperature: 0.7
  max_tokens: 4000

​
Agent Chaining

Agents can hand off to other specialized agents: 
// Main agent configuration
{
  name: 'Main Assistant',
  instructions: 'General purpose assistant that delegates to specialists',
  tools: ['chain'],
  handoff_agents: ['code-specialist', 'research-specialist']
}

// Specialist agent
{
  id: 'code-specialist',
  name: 'Code Specialist',
  instructions: 'Expert in code analysis and debugging',
  tools: ['execute_code', 'file_search']
}
1

User Request

User asks a question to the main agent
2

Agent Analysis

Main agent determines which specialist is needed
3

Handoff

Main agent hands off to the specialist agent
4

Specialist Response

Specialist completes the task and returns results

​
Tool Resources

Agents can access uploaded files through tool resources:

​
Execute Code Files

tool_resources: {
  execute_code: {
    files: [
      { file_id: 'file-123', filename: 'data.csv' },
      { file_id: 'file-456', filename: 'analysis.py' }
    ]
  }
}

​
File Search Vectors

tool_resources: {
  file_search: {
    vector_stores: [
      {
        file_ids: ['file-789', 'file-012'],
        name: 'Documentation',
        metadata: {
          category: 'technical'
        }
      }
    ]
  }
}

​
Agent Permissions

Control agent access through the interface configuration:
librechat.yaml
interface:
  agents:
    use: true      # Allow users to use agents
    create: true   # Allow users to create agents
    share: false   # Allow sharing with other users
    public: false  # Allow public sharing

​
Advanced Configuration

​
Recursion Control

​
recursionLimit
number
default:"25"
Default recursion depth for agent operations
​
maxRecursionLimit
number
default:"25"
Maximum allowed recursion depth

​
Context Management

model_parameters: {
  maxContextTokens: 100000,  // Maximum context window
  resendFiles: true          // Resend files in conversation
}

​
Custom Instructions

Provide detailed instructions to guide agent behavior: 
instructions: |
  You are a senior software engineer specializing in Python and data analysis.
  
  When analyzing code:
  - Always check for edge cases
  - Provide detailed explanations
  - Suggest optimizations
  
  When working with data:
  - Validate data quality first
  - Use appropriate visualizations
  - Document your assumptions

​
Example Agents

name: Data Analyst
provider: openAI
model: gpt-4o
instructions: |
  You are an expert data analyst. Analyze uploaded datasets,
  create visualizations, and provide insights.
tools:
  - execute_code
  - file_search
tool_resources:
  execute_code:
    file_ids: []

name: Research Assistant
provider: anthropic
model: claude-4.5-sonnet
instructions: |
  You are a research assistant. Search documents and the web
  to find accurate, well-cited information.
tools:
  - file_search
  - web_search
tool_resources:
  file_search:
    vector_stores:
      - name: Research Papers

name: Code Reviewer
provider: openAI
model: gpt-4o
instructions: |
  You are a senior code reviewer. Analyze code for bugs,
  security issues, and style improvements.
tools:
  - execute_code
  - file_search
model_parameters:
  temperature: 0.3

​
Best Practices

Clear Instructions: Provide specific, detailed instructions for best agent performance
Tool Selection: Only enable tools the agent actually needs to reduce token usage
Recursion Limits: Set appropriate limits to prevent infinite loops in agent chains
File Management: Keep file sets focused and relevant to the agent’s purpose

Code Interpreter

Execute Python code and analyze data

File Search

Search and analyze uploaded documents

Web Search

Search the web for current information

MCP

Model Context Protocol tool integration

Build docs developers (and LLMs) love

Get started for freeTalk to us