feat: Configurable default agent for through the librechat.yaml config file

[jogamned]

Add default_agent Configuration for Agents Endpoint

Summary

Implements a new default_agent configuration option in endpoints.agents that allows administrators to specify a default agent for user sessions. When configured, users are automatically directed to this agent when they log into the platform.

Context: This feature streamlines the user experience by allowing organizations to set a preferred default agent, ensuring users start with a specific agent on login without manual selection.

Change Type

• Feature (new functionality)
• Backend changes
• Frontend changes
• Configuration schema update
• Tests added

Changes Overview

Backend Changes

Configuration Schema (packages/data-provider/src/config.ts)

• Added default_agent: z.string().optional() to agentsEndpointSchema
• Added defaultAgent?: string | null to TStartupConfig type
• Enables configuration validation and type safety

API Service (api/server/routes/config.js)

• Exposed defaultAgent in startup config endpoint: config?.endpoints?.agents?.default_agent ?? null
• Makes default_agent available to frontend via /api/config endpoint

Tests (api/server/services/AppService.spec.js)

• Test 1: Verifies default_agent is correctly read from endpoints.agents configuration
• Test 2: Validates graceful handling when default_agent is omitted
• Both tests ensure processed endpoint includes default agent settings

Frontend Changes

Default Endpoint Logic (client/src/utils/getDefaultEndpoint.ts)

• New priority: Added early check for default_agent configuration
• When startupConfig.defaultAgent exists AND agents endpoint is configured, returns agents endpoint
• Existing priority chain (convoSetup → localStorage → first defined endpoint) remains unchanged
• New function getDefaultAgentFromConfig(): Extracts agent ID when on agents endpoint

Session Initialization (client/src/hooks/useNewConvo.ts)

• Integrated getDefaultAgentFromConfig() to automatically set conversation.agent_id on login
• Applied when isAgentsEndpoint(defaultEndpoint) is true
• Ensures seamless agent selection during session initialization

Utility Exports (client/src/utils/index.ts)

• Exported getDefaultAgentFromConfig for use across application

Tests

Comprehensive Test Suite (client/src/utils/getDefaultEndpoint.spec.ts)

253 lines of test coverage including:

getDefaultEndpoint tests:

• ✅ Returns agents endpoint when defaultAgent is configured
• ✅ Prioritizes defaultAgent over other endpoints
• ✅ Falls back to normal behavior when agents endpoint not configured
• ✅ Respects defaultAgent even with localStorage set to different endpoint
• ✅ Respects defaultAgent even with convoSetup set to different endpoint
• ✅ Handles undefined startupConfig
• ✅ Standard behavior without default_agent (convoSetup, localStorage, first endpoint)

getDefaultAgentFromConfig tests:

• ✅ Returns agent ID on agents endpoint with configured defaultAgent
• ✅ Returns null for non-agents endpoints
• ✅ Returns null when endpoint is null
• ✅ Returns null when defaultAgent not configured
• ✅ Returns null when startupConfig is undefined

Configuration & Documentation

Configuration Example (librechat.example.yaml)

• Version bump: 1.2.1 → 1.2.2
• Added documentation for default_agent option in agents section
• Clear usage instructions and requirements

endpoints:
  agents:
    # Default agent for new conversations
    # Specify agent ID users will be directed to on login
    # agents must be first endpoint in list
    # default_agent: "agent_8jxdBTEJiX5dTrSbz7yl7"

Testing

Unit Tests

• Backend: 2 tests in AppService.spec.js - default_agent reading and handling
• Frontend: 14 tests in getDefaultEndpoint.spec.ts - complete coverage of priority logic

Manual Testing

• Verified default agent selection on user login
• Tested fallback behavior when default_agent not configured
• Confirmed existing functionality (convoSetup, localStorage) remains intact
• Validated graceful handling of missing agents endpoint

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated (librechat.example.yaml)
• Unit tests added with full coverage
• Tests pass locally
• No breaking changes introduced
• Type safety maintained (TypeScript, Zod schemas)
• Backward compatible (feature is optional)

Additional Notes

Priority Hierarchy:

1. startupConfig.defaultAgent (highest priority when agents endpoint exists)
2. convoSetup.endpoint (unchanged)
3. localStorage.lastConversationSetup (unchanged)
4. First defined endpoint (fallback, unchanged)

Requirements:

• Agents endpoint must be configured in endpointsConfig
• default_agent is optional - system works normally without it
• No changes required to existing conversations or workflows