diff --git a/pages/docs/configuration/librechat_yaml/object_structure/agents.mdx b/pages/docs/configuration/librechat_yaml/object_structure/agents.mdx
index 0ce7c5300..cbac6b461 100644
--- a/pages/docs/configuration/librechat_yaml/object_structure/agents.mdx
+++ b/pages/docs/configuration/librechat_yaml/object_structure/agents.mdx
@@ -12,8 +12,39 @@ endpoints:
     disableBuilder: false
     # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
     # capabilities: ["execute_code", "file_search", "actions", "tools", "artifacts", "ocr", "chain", "web_search"]
+    # (optional) YAML-defined agents that are automatically synced to the database
+    definitions:
+      - id: "librechat-assistant"
+        name: "LibreChat Assistant"
+        description: "AI assistant specialized in LibreChat"
+        projects: "instance" # Optional: defaults to "instance" if omitted
+        instructions: |
+          You are a LibreChat assistant specialized in analyzing LibreChat and finding information.
+          You have access to uploaded knowledge base files and can search through them to find relevant information.
+
+          When answering questions:
+          - Search through the available files first
+          - Cite your sources when possible
+          - Provide comprehensive, well-researched answers
+          - If information isn't available in the files, clearly state that
+        provider: "openai"
+        model: "gpt-4o-mini"
+        tools:
+        - "file_search"
+        tool_resources:
+          file_search:
+            files:
+            - filepath: "./README.md"
+              filename: "README.md"
+              description: "LibreChat README"
+            - filepath: "./.github/CODE_OF_CONDUCT.md"
+              filename: "CODE_OF_CONDUCT.md"
+              description: "LibreChat code of conduct"
+            - filepath: "./.github/CONTRIBUTING.md"
+              filename: "CONTRIBUTING.md"
+              description: "LibreChat contributing guidelines"
 ```
-> This configuration enables the builder interface for agents.
+> This configuration enables the builder interface for agents and defines a YAML-configured agent.
 
 ## recursionLimit
 
@@ -121,24 +152,448 @@ The `capabilities` field allows you to enable or disable specific functionalitie
 
 By specifying the capabilities, you can control the features available to users when interacting with agents.
 
+## definitions
+
+<OptionTable
+  options={[
+    ['definitions', 'Array/List of Objects', 'Defines agents that are automatically synced to the database from YAML configuration.', 'YAML-defined agents are read-only in the UI and automatically managed by the system. They are synced on each application startup.'],
+  ]}
+/>
+
+**Default:** `[]` (empty list, no YAML-defined agents)
+
+**Example:**
+```yaml filename="endpoints / agents / definitions"
+definitions:
+  - id: "research-assistant"
+    name: "Research Assistant"
+    description: "Specialized research agent with file search capabilities"
+    provider: "openai"
+    model: "gpt-4o"
+    tools:
+      - "file_search"
+    tool_resources:
+      file_search:
+        files:
+          - filepath: "./documents/research.pdf"
+            filename: "research.pdf"
+            description: "Research documentation"
+```
+
+### Agent Definition Fields
+
+Each agent definition in the `definitions` array supports the following fields:
+
+#### id (required)
+
+<OptionTable
+  options={[
+    ['id', 'String', 'Unique identifier for the agent.', 'Must be unique across all agents in the system.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / id"
+id: "my-custom-agent"
+```
+
+#### name
+
+<OptionTable
+  options={[
+    ['name', 'String', 'Display name for the agent.', 'If omitted, the agent ID will be used as the display name.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / name"
+name: "My Custom Agent"
+```
+
+#### description
+
+<OptionTable
+  options={[
+    ['description', 'String', 'Description of the agent and its purpose.', 'Displayed in the agent selection interface.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / description"
+description: "A specialized agent for handling customer support queries"
+```
+
+#### instructions
+
+<OptionTable
+  options={[
+    ['instructions', 'String', 'System instructions that define the agent\'s behavior and personality.', 'Supports multiline strings using YAML literal scalar syntax (|).'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / instructions"
+instructions: |
+  You are a helpful assistant specialized in technical documentation.
+  Always provide clear, accurate, and well-structured responses.
+  When uncertain, ask for clarification rather than making assumptions.
+```
+
+#### provider (required)
+
+<OptionTable
+  options={[
+    ['provider', 'String', 'The AI provider to use for this agent.', 'Must be one of the configured providers in your system.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / provider"
+provider: "openai"
+```
+
+#### model (required)
+
+<OptionTable
+  options={[
+    ['model', 'String', 'The specific model to use for this agent.', 'Must be available for the specified provider.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / model"
+model: "gpt-4o"
+```
+
+#### model_parameters
+
+<OptionTable
+  options={[
+    ['model_parameters', 'Object', 'Model-specific parameters such as temperature, max_tokens, etc.', 'Parameters available depend on the provider and model.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / model_parameters"
+model_parameters:
+  temperature: 0.7
+  max_tokens: 2000
+  top_p: 0.9
+```
+
+#### tools
+
+<OptionTable
+  options={[
+    ['tools', 'Array/List of Strings', 'List of tools available to the agent.', 'Must be from the available capabilities: execute_code, file_search, actions, tools, artifacts, ocr, chain, web_search.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / tools"
+tools:
+  - "file_search"
+  - "execute_code"
+  - "web_search"
+```
+
+#### agent_ids
+
+<OptionTable
+  options={[
+    ['agent_ids', 'Array/List of Strings', 'List of other agent IDs that this agent can collaborate with.', 'Enables multi-agent workflows.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / agent_ids"
+agent_ids:
+  - "research-agent"
+  - "writing-agent"
+```
+
+#### artifacts
+
+<OptionTable
+  options={[
+    ['artifacts', 'String', 'Artifacts mode configuration.', 'Controls artifact generation behavior. Options: "", "default", "shadcnui", "custom".'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / artifacts"
+artifacts: "default"
+```
+
+#### recursion_limit
+
+<OptionTable
+  options={[
+    ['recursion_limit', 'Number', 'Maximum number of steps this agent can take in a run.', 'Overrides the global recursion limit for this specific agent.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / recursion_limit"
+recursion_limit: 30
+```
+
+#### end_after_tools
+
+<OptionTable
+  options={[
+    ['end_after_tools', 'Boolean', 'Whether to end the agent run after tool execution.', 'When true, the agent will stop after executing tools rather than continuing.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / end_after_tools"
+end_after_tools: false
+```
+
+#### hide_sequential_outputs
+
+<OptionTable
+  options={[
+    ['hide_sequential_outputs', 'Boolean', 'Whether to hide intermediate outputs in multi-step processes.', 'When true, only the final output is shown to the user.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / hide_sequential_outputs"
+hide_sequential_outputs: false
+```
+
+#### conversation_starters
+
+<OptionTable
+  options={[
+    ['conversation_starters', 'Array/List of Strings', 'Suggested conversation starters for the agent.', 'Displayed as clickable prompts in the user interface.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / conversation_starters"
+conversation_starters:
+  - "What can you help me with?"
+  - "Analyze this document"
+  - "Help me research this topic"
+```
+
+#### isCollaborative
+
+<OptionTable
+  options={[
+    ['isCollaborative', 'Boolean', 'Whether this agent can be used collaboratively by multiple users.', 'When true, the agent can be shared across users and projects.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / isCollaborative"
+isCollaborative: false
+```
+
+#### projects
+
+<OptionTable
+  options={[
+    ['projects', 'String or Array/List of Strings', 'Project(s) this agent belongs to.', 'Can be a single project name or an array of project names. Defaults to "instance" if omitted.'],
+  ]}
+/>
+
+**Examples:**
+```yaml filename="Agent Definition / projects (single)"
+projects: "instance"
+```
+
+```yaml filename="Agent Definition / projects (multiple)"
+projects:
+  - "instance"
+  - "research-team"
+  - "customer-support"
+```
+
+#### tool_resources
+
+<OptionTable
+  options={[
+    ['tool_resources', 'Object', 'Configuration for tool-specific resources such as files.', 'Supports file_search, execute_code, and ocr tool resources.'],
+  ]}
+/>
+
+The `tool_resources` field allows you to configure resources for specific tools. Currently supported:
+
+##### file_search
+
+<OptionTable
+  options={[
+    ['file_search', 'Object', 'Configuration for file search capabilities.', 'Allows pre-loading files that the agent can search through.'],
+  ]}
+/>
+
+**Subfields:**
+- `files`: Array of file configurations
+
+**File Configuration:**
+- `filepath` (required): Path to the file relative to the LibreChat root directory or absolute path
+- `filename` (optional): Display name for the file. If omitted, uses the basename of the filepath
+- `description` (optional): Description of the file's contents
+
+**Example:**
+```yaml filename="Agent Definition / tool_resources / file_search"
+tool_resources:
+  file_search:
+    files:
+      - filepath: "./docs/README.md"
+        filename: "README.md"
+        description: "Main documentation file"
+      - filepath: "/absolute/path/to/file.pdf"
+        filename: "manual.pdf"
+        description: "User manual"
+```
+
+##### execute_code
+
+<OptionTable
+  options={[
+    ['execute_code', 'Object', 'Configuration for code execution capabilities.', 'Allows pre-loading code files that the agent can access.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / tool_resources / execute_code"
+tool_resources:
+  execute_code:
+    files:
+      - filepath: "./scripts/helper.py"
+        filename: "helper.py"
+        description: "Helper functions"
+```
+
+##### ocr
+
+<OptionTable
+  options={[
+    ['ocr', 'Object', 'Configuration for OCR (Optical Character Recognition) capabilities.', 'Allows pre-loading image and document files for text extraction.'],
+  ]}
+/>
+
+**Example:**
+```yaml filename="Agent Definition / tool_resources / ocr"
+tool_resources:
+  ocr:
+    files:
+      - filepath: "./images/document.png"
+        filename: "document.png"
+        description: "Scanned document"
+```
+
+### Complete Agent Definition Example
+
+```yaml filename="Complete Agent Definition"
+definitions:
+  - id: "research-assistant"
+    name: "Research Assistant"
+    description: "Advanced research agent with comprehensive capabilities"
+    instructions: |
+      You are a research assistant specialized in analyzing documents and providing insights.
+      
+      Your capabilities include:
+      - Searching through uploaded documents
+      - Executing code for data analysis
+      - Performing web searches for current information
+      - Extracting text from images and PDFs
+      
+      Always provide well-sourced, accurate information and cite your sources.
+    provider: "openai"
+    model: "gpt-4o"
+    model_parameters:
+      temperature: 0.3
+      max_tokens: 4000
+    tools:
+      - "file_search"
+      - "execute_code"
+      - "web_search"
+      - "ocr"
+    tool_resources:
+      file_search:
+        files:
+          - filepath: "./research/papers/ai_trends.pdf"
+            filename: "AI Trends 2024"
+            description: "Latest AI research trends"
+          - filepath: "./research/data/statistics.csv"
+            filename: "Research Statistics"
+            description: "Statistical data for analysis"
+      execute_code:
+        files:
+          - filepath: "./scripts/analysis.py"
+            filename: "analysis.py"
+            description: "Data analysis utilities"
+      ocr:
+        files:
+          - filepath: "./images/charts.png"
+            filename: "Research Charts"
+            description: "Research visualization charts"
+    conversation_starters:
+      - "Analyze the latest AI trends"
+      - "Help me understand this research data"
+      - "Search for current information on this topic"
+    projects:
+      - "instance"
+      - "research-team"
+    recursion_limit: 40
+    isCollaborative: true
+```
+
 ## Example Configuration
 
-Here is an example of configuring the `agents` endpoint with custom capabilities:
+Here is an example of configuring the `agents` endpoint with custom capabilities and YAML-defined agents:
 
 ```yaml filename="Agents Endpoint"
 endpoints:
   agents:
+    recursionLimit: 50
+    maxRecursionLimit: 100
     disableBuilder: false
     capabilities:
       - "execute_code"
+      - "file_search"
       - "actions"
       - "artifacts"
       - "ocr"
       - "web_search"
+    definitions:
+      - id: "support-agent"
+        name: "Customer Support Agent"
+        description: "Specialized in handling customer inquiries"
+        provider: "openai"
+        model: "gpt-4o-mini"
+        instructions: |
+          You are a customer support agent. Be helpful, professional, and empathetic.
+          Always try to resolve issues efficiently and escalate when necessary.
+        tools:
+          - "file_search"
+          - "web_search"
+        tool_resources:
+          file_search:
+            files:
+              - filepath: "./support/faq.md"
+                filename: "FAQ"
+                description: "Frequently asked questions"
+              - filepath: "./support/policies.pdf"
+                filename: "Policies"
+                description: "Company policies"
+        conversation_starters:
+          - "How can I help you today?"
+          - "Tell me about your issue"
+          - "What product are you having trouble with?"
+        projects: "instance"
 ```
 
-In this example, the builder interface for agents is disabled, and only the `execute_code`, `actions`, `ocr`, and `web_search` capabilities are enabled.
-
 ## Notes
 
-- It's not recommended to disable the builder interface unless you are using [modelSpecs](/docs/configuration/librechat_yaml/object_structure/model_specs) to define a list of agents to choose from.
+- It's not recommended to disable the builder interface unless you are using [modelSpecs](/docs/configuration/librechat_yaml/object_structure/model_specs) to define a list of agents to choose from or have YAML-defined agents available.
+- YAML-defined agents are automatically synchronized on startup and cannot be modified through the UI.
+- File paths in `tool_resources` can be relative to the LibreChat root directory or absolute paths.
+- Files are automatically processed and embedded when first accessed by a user.
+- Changes to YAML-defined agents require an application restart to take effect.
diff --git a/pages/docs/features/agents.mdx b/pages/docs/features/agents.mdx
index e2649e827..9cc426373 100644
--- a/pages/docs/features/agents.mdx
+++ b/pages/docs/features/agents.mdx
@@ -28,6 +28,34 @@ The creation form includes:
 
 ![Agents - Mention](/images/agents/mention.png)
 
+## YAML-Defined Agents
+
+LibreChat supports YAML-defined agents - pre-configured agents that are automatically synchronized from your configuration file. These agents offer several advantages:
+
+### Features
+
+- **System-Managed**: Automatically created and updated from your `librechat.yaml` configuration
+- **Pre-Configured Resources**: Can include pre-loaded files for file search, code execution, and OCR
+- **Read-Only Interface**: Displayed in the UI but cannot be modified through the web interface
+- **Consistent Across Deployments**: Perfect for organizational standards and shared workflows
+- **Automatic File Processing**: Files specified in the configuration are automatically processed and embedded
+
+### Using YAML-Defined Agents
+
+1. **Select the Agent**: Choose a YAML-defined agent from the dropdown in the Side Panel
+2. **View Configuration**: You can see the agent's settings but cannot modify them
+3. **Duplicate for Customization**: Create your own editable copy by duplicating the agent
+4. **Direct Usage**: Use the agent immediately without any additional setup
+
+### Benefits
+
+- **Consistency**: Ensures all users have access to the same high-quality agents
+- **Maintenance**: Administrators can update agents centrally without individual user intervention
+- **Resource Management**: Files and configurations are managed at the system level
+- **Deployment**: Easy to distribute standardized agents across teams or organizations
+
+For configuration details, see the [Agents Configuration Guide](/docs/configuration/librechat_yaml/object_structure/agents#definitions).
+
 ### Model Configuration
 
 The model parameters interface allows fine-tuning of your agent's responses: