Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import type { LocatorTraversalReporter } from '../../protection/diagnostics';
/**
* OpenAI-compatible chat completions service for agents.
*
* This service provides an OpenAI v1/chat/completions compatible API for
* interacting with LibreChat agents. The agent_id is passed as the "model"
* parameter per OpenAI spec.
*
* Usage:
* ```typescript
* import { createAgentChatCompletion } from '@librechat/api';
*
* // In your Express route handler:
* app.post('/v1/chat/completions', async (req, res) => {
* await createAgentChatCompletion(req, res, {
* getAgent: db.getAgent,
* // ... other dependencies
* });
* });
* ```
*/
import { nanoid } from 'nanoid';
import { AgentCapabilities, EModelEndpoint } from 'librechat-data-provider';
import type {
FiltersConfig,
MessageFilterConfig,
MessageFilterPiiConfig,
StatefulCodeEnvironment,
TAgentsEndpoint,
} from 'librechat-data-provider';
import type { Response as ServerResponse, Request } from 'express';
import type {
ChatCompletionResponse,
OpenAIResponseContext,
ChatCompletionRequest,
OpenAIErrorResponse,
CompletionUsage,
ChatMessage,
ToolCall,
} from './types';
import type {
ExternalChatMessage,
ExternalMessagePart,
ContentTraversalLimitError,
TextContentFragment,
FileContentInput,
} from '~/protection';
import type { InitializeAgentParams as CoreInitializeAgentParams } from '../initialize';
import type { OpenAIStreamWriterConfig, EventHandler } from './handlers';
import type { LangfuseTraceContext } from '~/langfuse/identity';
import type { MCPRuntimeRequestBody } from '~/mcp/request';
import type { ToolExecuteOptions } from '../handlers';
import {
extractMessageContent,
extractModelParameterContent,
getBlockedOpaqueFileField,
getContentTraversalFragments,
inspectContent,
isContentTraversalProtected,
isContentTraversalLimitError,
} from '~/protection';
import {
createOpenAIContentAggregator,
createOpenAIStreamTracker,
createOpenAIHandlers,
completeOpenAIToolCalls,
sendFinalChunk,
createChunk,
writeSSE,
} from './handlers';
import {
assertModelBoundContent,
hasModelBoundContentProtection,
} from '~/middleware/modelBoundContent';
import { contentFilterBlockResponse, isContentFilterError } from '~/middleware/contentFilter';
import { contentFilterUninspectableResponse } from '~/protection/files';
import { resolveToolRoleGrants } from '../../tools/rolePermissions';
import { createMCPRuntimeRequestBody } from '~/mcp/request';
import { getUserFacingProviderError } from '../errors';
import { collectReachableAgents } from '../traversal';
import { resolveRecursionLimit } from '../config';
import { getDynamicToolContexts } from '../hitl';
import { createSafeUser } from '~/utils';
/**
* Dependencies for the chat completion service
*/
export interface ChatCompletionDependencies {
readonly onTraversalFailure?: LocatorTraversalReporter;
/** Get agent by ID */
getAgent: (params: { id: string }) => Promise<Agent | null>;
/** Initialize agent for use */
initializeAgent: (params: InitializeAgentParams) => Promise<InitializedAgent>;
/** Load agent tools */
loadAgentTools?: LoadToolsFn;
/** Get models config */
getModelsConfig?: (req: Request) => Promise<unknown>;
/** Validate agent model */
validateAgentModel?: (
params: unknown,
) => Promise<{ isValid: boolean; error?: { message: string } }>;
/** Log violation */
logViolation?: (
req: Request,
res: ServerResponse,
type: string,
info: unknown,
score: number,
) => Promise<void>;
/** Create agent run */
createRun?: CreateRunFn;
/**
* App config. Optional for basic chat, but required for source-aware content
* protection, tenant-scoped Langfuse fanout, and agents with `execute_code`
* in their tools. Filter policy and tenant Langfuse keys are forwarded to
* `createRun`, and the helper derives `codeEnvAvailable` from
* `appConfig?.endpoints?.agents?.capabilities` and forwards it into
* `deps.initializeAgent`. When `appConfig` is omitted, the resolved
* `codeEnvAvailable` is `undefined`, so `initializeAgent` skips the
* `execute_code` → `bash_tool` + `read_file` expansion entirely and
* code-requesting agents silently lose sandbox tools. Pass `appConfig`
* (even a minimal shape with just `endpoints.agents.capabilities`) to
* keep tenant tracing and code execution working.
*/
appConfig?: AppConfig;
/**
* Supply to have `codeEnvAvailable` and `fileSearchAvailable` respect the
* caller's `RUN_CODE` / `FILE_SEARCH` grants as well as the deployment
* capabilities. Optional so existing embedders keep their current behavior;
* without it this route is gated by capability alone.
*/
getRoleByName?: Parameters<typeof resolveToolRoleGrants>[0]['getRoleByName'];
/** Tool execute options for event-driven tool execution */
toolExecuteOptions?: ToolExecuteOptions;
/**
* Resolves an agent's `instructionsPrompt` link. Unlike `getRoleByName`,
* this has no default resolution path — the embedder must build it (a
* prompt service, cache, and logger) and supply it here for a linked agent
* to receive resolved instructions instead of falling back to empty.
*/
resolveLinkedInstructions?: CoreInitializeAgentParams['resolveLinkedInstructions'];
/** Forwarded to `initializeAgent`; defaults to `true` when omitted. */
recordLinkedPromptUsage?: CoreInitializeAgentParams['recordLinkedPromptUsage'];
}
/**
* Agent type from librechat-data-provider
*/
interface Agent {
id: string;
name?: string;
model?: string;
provider: string;
tools?: string[];
instructions?: string;
model_parameters?: Record<string, unknown>;
tool_resources?: Record<string, unknown>;
tool_options?: Record<string, unknown>;
[key: string]: unknown;
}
interface InitializedFile extends FileContentInput {
file_id?: string;
}
/**
* Initialized agent type - note: after initialization, tools become structured tool objects
*/
interface InitializedAgent {
id: string;
name?: string;
model?: string;
provider: string;
/** After initialization, tools are structured tool objects, not strings */
tools: unknown[];
instructions?: string;
model_parameters?: Record<string, unknown>;
tool_resources?: Record<string, unknown>;
tool_options?: Record<string, unknown>;
attachments: InitializedFile[];
requestAttachments?: InitializedFile[];
agentContextAttachments?: InitializedFile[];
toolContextMap: Record<string, unknown>;
dynamicToolContextMap?: Record<string, unknown>;
maxContextTokens: number;
userMCPAuthMap?: Record<string, Record<string, string>>;
subagentAgentConfigs?: InitializedAgent[];
/** Names of tools with the host-injected `intent` label param (see `agents/intent.ts`). */
intentToolNames?: string[];
recursion_limit?: number;
[key: string]: unknown;
}
/**
* Initialize agent params
*/
interface InitializeAgentParams {
req: Request;
res: ServerResponse;
/** Cancellation signal owned by this chat-completion request. */
signal?: CoreInitializeAgentParams['signal'];
agent: Agent;
conversationId?: string | null;
parentMessageId?: string | null;
requestBody?: MCPRuntimeRequestBody;
requestFiles?: unknown[];
loadTools?: NonNullable<CoreInitializeAgentParams['loadTools']>;
endpointOption?: Record<string, unknown>;
allowedProviders: Set<string>;
isInitialAgent?: boolean;
/**
* Whether the `execute_code` capability is enabled for the run.
* `initializeAgent` uses this to expand `agent.tools: ['execute_code']`
* into the `bash_tool` + `read_file` pair — if the caller's injected
* `initializeAgent` implementation consults this flag, agents configured
* for code execution will keep working post-Phase-8. Absent / `undefined`
* skips the expansion (same semantics as the in-repo controllers).
*/
codeEnvAvailable?: boolean;
/**
* Whether `file_search` is available to this caller — the capability AND, when
* the embedder wires `getRoleByName`, the `FILE_SEARCH` grant. Read only when
* re-hydrating a conversation's prior-turn files; absent / `undefined` leaves
* that priming unconditional.
*/
fileSearchAvailable?: boolean;
/**
* Resolves the `WEB_SEARCH` role grant. `initializeAgent` calls it only when an
* agent's built provider config turns native web search on, and strips that
* search when it resolves `false`.
*/
resolveWebSearchGrant?: () => Promise<boolean>;
/**
* Resolves this agent's `instructionsPrompt` link (a linked native or Langfuse
* prompt group). `initializeAgent` calls it only when the agent carries a
* resolvable link; absent, a linked agent falls back to empty instructions
* with a warning, since there is no default resolution path.
*/
resolveLinkedInstructions?: CoreInitializeAgentParams['resolveLinkedInstructions'];
/** Forwarded to `initializeAgent`; defaults to `true` when omitted. */
recordLinkedPromptUsage?: CoreInitializeAgentParams['recordLinkedPromptUsage'];
/**
* Whether the admin-level `stateful_code_sessions` capability is enabled.
* Threaded to `initializeAgent` alongside `codeEnvAvailable` so this
* OpenAI-compatible route resolves stateful sessions identically to the
* in-repo controllers; absent / `undefined` disables the feature.
*/
statefulSessionsAvailable?: boolean;
/** Deployment allowlist carried explicitly because this route's Request has no req.config. */
allowedStatefulCodeEnvironments?: readonly StatefulCodeEnvironment[];
/**
* Whether the admin-level `run_in_background` capability is enabled.
* Gates `applyBackgroundToolCalls` in `initializeAgent` (the injected
* `run_in_background` param + the `check_background_task` poll tool);
* absent / `undefined` disables background tool calls on this route.
*/
backgroundToolsAvailable?: boolean;
/**
* Whether the admin-level `tool_intents` capability is enabled. Gates
* `applyIntentLabels` in `initializeAgent` (the injected `intent` label
* param); absent / `undefined` disables intent labels on this route.
*
* Boundary: injection and the capability-off sanitize operate on the
* `toolDefinitions`/`toolRegistry` surfaces. A custom `LoadToolsFn` that
* returns only structured tool INSTANCES bypasses both — such loaders
* must provide definition/registry surfaces to participate in intent
* labels (matching how the in-repo tool loader behaves).
*/
toolIntentsAvailable?: boolean;
}
/**
* Tool loading function type
*/
type LoadToolsFn = (params: {
req: Request;
res: ServerResponse;
provider: string;
agentId: string;
tools: string[];
model: string | null;
tool_options: unknown;
tool_resources: unknown;
requestBody?: MCPRuntimeRequestBody;
}) => Promise<{
tools: unknown[];
toolContextMap: Record<string, unknown>;
userMCPAuthMap?: Record<string, Record<string, string>>;
} | null>;
/**
* Create run function type
*/
type CreateRunAppConfig = Pick<
AppConfig,
'endpoints' | 'filters' | 'langfuse' | 'interfaceConfig' | 'messageFilter'
>;
type CreateRunFn = (params: {
agents: unknown[];
messages: unknown[];
runId: string;
signal: AbortSignal;
customHandlers: Record<string, EventHandler>;
requestBody: Record<string, unknown>;
user: Record<string, unknown>;
traceContext?: LangfuseTraceContext;
tenantId?: string;
appConfig?: CreateRunAppConfig;
tokenCounter?: (message: unknown) => number;
}) => Promise<{
Graph?: unknown;
processStream: (
input: { messages: unknown[] },
config: Record<string, unknown>,
options: Record<string, unknown>,
) => Promise<void>;
} | null>;
/**
* App config type
*/
interface AppConfig {
endpoints?: Record<string, unknown>;
filters?: FiltersConfig;
langfuse?: Record<string, unknown>;
/** Carries `retentionMode`, which keeps forced-temporary runs out of Langfuse. */
interfaceConfig?: Record<string, unknown>;
messageFilter?: MessageFilterConfig;
[key: string]: unknown;
}
function selectCreateRunAppConfig(
appConfig: AppConfig | undefined,
): CreateRunAppConfig | undefined {
if (appConfig == null) {
return undefined;
}
return {
...(appConfig.endpoints !== undefined && { endpoints: appConfig.endpoints }),
...(appConfig.filters !== undefined && { filters: appConfig.filters }),
...(appConfig.langfuse !== undefined && { langfuse: appConfig.langfuse }),
...(appConfig.interfaceConfig?.retentionMode !== undefined && {
interfaceConfig: { retentionMode: appConfig.interfaceConfig.retentionMode },
}),
...(appConfig.messageFilter !== undefined && { messageFilter: appConfig.messageFilter }),
};
}
function inspectSubmittedRequest(
res: ServerResponse,
request: ChatCompletionRequest,
messages: readonly ExternalChatMessage[],
filters: FiltersConfig | undefined,
legacyPii: MessageFilterPiiConfig | undefined,
): boolean {
if (filters == null && legacyPii == null) {
return false;
}
const uninspectableField = getBlockedOpaqueFileField(filters, messages);
if (uninspectableField != null) {
const response = contentFilterUninspectableResponse(uninspectableField);
sendErrorResponse(res, 400, response.message, 'invalid_request_error', response.error);
return true;
}
const messageFragments: TextContentFragment[] = [];
const traversalErrors: ContentTraversalLimitError[] = [];
try {
for (const fragment of extractMessageContent(messages)) {
messageFragments.push(fragment);
}
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
messageFragments.push(...getContentTraversalFragments(error));
traversalErrors.push(error);
}
try {
messageFragments.push(...extractModelParameterContent(request));
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
messageFragments.push(...getContentTraversalFragments(error));
traversalErrors.push(error);
}
const finding = inspectContent(messageFragments, {
filters,
legacyPii,
});
if (finding != null) {
const isLegacyFilter = finding.detectorId === 'legacy-pattern';
const response = contentFilterBlockResponse(finding);
sendErrorResponse(
res,
400,
isLegacyFilter
? `Message contains a ${finding.label}. Remove it and try again.`
: response.message,
'invalid_request_error',
isLegacyFilter ? 'message_filter_pii_block' : response.error,
);
return true;
}
const traversalError = traversalErrors.find((error) =>
isContentTraversalProtected({
error,
filters,
legacyPii,
roles: messages.map((message) => message.role),
}),
);
if (traversalError != null) {
sendErrorResponse(
res,
traversalError.statusCode,
traversalError.body.message,
'invalid_request_error',
traversalError.body.error,
);
return true;
}
return false;
}
/**
* Convert OpenAI messages to LibreChat format
*/
export function convertMessages(messages: ChatMessage[]): unknown[] {
return messages.map((msg) => {
let content: string | unknown[];
if (typeof msg.content === 'string') {
content = msg.content;
} else if (msg.content) {
content = msg.content.map((part) => {
if (part.type === 'text') {
return { type: 'text', text: part.text };
}
if (part.type === 'image_url') {
return { type: 'image_url', image_url: part.image_url };
}
return part;
});
} else {
content = '';
}
return {
role: msg.role,
content,
...(msg.name && { name: msg.name }),
...(msg.tool_calls && { tool_calls: msg.tool_calls }),
...(msg.tool_call_id && { tool_call_id: msg.tool_call_id }),
};
});
}
/**
* Create an error response in OpenAI format
*/
export function createErrorResponse(
message: string,
type = 'invalid_request_error',
code: string | null = null,
): OpenAIErrorResponse {
return {
error: {
message,
type,
param: null,
code,
},
};
}
/**
* Send an error response
*/
export function sendErrorResponse(
res: ServerResponse,
statusCode: number,
message: string,
type = 'invalid_request_error',
code: string | null = null,
): void {
res.status(statusCode).json(createErrorResponse(message, type, code));
}
/**
* Validation result types for chat completion requests
*/
export type ChatCompletionValidationSuccess = { valid: true; request: ChatCompletionRequest };
export type ChatCompletionValidationFailure = { valid: false; error: string };
export type ChatCompletionValidationResult =
| ChatCompletionValidationSuccess
| ChatCompletionValidationFailure;
/**
* Type guard for validation failure
*/
export function isChatCompletionValidationFailure(
result: ChatCompletionValidationResult,
): result is ChatCompletionValidationFailure {
return !result.valid;
}
/**
* Validate the chat completion request
*/
export function validateRequest(body: unknown): ChatCompletionValidationResult {
if (!body || typeof body !== 'object') {
return { valid: false, error: 'Request body is required' };
}
const request = body as Record<string, unknown>;
if (!request.model || typeof request.model !== 'string') {
return { valid: false, error: 'model (agent_id) is required' };
}
if (!request.messages || !Array.isArray(request.messages)) {
return { valid: false, error: 'messages array is required' };
}
if (request.messages.length === 0) {
return { valid: false, error: 'messages array cannot be empty' };
}
// Validate each message has role and content
for (let i = 0; i < request.messages.length; i++) {
const msg = request.messages[i] as Record<string, unknown>;
if (!msg.role || typeof msg.role !== 'string') {
return { valid: false, error: `messages[${i}].role is required` };
}
if (!['system', 'user', 'assistant', 'tool'].includes(msg.role)) {
return {
valid: false,
error: `messages[${i}].role must be one of: system, user, assistant, tool`,
};
}
const toolCalls = msg.tool_calls;
if (toolCalls === undefined) {
continue;
}
if (!Array.isArray(toolCalls)) {
return { valid: false, error: `messages[${i}].tool_calls must be an array` };
}
for (let callIndex = 0; callIndex < toolCalls.length; callIndex++) {
const toolCall = toolCalls[callIndex];
if (toolCall == null || typeof toolCall !== 'object') {
continue;
}
const toolFunction = (toolCall as Record<string, unknown>).function;
if (toolFunction == null || typeof toolFunction !== 'object') {
continue;
}
const args = (toolFunction as Record<string, unknown>).arguments;
if (args !== undefined && typeof args !== 'string') {
return {
valid: false,
error: `messages[${i}].tool_calls[${callIndex}].function.arguments must be a string`,
};
}
}
}
if (request.conversation_id !== undefined && typeof request.conversation_id !== 'string') {
return { valid: false, error: 'conversation_id must be a string' };
}
if (request.code_environment_mode !== undefined || request.code_workspaces !== undefined) {
return {
valid: false,
error:
'code_environment_mode and code_workspaces are not supported by this service because it cannot enforce a persisted conversation decision',
};
}
if (request.parent_message_id !== undefined && typeof request.parent_message_id !== 'string') {
return { valid: false, error: 'parent_message_id must be a string' };
}
return { valid: true, request: request as unknown as ChatCompletionRequest };
}
/**
* Build a non-streaming response from aggregated content
*/
export function buildNonStreamingResponse(
context: OpenAIResponseContext,
text: string,
reasoning: string,
toolCalls: Map<number, ToolCall>,
usage: CompletionUsage,
/** True when the map contains only accepted client-owned calls, not legacy run-step history. */
acceptedToolCallsOnly = false,
): ChatCompletionResponse {
const toolCallsArray = Array.from(toolCalls.values());
const finishReason =
toolCallsArray.length > 0 && (acceptedToolCallsOnly || !text) ? 'tool_calls' : 'stop';
return {
id: context.requestId,
object: 'chat.completion',
created: context.created,
model: context.model,
choices: [
{
index: 0,
message: {
role: 'assistant',
content: text || null,
...(reasoning && { reasoning }),
...(toolCallsArray.length > 0 && { tool_calls: toolCallsArray }),
},
finish_reason: finishReason,
},
],
usage,
};
}
/**
* Main handler for OpenAI-compatible chat completions with agents.
*
* This function:
* 1. Validates the request
* 2. Looks up the agent by ID (model parameter)
* 3. Initializes the agent with tools
* 4. Runs the agent and streams/returns the response
*
* @param req - Express request object
* @param res - Express response object
* @param deps - Dependencies for the service
*/
export async function createAgentChatCompletion(
req: Request,
res: ServerResponse,
deps: ChatCompletionDependencies,
): Promise<void> {
// Validate request
const validation = validateRequest(req.body);
if (isChatCompletionValidationFailure(validation)) {
sendErrorResponse(res, 400, validation.error);
return;
}
const request = validation.request;
const agentId = request.model;
const requestedStreaming = request.stream === true;
const filters = deps.appConfig?.filters;
const legacyPii = deps.appConfig?.messageFilter?.pii;
const submittedMessages: readonly ExternalChatMessage[] = request.messages.map((message) => ({
...message,
content: Array.isArray(message.content)
? message.content.map<ExternalMessagePart>((part) => ({ ...part }))
: (message.content ?? undefined),
}));
if (inspectSubmittedRequest(res, request, submittedMessages, filters, legacyPii)) {
return;
}
// Look up the agent
const agent = await deps.getAgent({ id: agentId });
if (!agent) {
sendErrorResponse(
res,
404,
`Agent not found: ${agentId}`,
'invalid_request_error',
'model_not_found',
);
return;
}
// Generate IDs
const requestId = `chatcmpl-${nanoid()}`;
const conversationId = request.conversation_id ?? nanoid();
let mcpParentMessageId: string | null | undefined;
if (typeof request.parent_message_id === 'string' && request.parent_message_id.trim() !== '') {
mcpParentMessageId = request.parent_message_id;
} else if (request.conversation_id == null) {
mcpParentMessageId = null;
}
const mcpRequestBody = createMCPRuntimeRequestBody({
messageId: requestId,
conversationId,
parentMessageId: mcpParentMessageId,
});
const created = Math.floor(Date.now() / 1000);
// Build response context
const context: OpenAIResponseContext = {
created,
requestId,
model: agentId,
};
// Set up abort controller
const abortController = new AbortController();
// Handle client disconnect
req.on('close', () => {
abortController.abort();
});
try {
// Build allowed providers set (empty = all allowed)
const allowedProviders = new Set<string>();
/**
* Derive `codeEnvAvailable` from the caller-supplied `appConfig` so
* `agent.tools: ['execute_code']` still produces `bash_tool` +
* `read_file` in the initialized agent's `toolDefinitions` (Phase 8
* removed the legacy `execute_code` tool definition, so the
* capability flag is the sole gate). Uses the
* `AgentCapabilities.execute_code` enum value rather than a string
* literal so an enum rename propagates here automatically. Falls
* back to `undefined` when the caller doesn't provide `appConfig` —
* matching the "explicit opt-in" semantics the in-repo controllers
* use.
*/
const agentsConfig = (deps.appConfig?.endpoints as Record<string, unknown> | undefined)?.agents;
const capabilityEnabled = (capability: AgentCapabilities): boolean | undefined =>
agentsConfig != null && typeof agentsConfig === 'object'
? ((agentsConfig as { capabilities?: string[] }).capabilities ?? []).includes(capability)
: undefined;
const capabilityAllowsCodeEnv = capabilityEnabled(AgentCapabilities.execute_code);
/** Paired with the role grant when the embedder wires `getRoleByName`;
* `initializeAgent` rebuilds `bash_tool`, `read_file` and the workspace
* file tools from this flag, so a denied role would otherwise keep the
* code environment's file handlers. */
const codeEnvAvailable =
capabilityAllowsCodeEnv === true && deps.getRoleByName != null
? (await resolveToolRoleGrants({ req, getRoleByName: deps.getRoleByName })).runCode
: capabilityAllowsCodeEnv;
const capabilityAllowsFileSearch = capabilityEnabled(AgentCapabilities.file_search);
/** The same pairing for the other gated tool, read only by the resend-file
* priming inside `initializeAgent`. The grant resolution is memoized on the
* request, so pairing both flags costs one role read. */
const fileSearchAvailable =
capabilityAllowsFileSearch === true && deps.getRoleByName != null
? (await resolveToolRoleGrants({ req, getRoleByName: deps.getRoleByName })).fileSearch
: capabilityAllowsFileSearch;
/** Wired whenever the embedder supplies `getRoleByName`, independent of
* `appConfig`: provider-native web search is a model parameter with no
* capability of its own, so the role grant is its only gate. */
const { getRoleByName } = deps;
const resolveWebSearchGrant =
getRoleByName != null
? async () => (await resolveToolRoleGrants({ req, getRoleByName })).webSearch
: undefined;
/** Mirror `codeEnvAvailable` for the stateful-session gate so this route
* also carries each agent's trusted stateful endpoint/profile selection
* into tool loading and prewarming. */
const statefulSessionsAvailable = capabilityEnabled(AgentCapabilities.stateful_code_sessions);
const allowedStatefulCodeEnvironments =
agentsConfig != null && typeof agentsConfig === 'object'
? (
agentsConfig as {
statefulCodeSessions?: {
allowedEnvironments?: readonly StatefulCodeEnvironment[];
};
}
).statefulCodeSessions?.allowedEnvironments
: undefined;
/** Same gate as the in-repo controllers: without it, agents that opted
* tools in via tool_options.run_in_background silently lose the
* background param + poll tool on this route. */
const backgroundToolsAvailable = capabilityEnabled(AgentCapabilities.run_in_background);
/** Same gate for the injected `intent` label param. */
const toolIntentsAvailable = capabilityEnabled(AgentCapabilities.tool_intents);
const loadTools: InitializeAgentParams['loadTools'] = deps.loadAgentTools
? async (params) => {
const result = await deps.loadAgentTools!({
req,
res,
...params,
requestBody: mcpRequestBody,
});
return result as Awaited<ReturnType<NonNullable<CoreInitializeAgentParams['loadTools']>>>;
}
: undefined;
// Initialize the agent first to check for disableStreaming
const initializedAgent = await deps.initializeAgent({
req,
res,
agent,
conversationId,
parentMessageId: request.parent_message_id,
requestBody: mcpRequestBody,
loadTools,
endpointOption: {
endpoint: agent.provider,
model_parameters: agent.model_parameters ?? {},
},
allowedProviders,
isInitialAgent: true,
codeEnvAvailable,
fileSearchAvailable,
resolveWebSearchGrant,
resolveLinkedInstructions: deps.resolveLinkedInstructions,
recordLinkedPromptUsage: deps.recordLinkedPromptUsage,
statefulSessionsAvailable,
allowedStatefulCodeEnvironments,
backgroundToolsAvailable,
toolIntentsAvailable,
signal: abortController.signal,
});
const modelBoundAgents = collectReachableAgents([initializedAgent]);
const modelBoundFiles: InitializedFile[] = [];
for (const modelBoundAgent of modelBoundAgents) {
modelBoundFiles.push(
...(modelBoundAgent.attachments ?? []),
...(modelBoundAgent.requestAttachments ?? []),
...(modelBoundAgent.agentContextAttachments ?? []),
);
}
assertModelBoundContent({
onTraversalFailure: deps.onTraversalFailure,
filters,
legacyPii,
submittedMessages,
agents: modelBoundAgents,
files: [...modelBoundFiles, ...getDynamicToolContexts(modelBoundAgents)],
});
// Determine if streaming is enabled (check both request and agent config)
const streamingDisabled = !!(initializedAgent.model_parameters as Record<string, unknown>)
?.disableStreaming;
const isStreaming = requestedStreaming && !streamingDisabled;
// Create tracker for streaming or aggregator for non-streaming
const tracker = isStreaming ? createOpenAIStreamTracker() : null;
const aggregator = isStreaming ? null : createOpenAIContentAggregator();
// Set up response headers for streaming
if (isStreaming) {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.setHeader('X-Accel-Buffering', 'no');
res.flushHeaders();
// Send initial chunk with role
const initialChunk = createChunk(context, { role: 'assistant' });
writeSSE(res, initialChunk);
}
// Create handler config (only used for streaming)
const handlerConfig: OpenAIStreamWriterConfig | null =
isStreaming && tracker
? {
writer: res,
context,
tracker,
}
: null;
// Create event handlers
const eventHandlers = createOpenAIHandlers(
handlerConfig
? { ...handlerConfig, signal: abortController.signal }
: {
aggregator: aggregator!,
signal: abortController.signal,
},
deps.toolExecuteOptions == null
? undefined
: {
...deps.toolExecuteOptions,
runSignal: abortController.signal,
foregroundRunId: requestId,
},
);
// Convert messages to internal format
const messages = convertMessages(request.messages);
// Create and run the agent
if (deps.createRun) {
const reqUser = (req as unknown as { user?: Parameters<typeof createSafeUser>[0] }).user;
const userId = reqUser?.id ?? 'api-user';
/**
* Propagate the full safe user (id + role), matching the in-repo agent
* controllers (responses.js / openai.js). The runtime MCP permission
* check reads `configurable.user`; passing only `user_id` would make
* every MCP tool call fail closed for an authenticated caller. When the
* host app didn't attach a user, this falls back to a bare id, which
* correctly leaves MCP gated.
*/
const safeUser: Record<string, unknown> = { ...createSafeUser(reqUser), id: userId };
const run = await deps.createRun({
agents: [initializedAgent],
messages,
runId: requestId,
signal: abortController.signal,
customHandlers: eventHandlers,
requestBody: mcpRequestBody,
user: safeUser,
traceContext: { endpoint: EModelEndpoint.agents },
tenantId: typeof reqUser?.tenantId === 'string' ? reqUser.tenantId : undefined,
appConfig: selectCreateRunAppConfig(deps.appConfig),
});
if (run) {
const target = tracker ?? aggregator!;
await completeOpenAIToolCalls(
{
finish: () => target.finishToolCalls?.(),
abort: () => target.abortToolCalls?.(),
},
() =>
run.processStream(
{ messages },
{
runName: 'AgentRun',
configurable: {
thread_id: conversationId,
user_id: userId,
user: safeUser,
requestBody: mcpRequestBody,
/** Same per-agent channel the in-repo controllers thread via
* `loadTools`: without it, the executor's PTC path cannot
* strip host-injected `intent` params from the schemas the
* sandbox bridge advertises on this route. */
...(initializedAgent.intentToolNames?.length
? { intentToolNames: initializedAgent.intentToolNames }
: {}),
},
recursionLimit: resolveRecursionLimit(
agentsConfig as Partial<TAgentsEndpoint> | undefined,
initializedAgent,
),
signal: abortController.signal,
streamMode: 'values',
version: 'v2',
},
{},
),
);
}
}
// Finalize response
if (isStreaming && handlerConfig) {
sendFinalChunk(handlerConfig, 'stop', undefined, true);
res.end();
} else if (aggregator) {
aggregator.finishToolCalls?.();
// Build and send non-streaming response
const usage: CompletionUsage = {
prompt_tokens: aggregator.usage.promptTokens,
completion_tokens: aggregator.usage.completionTokens,
total_tokens: aggregator.usage.promptTokens + aggregator.usage.completionTokens,
...(aggregator.usage.reasoningTokens > 0 && {
completion_tokens_details: { reasoning_tokens: aggregator.usage.reasoningTokens },
}),
};
const response = buildNonStreamingResponse(
context,
aggregator.getText(),
aggregator.getReasoning(),
aggregator.toolCalls,
usage,
true,
);
res.json(response);
}
} catch (error) {
if (isContentFilterError(error) && !res.headersSent) {
sendErrorResponse(
res,
error.statusCode,
error.body.message,
'invalid_request_error',
error.body.error,
);
return;
}
const errorMessage = getUserFacingProviderError(
error,
hasModelBoundContentProtection(filters, legacyPii),
);
// Check if we already started streaming (headers sent)
if (res.headersSent) {
// Headers already sent, try to send error in stream format
const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');
writeSSE(res, errorChunk);
writeSSE(res, '[DONE]');
res.end();
} else {
const candidateStatus =
error != null && typeof error === 'object'
? ((error as { status?: unknown; statusCode?: unknown }).status ??
(error as { statusCode?: unknown }).statusCode)
: undefined;
const statusCode =
typeof candidateStatus === 'number' &&
Number.isInteger(candidateStatus) &&
candidateStatus >= 400 &&
candidateStatus < 600
? candidateStatus
: 500;
const errorType =
statusCode >= 400 && statusCode < 500 ? 'invalid_request_error' : 'server_error';
const errorCode =
error != null &&
typeof error === 'object' &&
typeof (error as { code?: unknown }).code === 'string'
? (error as { code: string }).code
: null;
sendErrorResponse(res, statusCode, errorMessage, errorType, errorCode);
}
}
}
/**
* List available agents/models
*
* This provides a /v1/models compatible endpoint that lists available agents.
*/
export async function listAgentModels(
_req: Request,
res: ServerResponse,
deps: { getAgents: (params: Record<string, unknown>) => Promise<Agent[]> },
): Promise<void> {
try {
const agents = await deps.getAgents({});
const models = agents.map((agent) => ({
id: agent.id,
object: 'model',
created: Math.floor(Date.now() / 1000),
owned_by: 'librechat',
permission: [],
root: agent.id,
parent: null,
// Extensions
name: agent.name,
provider: agent.provider,
}));
res.json({
object: 'list',
data: models,
});
} catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Failed to list models';
sendErrorResponse(res, 500, errorMessage, 'server_error');
}
}