feat: custom variables for agents

[hmiranda-pt]

Summary

Adds support for custom variables in agent instructions so that external systems can pass arbitrary key-value pairs via URL query parameters (prefixed with custom_). These are persisted on the conversation and injected into agent instructions at runtime using {{variable_name}} placeholders. This enables dynamic customization of agent behavior without modifying the agent itself.

(e.g., ?agent_id=...&custom_region=us-east&custom_user_name=Alice).

The custom variables are persisted per-conversation to support multi-turn conversations.

Changes

Frontend (client/)

• useQueryParams.ts: Extracts custom_* query parameters from the URL, strips the prefix, and attaches them as customVariables on the preset passed to newConversation.
• ChatRoute.tsx: Excludes custom_* params from the parameter subset to prevent them from interfering with existing logic.

Shared (packages/data-provider/)

• parsers.ts: New replaceCustomVariables() function that substitutes placeholders in text with the provided custom variable values. Intentionally skips built-in special variables (current_date, current_user, etc.) to avoid conflicts.
• schemas.ts: Added a customVariables field (z.record(z.string()).optional()) to tConversationSchema and included it in compactAgentsBaseSchema.
• types.ts: Added customVariables to TEndpointOption.

Legacy Backend (api/)

• api/server/services/Endpoints/agents/build.js: Extracts customVariables from the parsed body and passes it into the agent build options.
• api/server/services/Endpoints/agents/initialize.js: Forwards customVariables from endpointOption to the AgentClient options.
• api/server/controllers/agents/client.js: Passes customVariables through to the run options.

Backend (packages/api/)

• packages/api/src/agents/initialize.ts: Calls replaceCustomVariables on the agent instructions after the special variable replacement, only when customVariables is present on the endpoint option.

Database (packages/data-schemas/)

• schema/defaults.ts: Added customVariables as a Map<String> field to the conversation Mongoose schema.
• types/convo.ts: Added customVariables to the IConversation interface.
• methods/conversation.ts: Changed toObject() to use { flattenMaps: true } so that customVariables is returned as a plain object instead of a Mongoose Map. Without this change, the Mongoose Map serializes to '{}' (even when it contains values), which causes the custom variables to be cleared in multi-turn conversations.

Change Type

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Testing

Manual Testing

1. Build both the frontend and the backend.
2. Start LibreChat.
3. Create an agent with an instruction that makes use of custom variables:
   • e.g.: "Always begin your replies with 'Dear {{name}} ({{department}}),'"
4. Take note of the agent ID.
5. Start a new conversation by placing the agent ID and custom variables in the URL and pressing enter:
   • e.g.: http://localhost:3080/c/new?agent_id=<AGENT_ID>&custom_name=Alice&custom_department=Engineering
6. Once the prompt input appears, the custom variables should be stripped from the URL.
7. Send a message to the agent — it should follow the instructions, and its reply should start with "Dear Alice (Engineering)".
8. Send another message to confirm that the custom variables are persisted across multi-turn conversations.

Unit Testing

• cd client && npx jest useQueryParams.spec.ts
• cd packages/api && npx jest initialize.test.ts
• cd packages/data-provider && npx jest parsers.spec.ts
• cd packages/data-schemas && npx jest conversation.spec.ts

Test Configuration:

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• I have made pertinent documentation changes
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes
• A pull request for updating the documentation has been submitted.

[hmiranda-pt]

Related to discussion: #12695