Skip to content

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

🛸 feat: Remote Agent Access with External API Support (#11503)

Danny Avila6279ea8dd7af
diff --git a/api/models/Agent.js b/api/models/Agent.js
index 11789ca63b..663285183a 100644
--- a/api/models/Agent.js
+++ b/api/models/Agent.js
@@ -589,10 +589,16 @@ const deleteAgent = async (searchParameter) => {
const agent = await Agent.findOneAndDelete(searchParameter);
if (agent) {
await removeAgentFromAllProjects(agent.id);
- await removeAllPermissions({
- resourceType: ResourceType.AGENT,
- resourceId: agent._id,
- });
+ await Promise.all([
+ removeAllPermissions({
+ resourceType: ResourceType.AGENT,
+ resourceId: agent._id,
+ }),
+ removeAllPermissions({
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: agent._id,
+ }),
+ ]);
try {
await Agent.updateMany({ 'edges.to': agent.id }, { $pull: { edges: { to: agent.id } } });
} catch (error) {
@@ -631,7 +637,7 @@ const deleteUserAgents = async (userId) => {
}
await AclEntry.deleteMany({
- resourceType: ResourceType.AGENT,
+ resourceType: { $in: [ResourceType.AGENT, ResourceType.REMOTE_AGENT] },
resourceId: { $in: agentObjectIds },
});
diff --git a/api/server/controllers/PermissionsController.js b/api/server/controllers/PermissionsController.js
index e22e9532c9..51993d083c 100644
--- a/api/server/controllers/PermissionsController.js
+++ b/api/server/controllers/PermissionsController.js
@@ -5,6 +5,7 @@
const mongoose = require('mongoose');
const { logger } = require('@librechat/data-schemas');
const { ResourceType, PrincipalType, PermissionBits } = require('librechat-data-provider');
+const { enrichRemoteAgentPrincipals, backfillRemoteAgentPermissions } = require('@librechat/api');
const {
bulkUpdateResourcePermissions,
ensureGroupPrincipalExists,
@@ -14,7 +15,6 @@ const {
findAccessibleResources,
getResourcePermissionsMap,
} = require('~/server/services/PermissionService');
-const { AclEntry } = require('~/db/models');
const {
searchPrincipals: searchLocalPrincipals,
sortPrincipalsByRelevance,
@@ -24,6 +24,7 @@ const {
entraIdPrincipalFeatureEnabled,
searchEntraIdPrincipals,
} = require('~/server/services/GraphApiService');
+const { AclEntry, AccessRole } = require('~/db/models');
/**
* Generic controller for resource permission endpoints
@@ -234,7 +235,7 @@ const getResourcePermissions = async (req, res) => {
},
]);
- const principals = [];
+ let principals = [];
let publicPermission = null;
// Process aggregation results
@@ -280,6 +281,13 @@ const getResourcePermissions = async (req, res) => {
}
}
+ if (resourceType === ResourceType.REMOTE_AGENT) {
+ const enricherDeps = { AclEntry, AccessRole, logger };
+ const enrichResult = await enrichRemoteAgentPrincipals(enricherDeps, resourceId, principals);
+ principals = enrichResult.principals;
+ backfillRemoteAgentPermissions(enricherDeps, resourceId, enrichResult.entriesToBackfill);
+ }
+
// Return response in format expected by frontend
const response = {
resourceType,
diff --git a/api/server/controllers/UserController.js b/api/server/controllers/UserController.js
index b0cfd7ede2..0f17b4d3a9 100644
--- a/api/server/controllers/UserController.js
+++ b/api/server/controllers/UserController.js
@@ -22,6 +22,7 @@ const {
} = require('~/models');
const {
ConversationTag,
+ AgentApiKey,
Transaction,
MemoryEntry,
Assistant,
@@ -256,6 +257,7 @@ const deleteUserController = async (req, res) => {
await deleteFiles(null, user.id); // delete database files in case of orphaned files from previous steps
await deleteToolCalls(user.id); // delete user tool calls
await deleteUserAgents(user.id); // delete user agents
+ await AgentApiKey.deleteMany({ user: user._id }); // delete user agent API keys
await Assistant.deleteMany({ user: user.id }); // delete user assistants
await ConversationTag.deleteMany({ user: user.id }); // delete user conversation tags
await MemoryEntry.deleteMany({ userId: user.id }); // delete user memory entries
diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.js
index 490f05f832..c27f89fdf8 100644
--- a/api/server/controllers/agents/callbacks.js
+++ b/api/server/controllers/agents/callbacks.js
@@ -1,7 +1,7 @@
const { nanoid } = require('nanoid');
const { Constants } = require('@librechat/agents');
const { logger } = require('@librechat/data-schemas');
-const { sendEvent, GenerationJobManager } = require('@librechat/api');
+const { sendEvent, GenerationJobManager, writeAttachmentEvent } = require('@librechat/api');
const { Tools, StepTypes, FileContext, ErrorTypes } = require('librechat-data-provider');
const {
EnvVar,
@@ -489,7 +489,226 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })
};
}
+/**
+ * Helper to write attachment events in Open Responses format (librechat:attachment)
+ * @param {ServerResponse} res - The server response object
+ * @param {Object} tracker - The response tracker with sequence number
+ * @param {Object} attachment - The attachment data
+ * @param {Object} metadata - Additional metadata (messageId, conversationId)
+ */
+function writeResponsesAttachment(res, tracker, attachment, metadata) {
+ const sequenceNumber = tracker.nextSequence();
+ writeAttachmentEvent(res, sequenceNumber, attachment, {
+ messageId: metadata.run_id,
+ conversationId: metadata.thread_id,
+ });
+}
+
+/**
+ * Creates a tool end callback specifically for the Responses API.
+ * Emits attachments as `librechat:attachment` events per the Open Responses extension spec.
+ *
+ * @param {Object} params
+ * @param {ServerRequest} params.req
+ * @param {ServerResponse} params.res
+ * @param {Object} params.tracker - Response tracker with sequence number
+ * @param {Promise<MongoFile | { filename: string; filepath: string; expires: number;} | null>[]} params.artifactPromises
+ * @returns {ToolEndCallback} The tool end callback.
+ */
+function createResponsesToolEndCallback({ req, res, tracker, artifactPromises }) {
+ /**
+ * @type {ToolEndCallback}
+ */
+ return async (data, metadata) => {
+ const output = data?.output;
+ if (!output) {
+ return;
+ }
+
+ if (!output.artifact) {
+ return;
+ }
+
+ if (output.artifact[Tools.file_search]) {
+ artifactPromises.push(
+ (async () => {
+ const user = req.user;
+ const attachment = await processFileCitations({
+ user,
+ metadata,
+ appConfig: req.config,
+ toolArtifact: output.artifact,
+ toolCallId: output.tool_call_id,
+ });
+ if (!attachment) {
+ return null;
+ }
+ // For Responses API, emit attachment during streaming
+ if (res.headersSent && !res.writableEnded) {
+ writeResponsesAttachment(res, tracker, attachment, metadata);
+ }
+ return attachment;
+ })().catch((error) => {
+ logger.error('Error processing file citations:', error);
+ return null;
+ }),
+ );
+ }
+
+ if (output.artifact[Tools.ui_resources]) {
+ artifactPromises.push(
+ (async () => {
+ const attachment = {
+ type: Tools.ui_resources,
+ toolCallId: output.tool_call_id,
+ [Tools.ui_resources]: output.artifact[Tools.ui_resources].data,
+ };
+ // For Responses API, always emit attachment during streaming
+ if (res.headersSent && !res.writableEnded) {
+ writeResponsesAttachment(res, tracker, attachment, metadata);
+ }
+ return attachment;
+ })().catch((error) => {
+ logger.error('Error processing artifact content:', error);
+ return null;
+ }),
+ );
+ }
+
+ if (output.artifact[Tools.web_search]) {
+ artifactPromises.push(
+ (async () => {
+ const attachment = {
+ type: Tools.web_search,
+ toolCallId: output.tool_call_id,
+ [Tools.web_search]: { ...output.artifact[Tools.web_search] },
+ };
+ // For Responses API, always emit attachment during streaming
+ if (res.headersSent && !res.writableEnded) {
+ writeResponsesAttachment(res, tracker, attachment, metadata);
+ }
+ return attachment;
+ })().catch((error) => {
+ logger.error('Error processing artifact content:', error);
+ return null;
+ }),
+ );
+ }
+
+ if (output.artifact.content) {
+ /** @type {FormattedContent[]} */
+ const content = output.artifact.content;
+ for (let i = 0; i < content.length; i++) {
+ const part = content[i];
+ if (!part) {
+ continue;
+ }
+ if (part.type !== 'image_url') {
+ continue;
+ }
+ const { url } = part.image_url;
+ artifactPromises.push(
+ (async () => {
+ const filename = `${output.name}_img_${nanoid()}`;
+ const file_id = output.artifact.file_ids?.[i];
+ const file = await saveBase64Image(url, {
+ req,
+ file_id,
+ filename,
+ endpoint: metadata.provider,
+ context: FileContext.image_generation,
+ });
+ const fileMetadata = Object.assign(file, {
+ toolCallId: output.tool_call_id,
+ });
+
+ if (!fileMetadata) {
+ return null;
+ }
+
+ // For Responses API, emit attachment during streaming
+ if (res.headersSent && !res.writableEnded) {
+ const attachment = {
+ file_id: fileMetadata.file_id,
+ filename: fileMetadata.filename,
+ type: fileMetadata.type,
+ url: fileMetadata.filepath,
+ width: fileMetadata.width,
+ height: fileMetadata.height,
+ tool_call_id: output.tool_call_id,
+ };
+ writeResponsesAttachment(res, tracker, attachment, metadata);
+ }
+
+ return fileMetadata;
+ })().catch((error) => {
+ logger.error('Error processing artifact content:', error);
+ return null;
+ }),
+ );
+ }
+ return;
+ }
+
+ const isCodeTool =
+ output.name === Tools.execute_code || output.name === Constants.PROGRAMMATIC_TOOL_CALLING;
+ if (!isCodeTool) {
+ return;
+ }
+
+ if (!output.artifact.files) {
+ return;
+ }
+
+ for (const file of output.artifact.files) {
+ const { id, name } = file;
+ artifactPromises.push(
+ (async () => {
+ const result = await loadAuthValues({
+ userId: req.user.id,
+ authFields: [EnvVar.CODE_API_KEY],
+ });
+ const fileMetadata = await processCodeOutput({
+ req,
+ id,
+ name,
+ apiKey: result[EnvVar.CODE_API_KEY],
+ messageId: metadata.run_id,
+ toolCallId: output.tool_call_id,
+ conversationId: metadata.thread_id,
+ session_id: output.artifact.session_id,
+ });
+
+ if (!fileMetadata) {
+ return null;
+ }
+
+ // For Responses API, emit attachment during streaming
+ if (res.headersSent && !res.writableEnded) {
+ const attachment = {
+ file_id: fileMetadata.file_id,
+ filename: fileMetadata.filename,
+ type: fileMetadata.type,
+ url: fileMetadata.filepath,
+ width: fileMetadata.width,
+ height: fileMetadata.height,
+ tool_call_id: output.tool_call_id,
+ };
+ writeResponsesAttachment(res, tracker, attachment, metadata);
+ }
+
+ return fileMetadata;
+ })().catch((error) => {
+ logger.error('Error processing code output:', error);
+ return null;
+ }),
+ );
+ }
+ };
+}
+
module.exports = {
getDefaultHandlers,
createToolEndCallback,
+ createResponsesToolEndCallback,
};
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
new file mode 100644
index 0000000000..331179c7f4
--- /dev/null
+++ b/api/server/controllers/agents/openai.js
@@ -0,0 +1,660 @@
+const { nanoid } = require('nanoid');
+const { logger } = require('@librechat/data-schemas');
+const { EModelEndpoint, ResourceType, PermissionBits } = require('librechat-data-provider');
+const {
+ Callback,
+ ToolEndHandler,
+ formatAgentMessages,
+ ChatModelStreamHandler,
+} = require('@librechat/agents');
+const {
+ writeSSE,
+ createRun,
+ createChunk,
+ sendFinalChunk,
+ createSafeUser,
+ validateRequest,
+ initializeAgent,
+ createErrorResponse,
+ buildNonStreamingResponse,
+ createOpenAIStreamTracker,
+ createOpenAIContentAggregator,
+ isChatCompletionValidationFailure,
+} = require('@librechat/api');
+const { createToolEndCallback } = require('~/server/controllers/agents/callbacks');
+const { findAccessibleResources } = require('~/server/services/PermissionService');
+const { loadAgentTools } = require('~/server/services/ToolService');
+const { getConvoFiles } = require('~/models/Conversation');
+const { getAgent, getAgents } = require('~/models/Agent');
+const db = require('~/models');
+
+/**
+ * Creates a tool loader function for the agent.
+ * @param {AbortSignal} signal - The abort signal
+ */
+function createToolLoader(signal) {
+ return async function loadTools({
+ req,
+ res,
+ tools,
+ model,
+ agentId,
+ provider,
+ tool_options,
+ tool_resources,
+ }) {
+ const agent = { id: agentId, tools, provider, model, tool_options };
+ try {
+ return await loadAgentTools({
+ req,
+ res,
+ agent,
+ signal,
+ tool_resources,
+ streamId: null, // No resumable stream for OpenAI compat
+ });
+ } catch (error) {
+ logger.error('Error loading tools for agent ' + agentId, error);
+ }
+ };
+}
+
+/**
+ * Convert content part to internal format
+ * @param {Object} part - Content part
+ * @returns {Object} Converted part
+ */
+function convertContentPart(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;
+}
+
+/**
+ * Convert OpenAI messages to internal format
+ * @param {Array} messages - OpenAI format messages
+ * @returns {Array} Internal format messages
+ */
+function convertMessages(messages) {
+ return messages.map((msg) => {
+ let content;
+ if (typeof msg.content === 'string') {
+ content = msg.content;
+ } else if (msg.content) {
+ content = msg.content.map(convertContentPart);
+ } 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 }),
+ };
+ });
+}
+
+/**
+ * Send an error response in OpenAI format
+ */
+function sendErrorResponse(res, statusCode, message, type = 'invalid_request_error', code = null) {
+ res.status(statusCode).json(createErrorResponse(message, type, code));
+}
+
+/**
+ * OpenAI-compatible chat completions controller for agents.
+ *
+ * POST /v1/chat/completions
+ *
+ * Request format:
+ * {
+ * "model": "agent_id_here",
+ * "messages": [{"role": "user", "content": "Hello!"}],
+ * "stream": true,
+ * "conversation_id": "optional",
+ * "parent_message_id": "optional"
+ * }
+ */
+const OpenAIChatCompletionController = async (req, res) => {
+ const appConfig = req.config;
+
+ // Validate request
+ const validation = validateRequest(req.body);
+ if (isChatCompletionValidationFailure(validation)) {
+ return sendErrorResponse(res, 400, validation.error);
+ }
+
+ const request = validation.request;
+ const agentId = request.model;
+
+ // Look up the agent
+ const agent = await getAgent({ id: agentId });
+ if (!agent) {
+ return sendErrorResponse(
+ res,
+ 404,
+ `Agent not found: ${agentId}`,
+ 'invalid_request_error',
+ 'model_not_found',
+ );
+ }
+
+ // Generate IDs
+ const requestId = `chatcmpl-${nanoid()}`;
+ const conversationId = request.conversation_id ?? nanoid();
+ const parentMessageId = request.parent_message_id ?? null;
+ const created = Math.floor(Date.now() / 1000);
+
+ const context = {
+ created,
+ requestId,
+ model: agentId,
+ };
+
+ // Set up abort controller
+ const abortController = new AbortController();
+
+ // Handle client disconnect
+ req.on('close', () => {
+ if (!abortController.signal.aborted) {
+ abortController.abort();
+ logger.debug('[OpenAI API] Client disconnected, aborting');
+ }
+ });
+
+ try {
+ // Build allowed providers set
+ const allowedProviders = new Set(
+ appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders,
+ );
+
+ // Create tool loader
+ const loadTools = createToolLoader(abortController.signal);
+
+ // Initialize the agent first to check for disableStreaming
+ const endpointOption = {
+ endpoint: agent.provider,
+ model_parameters: agent.model_parameters ?? {},
+ };
+
+ const primaryConfig = await initializeAgent(
+ {
+ req,
+ res,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ agent,
+ endpointOption,
+ allowedProviders,
+ isInitialAgent: true,
+ },
+ {
+ getConvoFiles,
+ getFiles: db.getFiles,
+ getUserKey: db.getUserKey,
+ getMessages: db.getMessages,
+ updateFilesUsage: db.updateFilesUsage,
+ getUserKeyValues: db.getUserKeyValues,
+ getUserCodeFiles: db.getUserCodeFiles,
+ getToolFilesByIds: db.getToolFilesByIds,
+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,
+ },
+ );
+
+ // Determine if streaming is enabled (check both request and agent config)
+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
+ const isStreaming = request.stream === true && !streamingDisabled;
+
+ // Create tracker for streaming or aggregator for non-streaming
+ const tracker = isStreaming ? createOpenAIStreamTracker() : null;
+ const aggregator = isStreaming ? null : createOpenAIContentAggregator();
+
+ // Set up response 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 for OpenAI streaming (only used when streaming)
+ const handlerConfig = isStreaming
+ ? {
+ res,
+ context,
+ tracker,
+ }
+ : null;
+
+ // We need custom handlers that stream in OpenAI format
+ const collectedUsage = [];
+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
+ const artifactPromises = [];
+
+ // Create tool end callback for processing artifacts (images, file citations, code output)
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });
+
+ // Convert messages to internal format
+ const openaiMessages = convertMessages(request.messages);
+
+ // Format for agent
+ const toolSet = new Set((primaryConfig.tools ?? []).map((tool) => tool && tool.name));
+ const { messages: formattedMessages, indexTokenCountMap } = formatAgentMessages(
+ openaiMessages,
+ {},
+ toolSet,
+ );
+
+ /**
+ * Create a simple handler that processes data
+ */
+ const createHandler = (processor) => ({
+ handle: (_event, data) => {
+ if (processor) {
+ processor(data);
+ }
+ },
+ });
+
+ /**
+ * Stream text content in OpenAI format
+ */
+ const streamText = (text) => {
+ if (!text) {
+ return;
+ }
+ if (isStreaming) {
+ tracker.addText();
+ writeSSE(res, createChunk(context, { content: text }));
+ } else {
+ aggregator.addText(text);
+ }
+ };
+
+ /**
+ * Stream reasoning content in OpenAI format (OpenRouter convention)
+ */
+ const streamReasoning = (text) => {
+ if (!text) {
+ return;
+ }
+ if (isStreaming) {
+ tracker.addReasoning();
+ writeSSE(res, createChunk(context, { reasoning: text }));
+ } else {
+ aggregator.addReasoning(text);
+ }
+ };
+
+ // Built-in handler for processing raw model stream chunks
+ const chatModelStreamHandler = new ChatModelStreamHandler();
+
+ // Event handlers for OpenAI-compatible streaming
+ const handlers = {
+ // Process raw model chunks and dispatch message/reasoning deltas
+ on_chat_model_stream: {
+ handle: async (event, data, metadata, graph) => {
+ await chatModelStreamHandler.handle(event, data, metadata, graph);
+ },
+ },
+
+ // Text content streaming
+ on_message_delta: createHandler((data) => {
+ const content = data?.delta?.content;
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ streamText(part.text);
+ }
+ }
+ }
+ }),
+
+ // Reasoning/thinking content streaming
+ on_reasoning_delta: createHandler((data) => {
+ const content = data?.delta?.content;
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ const text = part.think || part.text;
+ if (text) {
+ streamReasoning(text);
+ }
+ }
+ }
+ }),
+
+ // Tool call initiation - streams id and name (from on_run_step)
+ on_run_step: createHandler((data) => {
+ const stepDetails = data?.stepDetails;
+ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
+ for (const tc of stepDetails.tool_calls) {
+ const toolIndex = data.index ?? 0;
+ const toolId = tc.id ?? '';
+ const toolName = tc.name ?? '';
+ const toolCall = {
+ id: toolId,
+ type: 'function',
+ function: { name: toolName, arguments: '' },
+ };
+
+ // Track tool call in tracker or aggregator
+ if (isStreaming) {
+ if (!tracker.toolCalls.has(toolIndex)) {
+ tracker.toolCalls.set(toolIndex, toolCall);
+ }
+ // Stream initial tool call chunk (like OpenAI does)
+ writeSSE(
+ res,
+ createChunk(context, {
+ tool_calls: [{ index: toolIndex, ...toolCall }],
+ }),
+ );
+ } else {
+ if (!aggregator.toolCalls.has(toolIndex)) {
+ aggregator.toolCalls.set(toolIndex, toolCall);
+ }
+ }
+ }
+ }
+ }),
+
+ // Tool call argument streaming (from on_run_step_delta)
+ on_run_step_delta: createHandler((data) => {
+ const delta = data?.delta;
+ if (delta?.type === 'tool_calls' && delta.tool_calls) {
+ for (const tc of delta.tool_calls) {
+ const args = tc.args ?? '';
+ if (!args) {
+ continue;
+ }
+
+ const toolIndex = tc.index ?? 0;
+
+ // Update tool call arguments
+ const targetMap = isStreaming ? tracker.toolCalls : aggregator.toolCalls;
+ const tracked = targetMap.get(toolIndex);
+ if (tracked) {
+ tracked.function.arguments += args;
+ }
+
+ // Stream argument delta (only for streaming)
+ if (isStreaming) {
+ writeSSE(
+ res,
+ createChunk(context, {
+ tool_calls: [
+ {
+ index: toolIndex,
+ function: { arguments: args },
+ },
+ ],
+ }),
+ );
+ }
+ }
+ }
+ }),
+
+ // Usage tracking
+ on_chat_model_end: createHandler((data) => {
+ const usage = data?.output?.usage_metadata;
+ if (usage) {
+ collectedUsage.push(usage);
+ const target = isStreaming ? tracker : aggregator;
+ target.usage.promptTokens += usage.input_tokens ?? 0;
+ target.usage.completionTokens += usage.output_tokens ?? 0;
+ }
+ }),
+ on_run_step_completed: createHandler(),
+ // Use proper ToolEndHandler for processing artifacts (images, file citations, code output)
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_chain_stream: createHandler(),
+ on_chain_end: createHandler(),
+ on_agent_update: createHandler(),
+ on_custom_event: createHandler(),
+ };
+
+ // Create and run the agent
+ const userId = req.user?.id ?? 'api-user';
+
+ // Extract userMCPAuthMap from primaryConfig (needed for MCP tool connections)
+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;
+
+ const run = await createRun({
+ agents: [primaryConfig],
+ messages: formattedMessages,
+ indexTokenCountMap,
+ runId: requestId,
+ signal: abortController.signal,
+ customHandlers: handlers,
+ requestBody: {
+ messageId: requestId,
+ conversationId,
+ },
+ user: { id: userId },
+ });
+
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
+
+ // Process the stream
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
+ },
+ signal: abortController.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[OpenAI API] Tool Error "${toolId}"`, error);
+ },
+ },
+ });
+
+ // Finalize response
+ if (isStreaming) {
+ sendFinalChunk(handlerConfig);
+ res.end();
+
+ // Wait for artifact processing after response ends (non-blocking)
+ if (artifactPromises.length > 0) {
+ Promise.all(artifactPromises).catch((artifactError) => {
+ logger.warn('[OpenAI API] Error processing artifacts:', artifactError);
+ });
+ }
+ } else {
+ // For non-streaming, wait for artifacts before sending response
+ if (artifactPromises.length > 0) {
+ try {
+ await Promise.all(artifactPromises);
+ } catch (artifactError) {
+ logger.warn('[OpenAI API] Error processing artifacts:', artifactError);
+ }
+ }
+
+ // Build usage from aggregated data
+ const usage = {
+ prompt_tokens: aggregator.usage.promptTokens,
+ completion_tokens: aggregator.usage.completionTokens,
+ total_tokens: aggregator.usage.promptTokens + aggregator.usage.completionTokens,
+ };
+
+ if (aggregator.usage.reasoningTokens > 0) {
+ usage.completion_tokens_details = {
+ reasoning_tokens: aggregator.usage.reasoningTokens,
+ };
+ }
+
+ const response = buildNonStreamingResponse(
+ context,
+ aggregator.getText(),
+ aggregator.getReasoning(),
+ aggregator.toolCalls,
+ usage,
+ );
+ res.json(response);
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';
+ logger.error('[OpenAI API] Error:', error);
+
+ // Check if we already started streaming (headers sent)
+ if (res.headersSent) {
+ // Headers already sent, send error in stream
+ const errorChunk = createChunk(context, { content: `\n\nError: ${errorMessage}` }, 'stop');
+ writeSSE(res, errorChunk);
+ writeSSE(res, '[DONE]');
+ res.end();
+ } else {
+ sendErrorResponse(res, 500, errorMessage, 'server_error');
+ }
+ }
+};
+
+/**
+ * List available agents as models (filtered by remote access permissions)
+ *
+ * GET /v1/models
+ */
+const ListModelsController = async (req, res) => {
+ try {
+ const userId = req.user?.id;
+ const userRole = req.user?.role;
+
+ if (!userId) {
+ return sendErrorResponse(res, 401, 'Authentication required', 'auth_error');
+ }
+
+ // Find agents the user has remote access to (VIEW permission on REMOTE_AGENT)
+ const accessibleAgentIds = await findAccessibleResources({
+ userId,
+ role: userRole,
+ resourceType: ResourceType.REMOTE_AGENT,
+ requiredPermissions: PermissionBits.VIEW,
+ });
+
+ // Get the accessible agents
+ let agents = [];
+ if (accessibleAgentIds.length > 0) {
+ agents = await getAgents({ _id: { $in: accessibleAgentIds } });
+ }
+
+ const models = agents.map((agent) => ({
+ id: agent.id,
+ object: 'model',
+ created: Math.floor(new Date(agent.createdAt || Date.now()).getTime() / 1000),
+ owned_by: 'librechat',
+ permission: [],
+ root: agent.id,
+ parent: null,
+ // LibreChat extensions
+ name: agent.name,
+ description: agent.description,
+ provider: agent.provider,
+ }));
+
+ res.json({
+ object: 'list',
+ data: models,
+ });
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : 'Failed to list models';
+ logger.error('[OpenAI API] Error listing models:', error);
+ sendErrorResponse(res, 500, errorMessage, 'server_error');
+ }
+};
+
+/**
+ * Get a specific model/agent (with remote access permission check)
+ *
+ * GET /v1/models/:model
+ */
+const GetModelController = async (req, res) => {
+ try {
+ const { model } = req.params;
+ const userId = req.user?.id;
+ const userRole = req.user?.role;
+
+ if (!userId) {
+ return sendErrorResponse(res, 401, 'Authentication required', 'auth_error');
+ }
+
+ const agent = await getAgent({ id: model });
+
+ if (!agent) {
+ return sendErrorResponse(
+ res,
+ 404,
+ `Model not found: ${model}`,
+ 'invalid_request_error',
+ 'model_not_found',
+ );
+ }
+
+ // Check if user has remote access to this agent
+ const accessibleAgentIds = await findAccessibleResources({
+ userId,
+ role: userRole,
+ resourceType: ResourceType.REMOTE_AGENT,
+ requiredPermissions: PermissionBits.VIEW,
+ });
+
+ const hasAccess = accessibleAgentIds.some((id) => id.toString() === agent._id.toString());
+
+ if (!hasAccess) {
+ return sendErrorResponse(
+ res,
+ 403,
+ `No remote access to model: ${model}`,
+ 'permission_error',
+ 'access_denied',
+ );
+ }
+
+ res.json({
+ id: agent.id,
+ object: 'model',
+ created: Math.floor(new Date(agent.createdAt || Date.now()).getTime() / 1000),
+ owned_by: 'librechat',
+ permission: [],
+ root: agent.id,
+ parent: null,
+ // LibreChat extensions
+ name: agent.name,
+ description: agent.description,
+ provider: agent.provider,
+ });
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : 'Failed to get model';
+ logger.error('[OpenAI API] Error getting model:', error);
+ sendErrorResponse(res, 500, errorMessage, 'server_error');
+ }
+};
+
+module.exports = {
+ OpenAIChatCompletionController,
+ ListModelsController,
+ GetModelController,
+};
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
new file mode 100644
index 0000000000..bf52edcf7d
--- /dev/null
+++ b/api/server/controllers/agents/responses.js
@@ -0,0 +1,800 @@
+const { nanoid } = require('nanoid');
+const { v4: uuidv4 } = require('uuid');
+const { logger } = require('@librechat/data-schemas');
+const { EModelEndpoint, ResourceType, PermissionBits } = require('librechat-data-provider');
+const {
+ Callback,
+ ToolEndHandler,
+ formatAgentMessages,
+ ChatModelStreamHandler,
+} = require('@librechat/agents');
+const {
+ createRun,
+ createSafeUser,
+ initializeAgent,
+ // Responses API
+ writeDone,
+ buildResponse,
+ generateResponseId,
+ isValidationFailure,
+ emitResponseCreated,
+ createResponseContext,
+ createResponseTracker,
+ setupStreamingResponse,
+ emitResponseInProgress,
+ convertInputToMessages,
+ validateResponseRequest,
+ buildAggregatedResponse,
+ createResponseAggregator,
+ sendResponsesErrorResponse,
+ createResponsesEventHandlers,
+ createAggregatorEventHandlers,
+} = require('@librechat/api');
+const {
+ createResponsesToolEndCallback,
+ createToolEndCallback,
+} = require('~/server/controllers/agents/callbacks');
+const { findAccessibleResources } = require('~/server/services/PermissionService');
+const { getConvoFiles, saveConvo, getConvo } = require('~/models/Conversation');
+const { loadAgentTools } = require('~/server/services/ToolService');
+const { getAgent, getAgents } = require('~/models/Agent');
+const db = require('~/models');
+
+/** @type {import('@librechat/api').AppConfig | null} */
+let appConfig = null;
+
+/**
+ * Set the app config for the controller
+ * @param {import('@librechat/api').AppConfig} config
+ */
+function setAppConfig(config) {
+ appConfig = config;
+}
+
+/**
+ * Creates a tool loader function for the agent.
+ * @param {AbortSignal} signal - The abort signal
+ */
+function createToolLoader(signal) {
+ return async function loadTools({
+ req,
+ res,
+ tools,
+ model,
+ agentId,
+ provider,
+ tool_options,
+ tool_resources,
+ }) {
+ const agent = { id: agentId, tools, provider, model, tool_options };
+ try {
+ return await loadAgentTools({
+ req,
+ res,
+ agent,
+ signal,
+ tool_resources,
+ streamId: null,
+ });
+ } catch (error) {
+ logger.error('Error loading tools for agent ' + agentId, error);
+ }
+ };
+}
+
+/**
+ * Convert Open Responses input items to internal messages
+ * @param {import('@librechat/api').InputItem[]} input
+ * @returns {Array} Internal messages
+ */
+function convertToInternalMessages(input) {
+ return convertInputToMessages(input);
+}
+
+/**
+ * Load messages from a previous response/conversation
+ * @param {string} conversationId - The conversation/response ID
+ * @param {string} userId - The user ID
+ * @returns {Promise<Array>} Messages from the conversation
+ */
+async function loadPreviousMessages(conversationId, userId) {
+ try {
+ const messages = await db.getMessages({ conversationId, user: userId });
+ if (!messages || messages.length === 0) {
+ return [];
+ }
+
+ // Convert stored messages to internal format
+ return messages.map((msg) => {
+ const internalMsg = {
+ role: msg.isCreatedByUser ? 'user' : 'assistant',
+ content: '',
+ messageId: msg.messageId,
+ };
+
+ // Handle content - could be string or array
+ if (typeof msg.text === 'string') {
+ internalMsg.content = msg.text;
+ } else if (Array.isArray(msg.content)) {
+ // Handle content parts
+ internalMsg.content = msg.content;
+ } else if (msg.text) {
+ internalMsg.content = String(msg.text);
+ }
+
+ return internalMsg;
+ });
+ } catch (error) {
+ logger.error('[Responses API] Error loading previous messages:', error);
+ return [];
+ }
+}
+
+/**
+ * Save input messages to database
+ * @param {import('express').Request} req
+ * @param {string} conversationId
+ * @param {Array} inputMessages - Internal format messages
+ * @param {string} agentId
+ * @returns {Promise<void>}
+ */
+async function saveInputMessages(req, conversationId, inputMessages, agentId) {
+ for (const msg of inputMessages) {
+ if (msg.role === 'user') {
+ await db.saveMessage(
+ req,
+ {
+ messageId: msg.messageId || nanoid(),
+ conversationId,
+ parentMessageId: null,
+ isCreatedByUser: true,
+ text: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+ sender: 'User',
+ endpoint: EModelEndpoint.agents,
+ model: agentId,
+ },
+ { context: 'Responses API - save user input' },
+ );
+ }
+ }
+}
+
+/**
+ * Save response output to database
+ * @param {import('express').Request} req
+ * @param {string} conversationId
+ * @param {string} responseId
+ * @param {import('@librechat/api').Response} response
+ * @param {string} agentId
+ * @returns {Promise<void>}
+ */
+async function saveResponseOutput(req, conversationId, responseId, response, agentId) {
+ // Extract text content from output items
+ let responseText = '';
+ for (const item of response.output) {
+ if (item.type === 'message' && item.content) {
+ for (const part of item.content) {
+ if (part.type === 'output_text' && part.text) {
+ responseText += part.text;
+ }
+ }
+ }
+ }
+
+ // Save the assistant message
+ await db.saveMessage(
+ req,
+ {
+ messageId: responseId,
+ conversationId,
+ parentMessageId: null,
+ isCreatedByUser: false,
+ text: responseText,
+ sender: 'Agent',
+ endpoint: EModelEndpoint.agents,
+ model: agentId,
+ finish_reason: response.status === 'completed' ? 'stop' : response.status,
+ tokenCount: response.usage?.output_tokens,
+ },
+ { context: 'Responses API - save assistant response' },
+ );
+}
+
+/**
+ * Save or update conversation
+ * @param {import('express').Request} req
+ * @param {string} conversationId
+ * @param {string} agentId
+ * @param {object} agent
+ * @returns {Promise<void>}
+ */
+async function saveConversation(req, conversationId, agentId, agent) {
+ await saveConvo(
+ req,
+ {
+ conversationId,
+ endpoint: EModelEndpoint.agents,
+ agentId,
+ title: agent?.name || 'Open Responses Conversation',
+ model: agent?.model,
+ },
+ { context: 'Responses API - save conversation' },
+ );
+}
+
+/**
+ * Convert stored messages to Open Responses output format
+ * @param {Array} messages - Stored messages
+ * @returns {Array} Output items
+ */
+function convertMessagesToOutputItems(messages) {
+ const output = [];
+
+ for (const msg of messages) {
+ if (!msg.isCreatedByUser) {
+ output.push({
+ type: 'message',
+ id: msg.messageId,
+ role: 'assistant',
+ status: 'completed',
+ content: [
+ {
+ type: 'output_text',
+ text: msg.text || '',
+ annotations: [],
+ },
+ ],
+ });
+ }
+ }
+
+ return output;
+}
+
+/**
+ * Create Response - POST /v1/responses
+ *
+ * Creates a model response following the Open Responses API specification.
+ * Supports both streaming and non-streaming responses.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ */
+const createResponse = async (req, res) => {
+ // Validate request
+ const validation = validateResponseRequest(req.body);
+ if (isValidationFailure(validation)) {
+ return sendResponsesErrorResponse(res, 400, validation.error);
+ }
+
+ const request = validation.request;
+ const agentId = request.model;
+ const isStreaming = request.stream === true;
+
+ // Look up the agent
+ const agent = await getAgent({ id: agentId });
+ if (!agent) {
+ return sendResponsesErrorResponse(
+ res,
+ 404,
+ `Agent not found: ${agentId}`,
+ 'not_found',
+ 'model_not_found',
+ );
+ }
+
+ // Generate IDs
+ const responseId = generateResponseId();
+ const conversationId = request.previous_response_id ?? uuidv4();
+ const parentMessageId = null;
+
+ // Create response context
+ const context = createResponseContext(request, responseId);
+
+ // Set up abort controller
+ const abortController = new AbortController();
+
+ // Handle client disconnect
+ req.on('close', () => {
+ if (!abortController.signal.aborted) {
+ abortController.abort();
+ logger.debug('[Responses API] Client disconnected, aborting');
+ }
+ });
+
+ try {
+ // Build allowed providers set
+ const allowedProviders = new Set(
+ appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders,
+ );
+
+ // Create tool loader
+ const loadTools = createToolLoader(abortController.signal);
+
+ // Initialize the agent first to check for disableStreaming
+ const endpointOption = {
+ endpoint: agent.provider,
+ model_parameters: agent.model_parameters ?? {},
+ };
+
+ const primaryConfig = await initializeAgent(
+ {
+ req,
+ res,
+ loadTools,
+ requestFiles: [],
+ conversationId,
+ parentMessageId,
+ agent,
+ endpointOption,
+ allowedProviders,
+ isInitialAgent: true,
+ },
+ {
+ getConvoFiles,
+ getFiles: db.getFiles,
+ getUserKey: db.getUserKey,
+ getMessages: db.getMessages,
+ updateFilesUsage: db.updateFilesUsage,
+ getUserKeyValues: db.getUserKeyValues,
+ getUserCodeFiles: db.getUserCodeFiles,
+ getToolFilesByIds: db.getToolFilesByIds,
+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,
+ },
+ );
+
+ // Determine if streaming is enabled (check both request and agent config)
+ const streamingDisabled = !!primaryConfig.model_parameters?.disableStreaming;
+ const actuallyStreaming = isStreaming && !streamingDisabled;
+
+ // Load previous messages if previous_response_id is provided
+ let previousMessages = [];
+ if (request.previous_response_id) {
+ const userId = req.user?.id ?? 'api-user';
+ previousMessages = await loadPreviousMessages(request.previous_response_id, userId);
+ }
+
+ // Convert input to internal messages
+ const inputMessages = convertToInternalMessages(
+ typeof request.input === 'string' ? request.input : request.input,
+ );
+
+ // Merge previous messages with new input
+ const allMessages = [...previousMessages, ...inputMessages];
+
+ // Format for agent
+ const toolSet = new Set((primaryConfig.tools ?? []).map((tool) => tool && tool.name));
+ const { messages: formattedMessages, indexTokenCountMap } = formatAgentMessages(
+ allMessages,
+ {},
+ toolSet,
+ );
+
+ // Create tracker for streaming or aggregator for non-streaming
+ const tracker = actuallyStreaming ? createResponseTracker() : null;
+ const aggregator = actuallyStreaming ? null : createResponseAggregator();
+
+ // Set up response for streaming
+ if (actuallyStreaming) {
+ setupStreamingResponse(res);
+
+ // Create handler config
+ const handlerConfig = {
+ res,
+ context,
+ tracker,
+ };
+
+ // Emit response.created then response.in_progress per Open Responses spec
+ emitResponseCreated(handlerConfig);
+ emitResponseInProgress(handlerConfig);
+
+ // Create event handlers
+ const { handlers: responsesHandlers, finalizeStream } =
+ createResponsesEventHandlers(handlerConfig);
+
+ // Built-in handler for processing raw model stream chunks
+ const chatModelStreamHandler = new ChatModelStreamHandler();
+
+ // Artifact promises for processing tool outputs
+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
+ const artifactPromises = [];
+ // Use Responses API-specific callback that emits librechat:attachment events
+ const toolEndCallback = createResponsesToolEndCallback({
+ req,
+ res,
+ tracker,
+ artifactPromises,
+ });
+
+ // Combine handlers
+ const handlers = {
+ on_chat_model_stream: {
+ handle: async (event, data, metadata, graph) => {
+ await chatModelStreamHandler.handle(event, data, metadata, graph);
+ },
+ },
+ on_message_delta: responsesHandlers.on_message_delta,
+ on_reasoning_delta: responsesHandlers.on_reasoning_delta,
+ on_run_step: responsesHandlers.on_run_step,
+ on_run_step_delta: responsesHandlers.on_run_step_delta,
+ on_chat_model_end: responsesHandlers.on_chat_model_end,
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_run_step_completed: { handle: () => {} },
+ on_chain_stream: { handle: () => {} },
+ on_chain_end: { handle: () => {} },
+ on_agent_update: { handle: () => {} },
+ on_custom_event: { handle: () => {} },
+ };
+
+ // Create and run the agent
+ const userId = req.user?.id ?? 'api-user';
+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;
+
+ const run = await createRun({
+ agents: [primaryConfig],
+ messages: formattedMessages,
+ indexTokenCountMap,
+ runId: responseId,
+ signal: abortController.signal,
+ customHandlers: handlers,
+ requestBody: {
+ messageId: responseId,
+ conversationId,
+ },
+ user: { id: userId },
+ });
+
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
+
+ // Process the stream
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
+ },
+ signal: abortController.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[Responses API] Tool Error "${toolId}"`, error);
+ },
+ },
+ });
+
+ // Finalize the stream
+ finalizeStream();
+ res.end();
+
+ // Save to database if store: true
+ if (request.store === true) {
+ try {
+ // Save conversation
+ await saveConversation(req, conversationId, agentId, agent);
+
+ // Save input messages
+ await saveInputMessages(req, conversationId, inputMessages, agentId);
+
+ // Build response for saving (use tracker with buildResponse for streaming)
+ const finalResponse = buildResponse(context, tracker, 'completed');
+ await saveResponseOutput(req, conversationId, responseId, finalResponse, agentId);
+
+ logger.debug(
+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
+ );
+ } catch (saveError) {
+ logger.error('[Responses API] Error saving response:', saveError);
+ // Don't fail the request if saving fails
+ }
+ }
+
+ // Wait for artifact processing after response ends (non-blocking)
+ if (artifactPromises.length > 0) {
+ Promise.all(artifactPromises).catch((artifactError) => {
+ logger.warn('[Responses API] Error processing artifacts:', artifactError);
+ });
+ }
+ } else {
+ // Non-streaming response
+ const aggregatorHandlers = createAggregatorEventHandlers(aggregator);
+
+ // Built-in handler for processing raw model stream chunks
+ const chatModelStreamHandler = new ChatModelStreamHandler();
+
+ // Artifact promises for processing tool outputs
+ /** @type {Promise<import('librechat-data-provider').TAttachment | null>[]} */
+ const artifactPromises = [];
+ const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId: null });
+
+ // Combine handlers
+ const handlers = {
+ on_chat_model_stream: {
+ handle: async (event, data, metadata, graph) => {
+ await chatModelStreamHandler.handle(event, data, metadata, graph);
+ },
+ },
+ on_message_delta: aggregatorHandlers.on_message_delta,
+ on_reasoning_delta: aggregatorHandlers.on_reasoning_delta,
+ on_run_step: aggregatorHandlers.on_run_step,
+ on_run_step_delta: aggregatorHandlers.on_run_step_delta,
+ on_chat_model_end: aggregatorHandlers.on_chat_model_end,
+ on_tool_end: new ToolEndHandler(toolEndCallback, logger),
+ on_run_step_completed: { handle: () => {} },
+ on_chain_stream: { handle: () => {} },
+ on_chain_end: { handle: () => {} },
+ on_agent_update: { handle: () => {} },
+ on_custom_event: { handle: () => {} },
+ };
+
+ // Create and run the agent
+ const userId = req.user?.id ?? 'api-user';
+ const userMCPAuthMap = primaryConfig.userMCPAuthMap;
+
+ const run = await createRun({
+ agents: [primaryConfig],
+ messages: formattedMessages,
+ indexTokenCountMap,
+ runId: responseId,
+ signal: abortController.signal,
+ customHandlers: handlers,
+ requestBody: {
+ messageId: responseId,
+ conversationId,
+ },
+ user: { id: userId },
+ });
+
+ if (!run) {
+ throw new Error('Failed to create agent run');
+ }
+
+ // Process the stream
+ const config = {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ user: createSafeUser(req.user),
+ ...(userMCPAuthMap != null && { userMCPAuthMap }),
+ },
+ signal: abortController.signal,
+ streamMode: 'values',
+ version: 'v2',
+ };
+
+ await run.processStream({ messages: formattedMessages }, config, {
+ callbacks: {
+ [Callback.TOOL_ERROR]: (graph, error, toolId) => {
+ logger.error(`[Responses API] Tool Error "${toolId}"`, error);
+ },
+ },
+ });
+
+ // Wait for artifacts before sending response
+ if (artifactPromises.length > 0) {
+ try {
+ await Promise.all(artifactPromises);
+ } catch (artifactError) {
+ logger.warn('[Responses API] Error processing artifacts:', artifactError);
+ }
+ }
+
+ // Build and send the response
+ const response = buildAggregatedResponse(context, aggregator);
+
+ // Save to database if store: true
+ if (request.store === true) {
+ try {
+ // Save conversation
+ await saveConversation(req, conversationId, agentId, agent);
+
+ // Save input messages
+ await saveInputMessages(req, conversationId, inputMessages, agentId);
+
+ // Save response output
+ await saveResponseOutput(req, conversationId, responseId, response, agentId);
+
+ logger.debug(
+ `[Responses API] Stored response ${responseId} in conversation ${conversationId}`,
+ );
+ } catch (saveError) {
+ logger.error('[Responses API] Error saving response:', saveError);
+ // Don't fail the request if saving fails
+ }
+ }
+
+ res.json(response);
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';
+ logger.error('[Responses API] Error:', error);
+
+ // Check if we already started streaming (headers sent)
+ if (res.headersSent) {
+ // Headers already sent, write error event and close
+ writeDone(res);
+ res.end();
+ } else {
+ sendResponsesErrorResponse(res, 500, errorMessage, 'server_error');
+ }
+ }
+};
+
+/**
+ * List available agents as models - GET /v1/models (also works with /v1/responses/models)
+ *
+ * Returns a list of available agents the user has remote access to.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ */
+const listModels = async (req, res) => {
+ try {
+ const userId = req.user?.id;
+ const userRole = req.user?.role;
+
+ if (!userId) {
+ return sendResponsesErrorResponse(res, 401, 'Authentication required', 'auth_error');
+ }
+
+ // Find agents the user has remote access to (VIEW permission on REMOTE_AGENT)
+ const accessibleAgentIds = await findAccessibleResources({
+ userId,
+ role: userRole,
+ resourceType: ResourceType.REMOTE_AGENT,
+ requiredPermissions: PermissionBits.VIEW,
+ });
+
+ // Get the accessible agents
+ let agents = [];
+ if (accessibleAgentIds.length > 0) {
+ agents = await getAgents({ _id: { $in: accessibleAgentIds } });
+ }
+
+ // Convert to models format
+ const models = agents.map((agent) => ({
+ id: agent.id,
+ object: 'model',
+ created: Math.floor(new Date(agent.createdAt).getTime() / 1000),
+ owned_by: agent.author ?? 'librechat',
+ // Additional metadata
+ name: agent.name,
+ description: agent.description,
+ provider: agent.provider,
+ }));
+
+ res.json({
+ object: 'list',
+ data: models,
+ });
+ } catch (error) {
+ logger.error('[Responses API] Error listing models:', error);
+ sendResponsesErrorResponse(
+ res,
+ 500,
+ error instanceof Error ? error.message : 'Failed to list models',
+ 'server_error',
+ );
+ }
+};
+
+/**
+ * Get Response - GET /v1/responses/:id
+ *
+ * Retrieves a stored response by its ID.
+ * The response ID maps to a conversationId in LibreChat's storage.
+ *
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ */
+const getResponse = async (req, res) => {
+ try {
+ const responseId = req.params.id;
+ const userId = req.user?.id;
+
+ if (!responseId) {
+ return sendResponsesErrorResponse(res, 400, 'Response ID is required');
+ }
+
+ // The responseId could be either the response ID or the conversation ID
+ // Try to find a conversation with this ID
+ const conversation = await getConvo(userId, responseId);
+
+ if (!conversation) {
+ return sendResponsesErrorResponse(
+ res,
+ 404,
+ `Response not found: ${responseId}`,
+ 'not_found',
+ 'response_not_found',
+ );
+ }
+
+ // Load messages for this conversation
+ const messages = await db.getMessages({ conversationId: responseId, user: userId });
+
+ if (!messages || messages.length === 0) {
+ return sendResponsesErrorResponse(
+ res,
+ 404,
+ `No messages found for response: ${responseId}`,
+ 'not_found',
+ 'response_not_found',
+ );
+ }
+
+ // Convert messages to Open Responses output format
+ const output = convertMessagesToOutputItems(messages);
+
+ // Find the last assistant message for usage info
+ const lastAssistantMessage = messages.filter((m) => !m.isCreatedByUser).pop();
+
+ // Build the response object
+ const response = {
+ id: responseId,
+ object: 'response',
+ created_at: Math.floor(new Date(conversation.createdAt || Date.now()).getTime() / 1000),
+ completed_at: Math.floor(new Date(conversation.updatedAt || Date.now()).getTime() / 1000),
+ status: 'completed',
+ incomplete_details: null,
+ model: conversation.agentId || conversation.model || 'unknown',
+ previous_response_id: null,
+ instructions: null,
+ output,
+ error: null,
+ tools: [],
+ tool_choice: 'auto',
+ truncation: 'disabled',
+ parallel_tool_calls: true,
+ text: { format: { type: 'text' } },
+ temperature: 1,
+ top_p: 1,
+ presence_penalty: 0,
+ frequency_penalty: 0,
+ top_logprobs: null,
+ reasoning: null,
+ user: userId,
+ usage: lastAssistantMessage?.tokenCount
+ ? {
+ input_tokens: 0,
+ output_tokens: lastAssistantMessage.tokenCount,
+ total_tokens: lastAssistantMessage.tokenCount,
+ }
+ : null,
+ max_output_tokens: null,
+ max_tool_calls: null,
+ store: true,
+ background: false,
+ service_tier: 'default',
+ metadata: {},
+ safety_identifier: null,
+ prompt_cache_key: null,
+ };
+
+ res.json(response);
+ } catch (error) {
+ logger.error('[Responses API] Error getting response:', error);
+ sendResponsesErrorResponse(
+ res,
+ 500,
+ error instanceof Error ? error.message : 'Failed to get response',
+ 'server_error',
+ );
+ }
+};
+
+module.exports = {
+ createResponse,
+ getResponse,
+ listModels,
+ setAppConfig,
+};
diff --git a/api/server/controllers/agents/v1.js b/api/server/controllers/agents/v1.js
index 9f0a4a2279..34078b2250 100644
--- a/api/server/controllers/agents/v1.js
+++ b/api/server/controllers/agents/v1.js
@@ -11,7 +11,9 @@ const {
convertOcrToContextInPlace,
} = require('@librechat/api');
const {
+ Time,
Tools,
+ CacheKeys,
Constants,
FileSources,
ResourceType,
@@ -21,8 +23,6 @@ const {
PermissionBits,
actionDelimiter,
removeNullishValues,
- CacheKeys,
- Time,
} = require('librechat-data-provider');
const {
getListAgentsByAccess,
@@ -94,16 +94,25 @@ const createAgentHandler = async (req, res) => {
const agent = await createAgent(agentData);
- // Automatically grant owner permissions to the creator
try {
- await grantPermission({
- principalType: PrincipalType.USER,
- principalId: userId,
- resourceType: ResourceType.AGENT,
- resourceId: agent._id,
- accessRoleId: AccessRoleIds.AGENT_OWNER,
- grantedBy: userId,
- });
+ await Promise.all([
+ grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: userId,
+ resourceType: ResourceType.AGENT,
+ resourceId: agent._id,
+ accessRoleId: AccessRoleIds.AGENT_OWNER,
+ grantedBy: userId,
+ }),
+ grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: userId,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: agent._id,
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ grantedBy: userId,
+ }),
+ ]);
logger.debug(
`[createAgent] Granted owner permissions to user ${userId} for agent ${agent.id}`,
);
@@ -396,16 +405,25 @@ const duplicateAgentHandler = async (req, res) => {
newAgentData.actions = agentActions;
const newAgent = await createAgent(newAgentData);
- // Automatically grant owner permissions to the duplicator
try {
- await grantPermission({
- principalType: PrincipalType.USER,
- principalId: userId,
- resourceType: ResourceType.AGENT,
- resourceId: newAgent._id,
- accessRoleId: AccessRoleIds.AGENT_OWNER,
- grantedBy: userId,
- });
+ await Promise.all([
+ grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: userId,
+ resourceType: ResourceType.AGENT,
+ resourceId: newAgent._id,
+ accessRoleId: AccessRoleIds.AGENT_OWNER,
+ grantedBy: userId,
+ }),
+ grantPermission({
+ principalType: PrincipalType.USER,
+ principalId: userId,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: newAgent._id,
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ grantedBy: userId,
+ }),
+ ]);
logger.debug(
`[duplicateAgent] Granted owner permissions to user ${userId} for duplicated agent ${newAgent.id}`,
);
diff --git a/api/server/experimental.js b/api/server/experimental.js
index 91ef9ef286..4a457abf61 100644
--- a/api/server/experimental.js
+++ b/api/server/experimental.js
@@ -299,6 +299,7 @@ if (cluster.isMaster) {
app.use('/api/auth', routes.auth);
app.use('/api/actions', routes.actions);
app.use('/api/keys', routes.keys);
+ app.use('/api/api-keys', routes.apiKeys);
app.use('/api/user', routes.user);
app.use('/api/search', routes.search);
app.use('/api/messages', routes.messages);
diff --git a/api/server/index.js b/api/server/index.js
index d5129c9a7e..fcd0229c9f 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -137,6 +137,7 @@ const startServer = async () => {
app.use('/api/admin', routes.adminAuth);
app.use('/api/actions', routes.actions);
app.use('/api/keys', routes.keys);
+ app.use('/api/api-keys', routes.apiKeys);
app.use('/api/user', routes.user);
app.use('/api/search', routes.search);
app.use('/api/messages', routes.messages);
diff --git a/api/server/middleware/checkSharePublicAccess.js b/api/server/middleware/checkSharePublicAccess.js
index c094d54acb..0e95b9f6f8 100644
--- a/api/server/middleware/checkSharePublicAccess.js
+++ b/api/server/middleware/checkSharePublicAccess.js
@@ -9,6 +9,7 @@ const resourceToPermissionType = {
[ResourceType.AGENT]: PermissionTypes.AGENTS,
[ResourceType.PROMPTGROUP]: PermissionTypes.PROMPTS,
[ResourceType.MCPSERVER]: PermissionTypes.MCP_SERVERS,
+ [ResourceType.REMOTE_AGENT]: PermissionTypes.REMOTE_AGENTS,
};
/**
diff --git a/api/server/routes/accessPermissions.js b/api/server/routes/accessPermissions.js
index 79e7f3ddca..45afec133b 100644
--- a/api/server/routes/accessPermissions.js
+++ b/api/server/routes/accessPermissions.js
@@ -53,6 +53,12 @@ const checkResourcePermissionAccess = (requiredPermission) => (req, res, next) =
requiredPermission,
resourceIdParam: 'resourceId',
});
+ } else if (resourceType === ResourceType.REMOTE_AGENT) {
+ middleware = canAccessResource({
+ resourceType: ResourceType.REMOTE_AGENT,
+ requiredPermission,
+ resourceIdParam: 'resourceId',
+ });
} else if (resourceType === ResourceType.PROMPTGROUP) {
middleware = canAccessResource({
resourceType: ResourceType.PROMPTGROUP,
diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.js
index e879d51452..442665d973 100644
--- a/api/server/routes/agents/__tests__/abort.spec.js
+++ b/api/server/routes/agents/__tests__/abort.spec.js
@@ -26,10 +26,12 @@ const mockGenerationJobManager = {
const mockSaveMessage = jest.fn();
jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
logger: mockLogger,
}));
jest.mock('@librechat/api', () => ({
+ ...jest.requireActual('@librechat/api'),
isEnabled: jest.fn().mockReturnValue(false),
GenerationJobManager: mockGenerationJobManager,
}));
diff --git a/api/server/routes/agents/__tests__/responses.spec.js b/api/server/routes/agents/__tests__/responses.spec.js
new file mode 100644
index 0000000000..4d83219b84
--- /dev/null
+++ b/api/server/routes/agents/__tests__/responses.spec.js
@@ -0,0 +1,1125 @@
+/**
+ * Open Responses API Integration Tests
+ *
+ * Tests the /v1/responses endpoint against the Open Responses specification
+ * compliance tests. Uses real Anthropic API for LLM calls.
+ *
+ * @see https://openresponses.org/specification
+ * @see https://github.com/openresponses/openresponses/blob/main/src/lib/compliance-tests.ts
+ */
+
+// Load environment variables from root .env file for API keys
+require('dotenv').config({ path: require('path').resolve(__dirname, '../../../../../.env') });
+
+const originalEnv = {
+ CREDS_KEY: process.env.CREDS_KEY,
+ CREDS_IV: process.env.CREDS_IV,
+};
+
+process.env.CREDS_KEY = '0123456789abcdef0123456789abcdef';
+process.env.CREDS_IV = '0123456789abcdef';
+
+/** Skip tests if ANTHROPIC_API_KEY is not available */
+const SKIP_INTEGRATION_TESTS = !process.env.ANTHROPIC_API_KEY;
+if (SKIP_INTEGRATION_TESTS) {
+ console.warn('ANTHROPIC_API_KEY not found - skipping integration tests');
+}
+
+jest.mock('meilisearch', () => ({
+ MeiliSearch: jest.fn().mockImplementation(() => ({
+ getIndex: jest.fn().mockRejectedValue(new Error('mocked')),
+ index: jest.fn().mockReturnValue({
+ getRawInfo: jest.fn().mockResolvedValue({ primaryKey: 'id' }),
+ updateSettings: jest.fn().mockResolvedValue({}),
+ addDocuments: jest.fn().mockResolvedValue({}),
+ updateDocuments: jest.fn().mockResolvedValue({}),
+ deleteDocument: jest.fn().mockResolvedValue({}),
+ }),
+ })),
+}));
+
+jest.mock('~/server/services/Config', () => ({
+ loadCustomConfig: jest.fn(() => Promise.resolve({})),
+ getAppConfig: jest.fn().mockResolvedValue({
+ paths: {
+ uploads: '/tmp',
+ dist: '/tmp/dist',
+ fonts: '/tmp/fonts',
+ assets: '/tmp/assets',
+ },
+ fileStrategy: 'local',
+ imageOutputType: 'PNG',
+ endpoints: {
+ agents: {
+ allowedProviders: ['anthropic', 'openAI'],
+ },
+ },
+ }),
+ setCachedTools: jest.fn(),
+ getCachedTools: jest.fn(),
+ getMCPServerTools: jest.fn().mockReturnValue([]),
+}));
+
+jest.mock('~/app/clients/tools', () => ({
+ createOpenAIImageTools: jest.fn(() => []),
+ createYouTubeTools: jest.fn(() => []),
+ manifestToolMap: {},
+ toolkits: [],
+}));
+
+jest.mock('~/config', () => ({
+ createMCPServersRegistry: jest.fn(),
+ createMCPManager: jest.fn().mockResolvedValue({
+ getAppToolFunctions: jest.fn().mockResolvedValue({}),
+ }),
+}));
+
+const express = require('express');
+const request = require('supertest');
+const mongoose = require('mongoose');
+const { v4: uuidv4 } = require('uuid');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+const { hashToken, getRandomValues, createModels } = require('@librechat/data-schemas');
+const {
+ SystemRoles,
+ ResourceType,
+ AccessRoleIds,
+ PrincipalType,
+ PrincipalModel,
+ PermissionBits,
+ EModelEndpoint,
+} = require('librechat-data-provider');
+
+/** @type {import('mongoose').Model} */
+let Agent;
+/** @type {import('mongoose').Model} */
+let AgentApiKey;
+/** @type {import('mongoose').Model} */
+let User;
+/** @type {import('mongoose').Model} */
+let AclEntry;
+/** @type {import('mongoose').Model} */
+let AccessRole;
+
+/**
+ * Parse SSE stream into events
+ * @param {string} text - Raw SSE text
+ * @returns {Array<{event: string, data: unknown}>}
+ */
+function parseSSEEvents(text) {
+ const events = [];
+ const lines = text.split('\n');
+
+ let currentEvent = '';
+ let currentData = '';
+
+ for (const line of lines) {
+ if (line.startsWith('event:')) {
+ currentEvent = line.slice(6).trim();
+ } else if (line.startsWith('data:')) {
+ currentData = line.slice(5).trim();
+ } else if (line === '' && currentData) {
+ if (currentData === '[DONE]') {
+ events.push({ event: 'done', data: '[DONE]' });
+ } else {
+ try {
+ const parsed = JSON.parse(currentData);
+ events.push({
+ event: currentEvent || parsed.type || 'unknown',
+ data: parsed,
+ });
+ } catch {
+ // Skip unparseable data
+ }
+ }
+ currentEvent = '';
+ currentData = '';
+ }
+ }
+
+ return events;
+}
+
+/**
+ * Valid streaming event types per Open Responses specification
+ * @see https://github.com/openresponses/openresponses/blob/main/src/lib/sse-parser.ts
+ */
+const VALID_STREAMING_EVENT_TYPES = new Set([
+ // Standard Open Responses events
+ 'response.created',
+ 'response.queued',
+ 'response.in_progress',
+ 'response.completed',
+ 'response.failed',
+ 'response.incomplete',
+ 'response.output_item.added',
+ 'response.output_item.done',
+ 'response.content_part.added',
+ 'response.content_part.done',
+ 'response.output_text.delta',
+ 'response.output_text.done',
+ 'response.refusal.delta',
+ 'response.refusal.done',
+ 'response.function_call_arguments.delta',
+ 'response.function_call_arguments.done',
+ 'response.reasoning_summary_part.added',
+ 'response.reasoning_summary_part.done',
+ 'response.reasoning.delta',
+ 'response.reasoning.done',
+ 'response.reasoning_summary_text.delta',
+ 'response.reasoning_summary_text.done',
+ 'response.output_text.annotation.added',
+ 'error',
+ // LibreChat extension events (prefixed per Open Responses spec)
+ // @see https://openresponses.org/specification#extending-streaming-events
+ 'librechat:attachment',
+]);
+
+/**
+ * Validate a streaming event against Open Responses spec
+ * @param {Object} event - Parsed event with data
+ * @returns {string[]} Array of validation errors
+ */
+function validateStreamingEvent(event) {
+ const errors = [];
+ const data = event.data;
+
+ if (!data || typeof data !== 'object') {
+ return errors; // Skip non-object data (e.g., [DONE])
+ }
+
+ const eventType = data.type;
+
+ // Check event type is valid
+ if (!VALID_STREAMING_EVENT_TYPES.has(eventType)) {
+ errors.push(`Invalid event type: ${eventType}`);
+ return errors;
+ }
+
+ // Validate required fields based on event type
+ switch (eventType) {
+ case 'response.output_text.delta':
+ if (typeof data.sequence_number !== 'number') {
+ errors.push('response.output_text.delta: missing sequence_number');
+ }
+ if (typeof data.item_id !== 'string') {
+ errors.push('response.output_text.delta: missing item_id');
+ }
+ if (typeof data.output_index !== 'number') {
+ errors.push('response.output_text.delta: missing output_index');
+ }
+ if (typeof data.content_index !== 'number') {
+ errors.push('response.output_text.delta: missing content_index');
+ }
+ if (typeof data.delta !== 'string') {
+ errors.push('response.output_text.delta: missing delta');
+ }
+ if (!Array.isArray(data.logprobs)) {
+ errors.push('response.output_text.delta: missing logprobs array');
+ }
+ break;
+
+ case 'response.output_text.done':
+ if (typeof data.sequence_number !== 'number') {
+ errors.push('response.output_text.done: missing sequence_number');
+ }
+ if (typeof data.item_id !== 'string') {
+ errors.push('response.output_text.done: missing item_id');
+ }
+ if (typeof data.output_index !== 'number') {
+ errors.push('response.output_text.done: missing output_index');
+ }
+ if (typeof data.content_index !== 'number') {
+ errors.push('response.output_text.done: missing content_index');
+ }
+ if (typeof data.text !== 'string') {
+ errors.push('response.output_text.done: missing text');
+ }
+ if (!Array.isArray(data.logprobs)) {
+ errors.push('response.output_text.done: missing logprobs array');
+ }
+ break;
+
+ case 'response.reasoning.delta':
+ if (typeof data.sequence_number !== 'number') {
+ errors.push('response.reasoning.delta: missing sequence_number');
+ }
+ if (typeof data.item_id !== 'string') {
+ errors.push('response.reasoning.delta: missing item_id');
+ }
+ if (typeof data.output_index !== 'number') {
+ errors.push('response.reasoning.delta: missing output_index');
+ }
+ if (typeof data.content_index !== 'number') {
+ errors.push('response.reasoning.delta: missing content_index');
+ }
+ if (typeof data.delta !== 'string') {
+ errors.push('response.reasoning.delta: missing delta');
+ }
+ break;
+
+ case 'response.reasoning.done':
+ if (typeof data.sequence_number !== 'number') {
+ errors.push('response.reasoning.done: missing sequence_number');
+ }
+ if (typeof data.item_id !== 'string') {
+ errors.push('response.reasoning.done: missing item_id');
+ }
+ if (typeof data.output_index !== 'number') {
+ errors.push('response.reasoning.done: missing output_index');
+ }
+ if (typeof data.content_index !== 'number') {
+ errors.push('response.reasoning.done: missing content_index');
+ }
+ if (typeof data.text !== 'string') {
+ errors.push('response.reasoning.done: missing text');
+ }
+ break;
+
+ case 'response.in_progress':
+ case 'response.completed':
+ case 'response.failed':
+ if (!data.response || typeof data.response !== 'object') {
+ errors.push(`${eventType}: missing response object`);
+ }
+ break;
+
+ case 'response.output_item.added':
+ case 'response.output_item.done':
+ if (typeof data.output_index !== 'number') {
+ errors.push(`${eventType}: missing output_index`);
+ }
+ if (!data.item || typeof data.item !== 'object') {
+ errors.push(`${eventType}: missing item object`);
+ }
+ break;
+ }
+
+ return errors;
+}
+
+/**
+ * Validate all streaming events and return errors
+ * @param {Array} events - Array of parsed events
+ * @returns {string[]} Array of all validation errors
+ */
+function validateAllStreamingEvents(events) {
+ const allErrors = [];
+ for (const event of events) {
+ const errors = validateStreamingEvent(event);
+ allErrors.push(...errors);
+ }
+ return allErrors;
+}
+
+/**
+ * Create a test agent with Anthropic provider
+ * @param {Object} overrides
+ * @returns {Promise<Object>}
+ */
+async function createTestAgent(overrides = {}) {
+ const timestamp = new Date();
+ const agentData = {
+ id: `agent_${uuidv4().replace(/-/g, '').substring(0, 21)}`,
+ name: 'Test Anthropic Agent',
+ description: 'An agent for testing Open Responses API',
+ instructions: 'You are a helpful assistant. Be concise.',
+ provider: EModelEndpoint.anthropic,
+ model: 'claude-sonnet-4-5-20250929',
+ author: new mongoose.Types.ObjectId(),
+ tools: [],
+ model_parameters: {},
+ ...overrides,
+ };
+
+ const versionData = { ...agentData };
+ delete versionData.author;
+
+ const initialAgentData = {
+ ...agentData,
+ versions: [
+ {
+ ...versionData,
+ createdAt: timestamp,
+ updatedAt: timestamp,
+ },
+ ],
+ category: 'general',
+ };
+
+ return (await Agent.create(initialAgentData)).toObject();
+}
+
+/**
+ * Create an agent with extended thinking enabled
+ * @param {Object} overrides
+ * @returns {Promise<Object>}
+ */
+async function createThinkingAgent(overrides = {}) {
+ return createTestAgent({
+ name: 'Test Thinking Agent',
+ description: 'An agent with extended thinking enabled',
+ model_parameters: {
+ thinking: {
+ type: 'enabled',
+ budget_tokens: 5000,
+ },
+ },
+ ...overrides,
+ });
+}
+
+const describeWithApiKey = SKIP_INTEGRATION_TESTS ? describe.skip : describe;
+
+describeWithApiKey('Open Responses API Integration Tests', () => {
+ // Increase timeout for real API calls
+ jest.setTimeout(120000);
+
+ let mongoServer;
+ let app;
+ let testAgent;
+ let thinkingAgent;
+ let testUser;
+ let testApiKey; // The raw API key for Authorization header
+
+ afterAll(() => {
+ process.env.CREDS_KEY = originalEnv.CREDS_KEY;
+ process.env.CREDS_IV = originalEnv.CREDS_IV;
+ });
+
+ beforeAll(async () => {
+ // Start MongoDB Memory Server
+ mongoServer = await MongoMemoryServer.create();
+ const mongoUri = mongoServer.getUri();
+
+ // Connect to MongoDB
+ await mongoose.connect(mongoUri);
+
+ // Register all models
+ const models = createModels(mongoose);
+
+ // Get models
+ Agent = models.Agent;
+ AgentApiKey = models.AgentApiKey;
+ User = models.User;
+ AclEntry = models.AclEntry;
+ AccessRole = models.AccessRole;
+
+ // Create minimal Express app with just the responses routes
+ app = express();
+ app.use(express.json());
+
+ // Mount the responses routes
+ const responsesRoutes = require('~/server/routes/agents/responses');
+ app.use('/api/agents/v1/responses', responsesRoutes);
+
+ // Create test user
+ testUser = await User.create({
+ name: 'Test API User',
+ username: 'testapiuser',
+ email: '[email protected]',
+ emailVerified: true,
+ provider: 'local',
+ role: SystemRoles.ADMIN,
+ });
+
+ // Create REMOTE_AGENT access roles (if they don't exist)
+ const existingRoles = await AccessRole.find({
+ accessRoleId: {
+ $in: [
+ AccessRoleIds.REMOTE_AGENT_VIEWER,
+ AccessRoleIds.REMOTE_AGENT_EDITOR,
+ AccessRoleIds.REMOTE_AGENT_OWNER,
+ ],
+ },
+ });
+
+ if (existingRoles.length === 0) {
+ await AccessRole.create([
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,
+ name: 'API Viewer',
+ description: 'Can query the agent via API',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits: PermissionBits.VIEW,
+ },
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,
+ name: 'API Editor',
+ description: 'Can view and modify the agent via API',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits: PermissionBits.VIEW | PermissionBits.EDIT,
+ },
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ name: 'API Owner',
+ description: 'Full API access + can grant remote access to others',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits:
+ PermissionBits.VIEW |
+ PermissionBits.EDIT |
+ PermissionBits.DELETE |
+ PermissionBits.SHARE,
+ },
+ ]);
+ }
+
+ // Generate and create an API key for the test user
+ const rawKey = `sk-${await getRandomValues(32)}`;
+ const keyHash = await hashToken(rawKey);
+ const keyPrefix = rawKey.substring(0, 8);
+
+ await AgentApiKey.create({
+ userId: testUser._id,
+ name: 'Test API Key',
+ keyHash,
+ keyPrefix,
+ });
+
+ testApiKey = rawKey;
+
+ // Create test agents with the test user as author
+ testAgent = await createTestAgent({ author: testUser._id });
+ thinkingAgent = await createThinkingAgent({ author: testUser._id });
+
+ // Grant REMOTE_AGENT permissions for the test agents
+ await AclEntry.create([
+ {
+ principalType: PrincipalType.USER,
+ principalModel: PrincipalModel.USER,
+ principalId: testUser._id,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: testAgent._id,
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ permBits:
+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE,
+ },
+ {
+ principalType: PrincipalType.USER,
+ principalModel: PrincipalModel.USER,
+ principalId: testUser._id,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: thinkingAgent._id,
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ permBits:
+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE,
+ },
+ ]);
+ }, 60000);
+
+ afterAll(async () => {
+ await mongoose.disconnect();
+ await mongoServer.stop();
+ });
+
+ beforeEach(async () => {
+ // Clean up any test data between tests if needed
+ });
+
+ /* ===========================================================================
+ * COMPLIANCE TESTS
+ * Based on: https://github.com/openresponses/openresponses/blob/main/src/lib/compliance-tests.ts
+ * =========================================================================== */
+
+ /** Helper to add auth header to requests */
+ const authRequest = () => ({
+ post: (url) => request(app).post(url).set('Authorization', `Bearer ${testApiKey}`),
+ get: (url) => request(app).get(url).set('Authorization', `Bearer ${testApiKey}`),
+ });
+
+ describe('Compliance Tests', () => {
+ describe('basic-response', () => {
+ it('should return a valid ResponseResource for a simple text request', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'Say hello in exactly 3 words.',
+ },
+ ],
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body).toBeDefined();
+
+ // Validate ResponseResource schema
+ const body = response.body;
+ expect(body.id).toMatch(/^resp_/);
+ expect(body.object).toBe('response');
+ expect(typeof body.created_at).toBe('number');
+ expect(body.status).toBe('completed');
+ expect(body.model).toBe(testAgent.id);
+
+ // Validate output
+ expect(Array.isArray(body.output)).toBe(true);
+ expect(body.output.length).toBeGreaterThan(0);
+
+ // Should have at least one message item
+ const messageItem = body.output.find((item) => item.type === 'message');
+ expect(messageItem).toBeDefined();
+ expect(messageItem.role).toBe('assistant');
+ expect(messageItem.status).toBe('completed');
+ expect(Array.isArray(messageItem.content)).toBe(true);
+ });
+ });
+
+ describe('streaming-response', () => {
+ it('should return valid SSE streaming events', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'Count from 1 to 5.',
+ },
+ ],
+ stream: true,
+ })
+ .buffer(true)
+ .parse((res, callback) => {
+ let data = '';
+ res.on('data', (chunk) => {
+ data += chunk.toString();
+ });
+ res.on('end', () => {
+ callback(null, data);
+ });
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.headers['content-type']).toMatch(/text\/event-stream/);
+
+ const events = parseSSEEvents(response.body);
+ expect(events.length).toBeGreaterThan(0);
+
+ // Validate all streaming events against Open Responses spec
+ // This catches issues like:
+ // - Invalid event types (e.g., response.reasoning_text.delta instead of response.reasoning.delta)
+ // - Missing required fields (e.g., logprobs on output_text events)
+ const validationErrors = validateAllStreamingEvents(events);
+ if (validationErrors.length > 0) {
+ console.error('Streaming event validation errors:', validationErrors);
+ }
+ expect(validationErrors).toEqual([]);
+
+ // Validate streaming event types
+ const eventTypes = events.map((e) => e.event);
+
+ // Should have response.created first (per Open Responses spec)
+ expect(eventTypes).toContain('response.created');
+
+ // Should have response.in_progress
+ expect(eventTypes).toContain('response.in_progress');
+
+ // response.created should come before response.in_progress
+ const createdIdx = eventTypes.indexOf('response.created');
+ const inProgressIdx = eventTypes.indexOf('response.in_progress');
+ expect(createdIdx).toBeLessThan(inProgressIdx);
+
+ // Should have response.completed or response.failed
+ expect(eventTypes.some((t) => t === 'response.completed' || t === 'response.failed')).toBe(
+ true,
+ );
+
+ // Should have [DONE]
+ expect(eventTypes).toContain('done');
+
+ // Validate response.completed has full response
+ const completedEvent = events.find((e) => e.event === 'response.completed');
+ if (completedEvent) {
+ expect(completedEvent.data.response).toBeDefined();
+ expect(completedEvent.data.response.status).toBe('completed');
+ expect(completedEvent.data.response.output.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('should emit valid event types per Open Responses spec', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'Say hi.',
+ },
+ ],
+ stream: true,
+ })
+ .buffer(true)
+ .parse((res, callback) => {
+ let data = '';
+ res.on('data', (chunk) => {
+ data += chunk.toString();
+ });
+ res.on('end', () => {
+ callback(null, data);
+ });
+ });
+
+ expect(response.status).toBe(200);
+
+ const events = parseSSEEvents(response.body);
+
+ // Check all event types are valid
+ for (const event of events) {
+ if (event.data && typeof event.data === 'object' && event.data.type) {
+ expect(VALID_STREAMING_EVENT_TYPES.has(event.data.type)).toBe(true);
+ }
+ }
+ });
+
+ it('should include logprobs array in output_text events', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'Say one word.',
+ },
+ ],
+ stream: true,
+ })
+ .buffer(true)
+ .parse((res, callback) => {
+ let data = '';
+ res.on('data', (chunk) => {
+ data += chunk.toString();
+ });
+ res.on('end', () => {
+ callback(null, data);
+ });
+ });
+
+ expect(response.status).toBe(200);
+
+ const events = parseSSEEvents(response.body);
+
+ // Find output_text delta/done events and verify logprobs
+ const textDeltaEvents = events.filter(
+ (e) => e.data && e.data.type === 'response.output_text.delta',
+ );
+ const textDoneEvents = events.filter(
+ (e) => e.data && e.data.type === 'response.output_text.done',
+ );
+
+ // Should have at least one output_text event
+ expect(textDeltaEvents.length + textDoneEvents.length).toBeGreaterThan(0);
+
+ // All output_text.delta events must have logprobs array
+ for (const event of textDeltaEvents) {
+ expect(Array.isArray(event.data.logprobs)).toBe(true);
+ }
+
+ // All output_text.done events must have logprobs array
+ for (const event of textDoneEvents) {
+ expect(Array.isArray(event.data.logprobs)).toBe(true);
+ }
+ });
+ });
+
+ describe('system-prompt', () => {
+ it('should handle developer role messages in input (as system)', async () => {
+ // Note: For Anthropic, system messages must be first and there can only be one.
+ // Since the agent already has instructions, we use 'developer' role which
+ // gets merged into the system prompt, or we test with a simple user message
+ // that instructs the behavior.
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'Pretend you are a pirate and say hello in pirate speak.',
+ },
+ ],
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body.status).toBe('completed');
+ expect(response.body.output.length).toBeGreaterThan(0);
+
+ // The response should reflect the pirate persona
+ const messageItem = response.body.output.find((item) => item.type === 'message');
+ expect(messageItem).toBeDefined();
+ expect(messageItem.content.length).toBeGreaterThan(0);
+ });
+ });
+
+ describe('multi-turn', () => {
+ it('should handle multi-turn conversation history', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: testAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'My name is Alice.',
+ },
+ {
+ type: 'message',
+ role: 'assistant',
+ content: 'Hello Alice! Nice to meet you. How can I help you today?',
+ },
+ {
+ type: 'message',
+ role: 'user',
+ content: 'What is my name?',
+ },
+ ],
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body.status).toBe('completed');
+
+ // The response should reference "Alice"
+ const messageItem = response.body.output.find((item) => item.type === 'message');
+ expect(messageItem).toBeDefined();
+
+ const textContent = messageItem.content.find((c) => c.type === 'output_text');
+ expect(textContent).toBeDefined();
+ expect(textContent.text.toLowerCase()).toContain('alice');
+ });
+ });
+
+ // Note: tool-calling test requires tool setup which may need additional configuration
+ // Note: image-input test requires vision-capable model
+
+ describe('string-input', () => {
+ it('should accept simple string input', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ model: testAgent.id,
+ input: 'Hello!',
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body.status).toBe('completed');
+ expect(response.body.output.length).toBeGreaterThan(0);
+ });
+ });
+ });
+
+ /* ===========================================================================
+ * EXTENDED THINKING TESTS
+ * Tests reasoning output from Claude models with extended thinking enabled
+ * =========================================================================== */
+
+ describe('Extended Thinking', () => {
+ it('should return reasoning output when thinking is enabled', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: thinkingAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'What is 15 * 7? Think step by step.',
+ },
+ ],
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.body.status).toBe('completed');
+
+ // Check for reasoning item in output
+ const reasoningItem = response.body.output.find((item) => item.type === 'reasoning');
+ // If reasoning is present, validate its structure per Open Responses spec
+ // Note: reasoning items do NOT have a 'status' field per the spec
+ // @see https://github.com/openresponses/openresponses/blob/main/src/generated/kubb/zod/reasoningBodySchema.ts
+ if (reasoningItem) {
+ expect(reasoningItem).toHaveProperty('id');
+ expect(reasoningItem).toHaveProperty('type', 'reasoning');
+ // Note: 'status' is NOT a field on reasoning items per the spec
+ expect(reasoningItem).toHaveProperty('summary');
+ expect(Array.isArray(reasoningItem.summary)).toBe(true);
+
+ // Validate content items
+ if (reasoningItem.content && reasoningItem.content.length > 0) {
+ const reasoningContent = reasoningItem.content[0];
+ expect(reasoningContent).toHaveProperty('type', 'reasoning_text');
+ expect(reasoningContent).toHaveProperty('text');
+ }
+ }
+
+ const messageItem = response.body.output.find((item) => item.type === 'message');
+ expect(messageItem).toBeDefined();
+ });
+
+ it('should stream reasoning events when thinking is enabled', async () => {
+ const response = await authRequest()
+ .post('/api/agents/v1/responses')
+ .send({
+ model: thinkingAgent.id,
+ input: [
+ {
+ type: 'message',
+ role: 'user',
+ content: 'What is 12 + 8? Think step by step.',
+ },
+ ],
+ stream: true,
+ })
+ .buffer(true)
+ .parse((res, callback) => {
+ let data = '';
+ res.on('data', (chunk) => {
+ data += chunk.toString();
+ });
+ res.on('end', () => {
+ callback(null, data);
+ });
+ });
+
+ expect(response.status).toBe(200);
+
+ const events = parseSSEEvents(response.body);
+
+ // Validate all events against Open Responses spec
+ const validationErrors = validateAllStreamingEvents(events);
+ if (validationErrors.length > 0) {
+ console.error('Reasoning streaming event validation errors:', validationErrors);
+ }
+ expect(validationErrors).toEqual([]);
+
+ // Check for reasoning-related events using correct event types per Open Responses spec
+ // Note: The spec uses response.reasoning.delta NOT response.reasoning_text.delta
+ const reasoningDeltaEvents = events.filter(
+ (e) => e.data && e.data.type === 'response.reasoning.delta',
+ );
+ const reasoningDoneEvents = events.filter(
+ (e) => e.data && e.data.type === 'response.reasoning.done',
+ );
+
+ // If reasoning events are present, validate their structure
+ if (reasoningDeltaEvents.length > 0) {
+ const deltaEvent = reasoningDeltaEvents[0];
+ expect(deltaEvent.data).toHaveProperty('item_id');
+ expect(deltaEvent.data).toHaveProperty('delta');
+ expect(deltaEvent.data).toHaveProperty('output_index');
+ expect(deltaEvent.data).toHaveProperty('content_index');
+ expect(deltaEvent.data).toHaveProperty('sequence_number');
+ }
+
+ if (reasoningDoneEvents.length > 0) {
+ const doneEvent = reasoningDoneEvents[0];
+ expect(doneEvent.data).toHaveProperty('item_id');
+ expect(doneEvent.data).toHaveProperty('text');
+ expect(doneEvent.data).toHaveProperty('output_index');
+ expect(doneEvent.data).toHaveProperty('content_index');
+ expect(doneEvent.data).toHaveProperty('sequence_number');
+ }
+
+ // Verify stream completed properly
+ const eventTypes = events.map((e) => e.event);
+ expect(eventTypes).toContain('response.completed');
+ });
+ });
+
+ /* ===========================================================================
+ * SCHEMA VALIDATION TESTS
+ * Verify response schema compliance
+ * =========================================================================== */
+
+ describe('Schema Validation', () => {
+ it('should include all required fields in response', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ model: testAgent.id,
+ input: 'Test',
+ });
+
+ expect(response.status).toBe(200);
+ const body = response.body;
+
+ // Required fields per Open Responses spec
+ expect(body).toHaveProperty('id');
+ expect(body).toHaveProperty('object', 'response');
+ expect(body).toHaveProperty('created_at');
+ expect(body).toHaveProperty('completed_at');
+ expect(body).toHaveProperty('status');
+ expect(body).toHaveProperty('model');
+ expect(body).toHaveProperty('output');
+ expect(body).toHaveProperty('tools');
+ expect(body).toHaveProperty('tool_choice');
+ expect(body).toHaveProperty('truncation');
+ expect(body).toHaveProperty('parallel_tool_calls');
+ expect(body).toHaveProperty('text');
+ expect(body).toHaveProperty('temperature');
+ expect(body).toHaveProperty('top_p');
+ expect(body).toHaveProperty('presence_penalty');
+ expect(body).toHaveProperty('frequency_penalty');
+ expect(body).toHaveProperty('top_logprobs');
+ expect(body).toHaveProperty('store');
+ expect(body).toHaveProperty('background');
+ expect(body).toHaveProperty('service_tier');
+ expect(body).toHaveProperty('metadata');
+
+ // top_logprobs must be a number (not null)
+ expect(typeof body.top_logprobs).toBe('number');
+
+ // Usage must have required detail fields
+ expect(body).toHaveProperty('usage');
+ expect(body.usage).toHaveProperty('input_tokens');
+ expect(body.usage).toHaveProperty('output_tokens');
+ expect(body.usage).toHaveProperty('total_tokens');
+ expect(body.usage).toHaveProperty('input_tokens_details');
+ expect(body.usage).toHaveProperty('output_tokens_details');
+ expect(body.usage.input_tokens_details).toHaveProperty('cached_tokens');
+ expect(body.usage.output_tokens_details).toHaveProperty('reasoning_tokens');
+ });
+
+ it('should have valid message item structure', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ model: testAgent.id,
+ input: 'Hello',
+ });
+
+ expect(response.status).toBe(200);
+
+ const messageItem = response.body.output.find((item) => item.type === 'message');
+ expect(messageItem).toBeDefined();
+
+ // Message item required fields
+ expect(messageItem).toHaveProperty('type', 'message');
+ expect(messageItem).toHaveProperty('id');
+ expect(messageItem).toHaveProperty('status');
+ expect(messageItem).toHaveProperty('role', 'assistant');
+ expect(messageItem).toHaveProperty('content');
+ expect(Array.isArray(messageItem.content)).toBe(true);
+
+ // Content part structure - verify all required fields
+ if (messageItem.content.length > 0) {
+ const textContent = messageItem.content.find((c) => c.type === 'output_text');
+ if (textContent) {
+ expect(textContent).toHaveProperty('type', 'output_text');
+ expect(textContent).toHaveProperty('text');
+ expect(textContent).toHaveProperty('annotations');
+ expect(textContent).toHaveProperty('logprobs');
+ expect(Array.isArray(textContent.annotations)).toBe(true);
+ expect(Array.isArray(textContent.logprobs)).toBe(true);
+ }
+ }
+
+ // Verify reasoning item has required summary field
+ const reasoningItem = response.body.output.find((item) => item.type === 'reasoning');
+ if (reasoningItem) {
+ expect(reasoningItem).toHaveProperty('type', 'reasoning');
+ expect(reasoningItem).toHaveProperty('id');
+ expect(reasoningItem).toHaveProperty('summary');
+ expect(Array.isArray(reasoningItem.summary)).toBe(true);
+ }
+ });
+ });
+
+ /* ===========================================================================
+ * RESPONSE STORAGE TESTS
+ * Tests for store: true and GET /v1/responses/:id
+ * =========================================================================== */
+
+ describe('Response Storage', () => {
+ it('should store response when store: true and retrieve it', async () => {
+ // Create a stored response
+ const createResponse = await authRequest().post('/api/agents/v1/responses').send({
+ model: testAgent.id,
+ input: 'Remember this: The answer is 42.',
+ store: true,
+ });
+
+ expect(createResponse.status).toBe(200);
+ expect(createResponse.body.status).toBe('completed');
+
+ const responseId = createResponse.body.id;
+ expect(responseId).toMatch(/^resp_/);
+
+ // Small delay to ensure database write completes
+ await new Promise((resolve) => setTimeout(resolve, 500));
+
+ // Retrieve the stored response
+ const getResponseResult = await authRequest().get(`/api/agents/v1/responses/${responseId}`);
+
+ // Note: The response might be stored under conversationId, not responseId
+ // If we get 404, that's expected behavior for now since we store by conversationId
+ if (getResponseResult.status === 200) {
+ expect(getResponseResult.body.object).toBe('response');
+ expect(getResponseResult.body.status).toBe('completed');
+ expect(getResponseResult.body.output.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('should return 404 for non-existent response', async () => {
+ const response = await authRequest().get('/api/agents/v1/responses/resp_nonexistent123');
+
+ expect(response.status).toBe(404);
+ expect(response.body.error).toBeDefined();
+ });
+ });
+
+ /* ===========================================================================
+ * ERROR HANDLING TESTS
+ * =========================================================================== */
+
+ describe('Error Handling', () => {
+ it('should return error for missing model', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ input: 'Hello',
+ });
+
+ expect(response.status).toBe(400);
+ expect(response.body.error).toBeDefined();
+ });
+
+ it('should return error for missing input', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ model: testAgent.id,
+ });
+
+ expect(response.status).toBe(400);
+ expect(response.body.error).toBeDefined();
+ });
+
+ it('should return error for non-existent agent', async () => {
+ const response = await authRequest().post('/api/agents/v1/responses').send({
+ model: 'agent_nonexistent123456789',
+ input: 'Hello',
+ });
+
+ expect(response.status).toBe(404);
+ expect(response.body.error).toBeDefined();
+ });
+ });
+
+ /* ===========================================================================
+ * MODELS ENDPOINT TESTS
+ * =========================================================================== */
+
+ describe('GET /v1/responses/models', () => {
+ it('should list available agents as models', async () => {
+ const response = await authRequest().get('/api/agents/v1/responses/models');
+
+ expect(response.status).toBe(200);
+ expect(response.body.object).toBe('list');
+ expect(Array.isArray(response.body.data)).toBe(true);
+
+ // Should include our test agent
+ const foundAgent = response.body.data.find((m) => m.id === testAgent.id);
+ expect(foundAgent).toBeDefined();
+ expect(foundAgent.object).toBe('model');
+ expect(foundAgent.name).toBe(testAgent.name);
+ });
+ });
+});
diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js
index bf790aeee8..f8d39cb4d8 100644
--- a/api/server/routes/agents/index.js
+++ b/api/server/routes/agents/index.js
@@ -10,6 +10,8 @@ const {
messageUserLimiter,
} = require('~/server/middleware');
const { saveMessage } = require('~/models');
+const openai = require('./openai');
+const responses = require('./responses');
const { v1 } = require('./v1');
const chat = require('./chat');
@@ -17,6 +19,20 @@ const { LIMIT_MESSAGE_IP, LIMIT_MESSAGE_USER } = process.env ?? {};
const router = express.Router();
+/**
+ * Open Responses API routes (API key authentication handled in route file)
+ * Mounted at /agents/v1/responses (full path: /api/agents/v1/responses)
+ * NOTE: Must be mounted BEFORE /v1 to avoid being caught by the less specific route
+ * @see https://openresponses.org/specification
+ */
+router.use('/v1/responses', responses);
+
+/**
+ * OpenAI-compatible API routes (API key authentication handled in route file)
+ * Mounted at /agents/v1 (full path: /api/agents/v1/chat/completions)
+ */
+router.use('/v1', openai);
+
router.use(requireJwtAuth);
router.use(checkBan);
router.use(uaParser);
diff --git a/api/server/routes/agents/openai.js b/api/server/routes/agents/openai.js
new file mode 100644
index 0000000000..9a0d9a3564
--- /dev/null
+++ b/api/server/routes/agents/openai.js
@@ -0,0 +1,110 @@
+/**
+ * OpenAI-compatible API routes for LibreChat agents.
+ *
+ * Provides a /v1/chat/completions compatible interface for
+ * interacting with LibreChat agents remotely via API.
+ *
+ * Usage:
+ * POST /v1/chat/completions - Chat with an agent
+ * GET /v1/models - List available agents
+ * GET /v1/models/:model - Get agent details
+ *
+ * Request format:
+ * {
+ * "model": "agent_id_here",
+ * "messages": [{"role": "user", "content": "Hello!"}],
+ * "stream": true
+ * }
+ */
+const express = require('express');
+const { PermissionTypes, Permissions } = require('librechat-data-provider');
+const {
+ generateCheckAccess,
+ createRequireApiKeyAuth,
+ createCheckRemoteAgentAccess,
+} = require('@librechat/api');
+const {
+ OpenAIChatCompletionController,
+ ListModelsController,
+ GetModelController,
+} = require('~/server/controllers/agents/openai');
+const { getEffectivePermissions } = require('~/server/services/PermissionService');
+const { validateAgentApiKey, findUser } = require('~/models');
+const { configMiddleware } = require('~/server/middleware');
+const { getRoleByName } = require('~/models/Role');
+const { getAgent } = require('~/models/Agent');
+
+const router = express.Router();
+
+const requireApiKeyAuth = createRequireApiKeyAuth({
+ validateAgentApiKey,
+ findUser,
+});
+
+const checkRemoteAgentsFeature = generateCheckAccess({
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ permissions: [Permissions.USE],
+ getRoleByName,
+});
+
+const checkAgentPermission = createCheckRemoteAgentAccess({
+ getAgent,
+ getEffectivePermissions,
+});
+
+router.use(requireApiKeyAuth);
+router.use(configMiddleware);
+router.use(checkRemoteAgentsFeature);
+
+/**
+ * @route POST /v1/chat/completions
+ * @desc OpenAI-compatible chat completions with agents
+ * @access Private (API key auth required)
+ *
+ * Request body:
+ * {
+ * "model": "agent_id", // Required: The agent ID to use
+ * "messages": [...], // Required: Array of chat messages
+ * "stream": true, // Optional: Whether to stream (default: false)
+ * "conversation_id": "...", // Optional: Conversation ID for context
+ * "parent_message_id": "..." // Optional: Parent message for threading
+ * }
+ *
+ * Response (streaming):
+ * - SSE stream with OpenAI chat.completion.chunk format
+ * - Includes delta.reasoning for thinking/reasoning content
+ *
+ * Response (non-streaming):
+ * - Standard OpenAI chat.completion format
+ */
+router.post('/chat/completions', checkAgentPermission, OpenAIChatCompletionController);
+
+/**
+ * @route GET /v1/models
+ * @desc List available agents as models
+ * @access Private (API key auth required)
+ *
+ * Response:
+ * {
+ * "object": "list",
+ * "data": [
+ * {
+ * "id": "agent_id",
+ * "object": "model",
+ * "name": "Agent Name",
+ * "provider": "openai",
+ * ...
+ * }
+ * ]
+ * }
+ */
+router.get('/models', ListModelsController);
+
+/**
+ * @route GET /v1/models/:model
+ * @desc Get details for a specific agent/model
+ * @access Private (API key auth required)
+ */
+router.get('/models/:model', GetModelController);
+
+module.exports = router;
diff --git a/api/server/routes/agents/responses.js b/api/server/routes/agents/responses.js
new file mode 100644
index 0000000000..431942e921
--- /dev/null
+++ b/api/server/routes/agents/responses.js
@@ -0,0 +1,144 @@
+/**
+ * Open Responses API routes for LibreChat agents.
+ *
+ * Implements the Open Responses specification for a forward-looking,
+ * agentic API that uses items as the fundamental unit and semantic
+ * streaming events.
+ *
+ * Usage:
+ * POST /v1/responses - Create a response
+ * GET /v1/models - List available agents
+ *
+ * Request format:
+ * {
+ * "model": "agent_id_here",
+ * "input": "Hello!" or [{ type: "message", role: "user", content: "Hello!" }],
+ * "stream": true,
+ * "previous_response_id": "optional_conversation_id"
+ * }
+ *
+ * @see https://openresponses.org/specification
+ */
+const express = require('express');
+const { PermissionTypes, Permissions } = require('librechat-data-provider');
+const {
+ generateCheckAccess,
+ createRequireApiKeyAuth,
+ createCheckRemoteAgentAccess,
+} = require('@librechat/api');
+const {
+ createResponse,
+ getResponse,
+ listModels,
+} = require('~/server/controllers/agents/responses');
+const { getEffectivePermissions } = require('~/server/services/PermissionService');
+const { validateAgentApiKey, findUser } = require('~/models');
+const { configMiddleware } = require('~/server/middleware');
+const { getRoleByName } = require('~/models/Role');
+const { getAgent } = require('~/models/Agent');
+
+const router = express.Router();
+
+const requireApiKeyAuth = createRequireApiKeyAuth({
+ validateAgentApiKey,
+ findUser,
+});
+
+const checkRemoteAgentsFeature = generateCheckAccess({
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ permissions: [Permissions.USE],
+ getRoleByName,
+});
+
+const checkAgentPermission = createCheckRemoteAgentAccess({
+ getAgent,
+ getEffectivePermissions,
+});
+
+router.use(requireApiKeyAuth);
+router.use(configMiddleware);
+router.use(checkRemoteAgentsFeature);
+
+/**
+ * @route POST /v1/responses
+ * @desc Create a model response following Open Responses specification
+ * @access Private (API key auth required)
+ *
+ * Request body:
+ * {
+ * "model": "agent_id", // Required: The agent ID to use
+ * "input": "..." | [...], // Required: String or array of input items
+ * "stream": true, // Optional: Whether to stream (default: false)
+ * "previous_response_id": "...", // Optional: Previous response for continuation
+ * "instructions": "...", // Optional: Additional instructions
+ * "tools": [...], // Optional: Additional tools
+ * "tool_choice": "auto", // Optional: Tool choice mode
+ * "max_output_tokens": 4096, // Optional: Max tokens
+ * "temperature": 0.7 // Optional: Temperature
+ * }
+ *
+ * Response (streaming):
+ * - SSE stream with semantic events:
+ * - response.in_progress
+ * - response.output_item.added
+ * - response.content_part.added
+ * - response.output_text.delta
+ * - response.output_text.done
+ * - response.function_call_arguments.delta
+ * - response.output_item.done
+ * - response.completed
+ * - [DONE]
+ *
+ * Response (non-streaming):
+ * {
+ * "id": "resp_xxx",
+ * "object": "response",
+ * "created_at": 1234567890,
+ * "status": "completed",
+ * "model": "agent_id",
+ * "output": [...], // Array of output items
+ * "usage": { ... }
+ * }
+ */
+router.post('/', checkAgentPermission, createResponse);
+
+/**
+ * @route GET /v1/responses/models
+ * @desc List available agents as models
+ * @access Private (API key auth required)
+ *
+ * Response:
+ * {
+ * "object": "list",
+ * "data": [
+ * {
+ * "id": "agent_id",
+ * "object": "model",
+ * "name": "Agent Name",
+ * "provider": "openai",
+ * ...
+ * }
+ * ]
+ * }
+ */
+router.get('/models', listModels);
+
+/**
+ * @route GET /v1/responses/:id
+ * @desc Retrieve a stored response by ID
+ * @access Private (API key auth required)
+ *
+ * Response:
+ * {
+ * "id": "resp_xxx",
+ * "object": "response",
+ * "created_at": 1234567890,
+ * "status": "completed",
+ * "model": "agent_id",
+ * "output": [...],
+ * "usage": { ... }
+ * }
+ */
+router.get('/:id', getResponse);
+
+module.exports = router;
diff --git a/api/server/routes/apiKeys.js b/api/server/routes/apiKeys.js
new file mode 100644
index 0000000000..29dcc326f5
--- /dev/null
+++ b/api/server/routes/apiKeys.js
@@ -0,0 +1,36 @@
+const express = require('express');
+const { generateCheckAccess, createApiKeyHandlers } = require('@librechat/api');
+const { PermissionTypes, Permissions } = require('librechat-data-provider');
+const {
+ getAgentApiKeyById,
+ createAgentApiKey,
+ deleteAgentApiKey,
+ listAgentApiKeys,
+} = require('~/models');
+const { requireJwtAuth } = require('~/server/middleware');
+const { getRoleByName } = require('~/models/Role');
+
+const router = express.Router();
+
+const handlers = createApiKeyHandlers({
+ createAgentApiKey,
+ listAgentApiKeys,
+ deleteAgentApiKey,
+ getAgentApiKeyById,
+});
+
+const checkRemoteAgentsUse = generateCheckAccess({
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ permissions: [Permissions.USE],
+ getRoleByName,
+});
+
+router.post('/', requireJwtAuth, checkRemoteAgentsUse, handlers.createApiKey);
+
+router.get('/', requireJwtAuth, checkRemoteAgentsUse, handlers.listApiKeys);
+
+router.get('/:id', requireJwtAuth, checkRemoteAgentsUse, handlers.getApiKey);
+
+router.delete('/:id', requireJwtAuth, checkRemoteAgentsUse, handlers.deleteApiKey);
+
+module.exports = router;
diff --git a/api/server/routes/index.js b/api/server/routes/index.js
index 785e74bb8f..6a48919db3 100644
--- a/api/server/routes/index.js
+++ b/api/server/routes/index.js
@@ -10,6 +10,7 @@ const presets = require('./presets');
const prompts = require('./prompts');
const balance = require('./balance');
const actions = require('./actions');
+const apiKeys = require('./apiKeys');
const banner = require('./banner');
const search = require('./search');
const models = require('./models');
@@ -31,6 +32,7 @@ module.exports = {
auth,
adminAuth,
keys,
+ apiKeys,
user,
tags,
roles,
diff --git a/api/server/routes/roles.js b/api/server/routes/roles.js
index abb53141bd..12e18c7624 100644
--- a/api/server/routes/roles.js
+++ b/api/server/routes/roles.js
@@ -6,9 +6,10 @@ const {
agentPermissionsSchema,
promptPermissionsSchema,
memoryPermissionsSchema,
+ mcpServersPermissionsSchema,
marketplacePermissionsSchema,
peoplePickerPermissionsSchema,
- mcpServersPermissionsSchema,
+ remoteAgentsPermissionsSchema,
} = require('librechat-data-provider');
const { checkAdmin, requireJwtAuth } = require('~/server/middleware');
const { updateRoleByName, getRoleByName } = require('~/models/Role');
@@ -51,6 +52,11 @@ const permissionConfigs = {
permissionType: PermissionTypes.MARKETPLACE,
errorMessage: 'Invalid marketplace permissions.',
},
+ 'remote-agents': {
+ schema: remoteAgentsPermissionsSchema,
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ errorMessage: 'Invalid remote agents permissions.',
+ },
};
/**
@@ -160,4 +166,10 @@ router.put('/:roleName/mcp-servers', checkAdmin, createPermissionUpdateHandler('
*/
router.put('/:roleName/marketplace', checkAdmin, createPermissionUpdateHandler('marketplace'));
+/**
+ * PUT /api/roles/:roleName/remote-agents
+ * Update remote agents (API) permissions for a specific role
+ */
+router.put('/:roleName/remote-agents', checkAdmin, createPermissionUpdateHandler('remote-agents'));
+
module.exports = router;
diff --git a/api/server/services/PermissionService.js b/api/server/services/PermissionService.js
index c35faf7c8d..a843f48f6f 100644
--- a/api/server/services/PermissionService.js
+++ b/api/server/services/PermissionService.js
@@ -141,7 +141,6 @@ const checkPermission = async ({ userId, role, resourceType, resourceId, require
validateResourceType(resourceType);
- // Get all principals for the user (user + groups + public)
const principals = await getUserPrincipals({ userId, role });
if (principals.length === 0) {
@@ -151,7 +150,6 @@ const checkPermission = async ({ userId, role, resourceType, resourceId, require
return await hasPermission(principals, resourceType, resourceId, requiredPermission);
} catch (error) {
logger.error(`[PermissionService.checkPermission] Error: ${error.message}`);
- // Re-throw validation errors
if (error.message.includes('requiredPermission must be')) {
throw error;
}
@@ -172,12 +170,12 @@ const getEffectivePermissions = async ({ userId, role, resourceType, resourceId
try {
validateResourceType(resourceType);
- // Get all principals for the user (user + groups + public)
const principals = await getUserPrincipals({ userId, role });
if (principals.length === 0) {
return 0;
}
+
return await getEffectivePermissionsACL(principals, resourceType, resourceId);
} catch (error) {
logger.error(`[PermissionService.getEffectivePermissions] Error: ${error.message}`);
diff --git a/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsx b/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsx
new file mode 100644
index 0000000000..f75b93526a
--- /dev/null
+++ b/client/src/components/Nav/SettingsTabs/Data/AgentApiKeys.tsx
@@ -0,0 +1,362 @@
+import React, { useState } from 'react';
+import {
+ useGetAgentApiKeysQuery,
+ useCreateAgentApiKeyMutation,
+ useDeleteAgentApiKeyMutation,
+} from 'librechat-data-provider/react-query';
+import { Permissions, PermissionTypes } from 'librechat-data-provider';
+import { Plus, Trash2, Copy, CopyCheck, Key, Eye, EyeOff, ShieldEllipsis } from 'lucide-react';
+import {
+ Button,
+ Input,
+ Label,
+ Spinner,
+ OGDialog,
+ OGDialogClose,
+ OGDialogTitle,
+ OGDialogHeader,
+ OGDialogContent,
+ OGDialogTrigger,
+ useToastContext,
+} from '@librechat/client';
+import type { PermissionConfig } from '~/components/ui';
+import { useUpdateRemoteAgentsPermissionsMutation } from '~/data-provider';
+import { useLocalize, useCopyToClipboard } from '~/hooks';
+import { AdminSettingsDialog } from '~/components/ui';
+
+function CreateKeyDialog({ onKeyCreated }: { onKeyCreated?: () => void }) {
+ const localize = useLocalize();
+ const { showToast } = useToastContext();
+ const [open, setOpen] = useState(false);
+ const [name, setName] = useState('');
+ const [newKey, setNewKey] = useState<string | null>(null);
+ const [showKey, setShowKey] = useState(false);
+ const [isCopying, setIsCopying] = useState(false);
+ const createMutation = useCreateAgentApiKeyMutation();
+ const copyKey = useCopyToClipboard({ text: newKey || '' });
+
+ const handleCreate = async () => {
+ if (!name.trim()) {
+ showToast({ message: localize('com_ui_api_key_name_required'), status: 'error' });
+ return;
+ }
+
+ try {
+ const result = await createMutation.mutateAsync({ name: name.trim() });
+ setNewKey(result.key);
+ showToast({ message: localize('com_ui_api_key_created'), status: 'success' });
+ onKeyCreated?.();
+ } catch {
+ showToast({ message: localize('com_ui_api_key_create_error'), status: 'error' });
+ }
+ };
+
+ const handleClose = () => {
+ setName('');
+ setNewKey(null);
+ setShowKey(false);
+ setOpen(false);
+ };
+
+ const handleCopy = () => {
+ if (isCopying) {
+ return;
+ }
+ copyKey(setIsCopying);
+ showToast({ message: localize('com_ui_api_key_copied'), status: 'success' });
+ };
+
+ return (
+ <OGDialog open={open} onOpenChange={setOpen}>
+ <OGDialogTrigger asChild>
+ <Button variant="outline" size="sm" className="gap-2">
+ <Plus className="h-4 w-4" />
+ {localize('com_ui_create_api_key')}
+ </Button>
+ </OGDialogTrigger>
+ <OGDialogContent className="max-w-md">
+ <OGDialogTitle>{localize('com_ui_create_api_key')}</OGDialogTitle>
+ <div className="space-y-4 py-4">
+ {!newKey ? (
+ <>
+ <div className="space-y-2">
+ <Label htmlFor="key-name">{localize('com_ui_api_key_name')}</Label>
+ <Input
+ id="key-name"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ placeholder={localize('com_ui_api_key_name_placeholder')}
+ />
+ </div>
+ <div className="flex justify-end gap-2">
+ <OGDialogClose asChild>
+ <Button variant="outline" onClick={handleClose}>
+ {localize('com_ui_cancel')}
+ </Button>
+ </OGDialogClose>
+ <Button onClick={handleCreate} disabled={createMutation.isLoading}>
+ {createMutation.isLoading ? (
+ <Spinner className="h-4 w-4" />
+ ) : (
+ localize('com_ui_create')
+ )}
+ </Button>
+ </div>
+ </>
+ ) : (
+ <>
+ <div className="rounded-lg border border-yellow-500/50 bg-yellow-50 p-4 dark:bg-yellow-900/20">
+ <p className="text-sm text-yellow-800 dark:text-yellow-200">
+ {localize('com_ui_api_key_warning')}
+ </p>
+ </div>
+ <div className="space-y-2">
+ <Label>{localize('com_ui_your_api_key')}</Label>
+ <div className="flex gap-2">
+ <Input
+ value={showKey ? newKey : '•'.repeat(newKey.length)}
+ readOnly
+ className="font-mono text-sm"
+ />
+ <Button
+ variant="outline"
+ size="icon"
+ onClick={() => setShowKey(!showKey)}
+ title={showKey ? localize('com_ui_hide') : localize('com_ui_show')}
+ >
+ {showKey ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+ </Button>
+ <Button
+ variant="outline"
+ size="icon"
+ onClick={handleCopy}
+ disabled={isCopying}
+ title={localize('com_ui_copy')}
+ >
+ {isCopying ? <CopyCheck className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
+ </Button>
+ </div>
+ </div>
+ <div className="flex justify-end">
+ <Button onClick={handleClose}>{localize('com_ui_done')}</Button>
+ </div>
+ </>
+ )}
+ </div>
+ </OGDialogContent>
+ </OGDialog>
+ );
+}
+
+function KeyItem({
+ id,
+ name,
+ keyPrefix,
+ createdAt,
+ lastUsedAt,
+}: {
+ id: string;
+ name: string;
+ keyPrefix: string;
+ createdAt: string;
+ lastUsedAt?: string;
+}) {
+ const localize = useLocalize();
+ const { showToast } = useToastContext();
+ const [confirmDelete, setConfirmDelete] = useState(false);
+ const deleteMutation = useDeleteAgentApiKeyMutation();
+
+ const handleDelete = async () => {
+ try {
+ await deleteMutation.mutateAsync(id);
+ showToast({ message: localize('com_ui_api_key_deleted'), status: 'success' });
+ } catch {
+ showToast({ message: localize('com_ui_api_key_delete_error'), status: 'error' });
+ }
+ setConfirmDelete(false);
+ };
+
+ const formatDate = (dateStr: string) => {
+ return new Date(dateStr).toLocaleDateString(undefined, {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ });
+ };
+
+ return (
+ <div className="flex items-center justify-between rounded-lg border border-border-light p-3">
+ <div className="flex items-center gap-3">
+ <Key className="h-5 w-5 text-text-secondary" />
+ <div>
+ <div className="font-medium">{name}</div>
+ <div className="text-sm text-text-secondary">
+ <span className="font-mono">{keyPrefix}...</span>
+ <span className="mx-2">•</span>
+ <span>
+ {localize('com_ui_created')} {formatDate(createdAt)}
+ </span>
+ {lastUsedAt && (
+ <>
+ <span className="mx-2">•</span>
+ <span>
+ {localize('com_ui_last_used')} {formatDate(lastUsedAt)}
+ </span>
+ </>
+ )}
+ </div>
+ </div>
+ </div>
+ <div>
+ {confirmDelete ? (
+ <div className="flex gap-2">
+ <Button variant="outline" size="sm" onClick={() => setConfirmDelete(false)}>
+ {localize('com_ui_cancel')}
+ </Button>
+ <Button
+ variant="destructive"
+ size="sm"
+ onClick={handleDelete}
+ disabled={deleteMutation.isLoading}
+ >
+ {deleteMutation.isLoading ? (
+ <Spinner className="h-4 w-4" />
+ ) : (
+ localize('com_ui_delete')
+ )}
+ </Button>
+ </div>
+ ) : (
+ <Button
+ variant="ghost"
+ size="icon"
+ onClick={() => setConfirmDelete(true)}
+ title={localize('com_ui_delete')}
+ >
+ <Trash2 className="h-4 w-4 text-text-secondary hover:text-red-500" />
+ </Button>
+ )}
+ </div>
+ </div>
+ );
+}
+
+function ApiKeysContent({ isOpen }: { isOpen: boolean }) {
+ const localize = useLocalize();
+ const { data, isLoading, error } = useGetAgentApiKeysQuery({ enabled: isOpen });
+
+ if (error) {
+ return <div className="text-sm text-red-500">{localize('com_ui_api_keys_load_error')}</div>;
+ }
+
+ return (
+ <div className="space-y-4">
+ <div className="flex items-center justify-end gap-2">
+ <RemoteAgentsAdminSettings />
+ <CreateKeyDialog />
+ </div>
+
+ <div className="max-h-[400px] space-y-2 overflow-y-auto">
+ {isLoading && (
+ <div className="flex items-center justify-center py-8">
+ <Spinner className="h-6 w-6" />
+ </div>
+ )}
+ {!isLoading &&
+ data?.keys &&
+ data.keys.length > 0 &&
+ data.keys.map((key) => (
+ <KeyItem
+ key={key.id}
+ id={key.id}
+ name={key.name}
+ keyPrefix={key.keyPrefix}
+ createdAt={key.createdAt}
+ lastUsedAt={key.lastUsedAt}
+ />
+ ))}
+ {!isLoading && (!data?.keys || data.keys.length === 0) && (
+ <div className="rounded-lg border-2 border-dashed border-border-light p-8 text-center">
+ <Key className="mx-auto h-8 w-8 text-text-secondary" />
+ <p className="mt-2 text-sm text-text-secondary">{localize('com_ui_no_api_keys')}</p>
+ </div>
+ )}
+ </div>
+ </div>
+ );
+}
+
+const remoteAgentsPermissions: PermissionConfig[] = [
+ { permission: Permissions.USE, labelKey: 'com_ui_remote_agents_allow_use' },
+ { permission: Permissions.CREATE, labelKey: 'com_ui_remote_agents_allow_create' },
+ { permission: Permissions.SHARE, labelKey: 'com_ui_remote_agents_allow_share' },
+ { permission: Permissions.SHARE_PUBLIC, labelKey: 'com_ui_remote_agents_allow_share_public' },
+];
+
+function RemoteAgentsAdminSettings() {
+ const localize = useLocalize();
+ const { showToast } = useToastContext();
+
+ const mutation = useUpdateRemoteAgentsPermissionsMutation({
+ onSuccess: () => {
+ showToast({ status: 'success', message: localize('com_ui_saved') });
+ },
+ onError: () => {
+ showToast({ status: 'error', message: localize('com_ui_error_save_admin_settings') });
+ },
+ });
+
+ const trigger = (
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-8 w-8"
+ aria-label={localize('com_ui_admin_settings')}
+ >
+ <ShieldEllipsis className="h-5 w-5" aria-hidden="true" />
+ </Button>
+ );
+
+ return (
+ <AdminSettingsDialog
+ permissionType={PermissionTypes.REMOTE_AGENTS}
+ sectionKey="com_ui_remote_agents"
+ permissions={remoteAgentsPermissions}
+ menuId="remote-agents-role-dropdown"
+ mutation={mutation}
+ trigger={trigger}
+ />
+ );
+}
+
+export function AgentApiKeys() {
+ const localize = useLocalize();
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <div className="flex items-center justify-between">
+ <Label id="api-keys-label">{localize('com_ui_agent_api_keys')}</Label>
+
+ <OGDialog open={isOpen} onOpenChange={setIsOpen}>
+ <OGDialogTrigger asChild>
+ <Button aria-labelledby="api-keys-label" variant="outline">
+ {localize('com_ui_manage')}
+ </Button>
+ </OGDialogTrigger>
+
+ <OGDialogContent
+ title={localize('com_ui_agent_api_keys')}
+ className="w-11/12 max-w-2xl bg-background text-text-primary shadow-2xl"
+ >
+ <OGDialogHeader>
+ <OGDialogTitle>{localize('com_ui_agent_api_keys')}</OGDialogTitle>
+ <p className="text-sm text-text-secondary">
+ {localize('com_ui_agent_api_keys_description')}
+ </p>
+ </OGDialogHeader>
+ <ApiKeysContent isOpen={isOpen} />
+ </OGDialogContent>
+ </OGDialog>
+ </div>
+ );
+}
diff --git a/client/src/components/Nav/SettingsTabs/Data/Data.tsx b/client/src/components/Nav/SettingsTabs/Data/Data.tsx
index 0bba5a152e..eb8cea98c2 100644
--- a/client/src/components/Nav/SettingsTabs/Data/Data.tsx
+++ b/client/src/components/Nav/SettingsTabs/Data/Data.tsx
@@ -1,15 +1,22 @@
import React, { useState, useRef } from 'react';
import { useOnClickOutside } from '@librechat/client';
+import { Permissions, PermissionTypes } from 'librechat-data-provider';
import ImportConversations from './ImportConversations';
-import { RevokeKeys } from './RevokeKeys';
+import { AgentApiKeys } from './AgentApiKeys';
import { DeleteCache } from './DeleteCache';
+import { RevokeKeys } from './RevokeKeys';
import { ClearChats } from './ClearChats';
import SharedLinks from './SharedLinks';
+import { useHasAccess } from '~/hooks';
function Data() {
const dataTabRef = useRef(null);
const [confirmClearConvos, setConfirmClearConvos] = useState(false);
useOnClickOutside(dataTabRef, () => confirmClearConvos && setConfirmClearConvos(false), []);
+ const hasAccessToApiKeys = useHasAccess({
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ permission: Permissions.USE,
+ });
return (
<div className="flex flex-col gap-3 p-1 text-sm text-text-primary">
@@ -19,6 +26,11 @@ function Data() {
<div className="pb-3">
<SharedLinks />
</div>
+ {hasAccessToApiKeys && (
+ <div className="pb-3">
+ <AgentApiKeys />
+ </div>
+ )}
<div className="pb-3">
<RevokeKeys />
</div>
diff --git a/client/src/components/SidePanel/Agents/AgentFooter.tsx b/client/src/components/SidePanel/Agents/AgentFooter.tsx
index 80a449bb2d..b2fa996596 100644
--- a/client/src/components/SidePanel/Agents/AgentFooter.tsx
+++ b/client/src/components/SidePanel/Agents/AgentFooter.tsx
@@ -1,3 +1,4 @@
+import { Globe } from 'lucide-react';
import { Spinner } from '@librechat/client';
import { useWatch, useFormContext } from 'react-hook-form';
import {
@@ -44,13 +45,20 @@ export default function AgentFooter({
permissionType: PermissionTypes.AGENTS,
permission: Permissions.SHARE,
});
+ const hasAccessToShareRemoteAgents = useHasAccess({
+ permissionType: PermissionTypes.REMOTE_AGENTS,
+ permission: Permissions.SHARE,
+ });
const { hasPermission, isLoading: permissionsLoading } = useResourcePermissions(
ResourceType.AGENT,
agent?._id || '',
);
+ const { hasPermission: hasRemoteAgentPermission, isLoading: remotePermissionsLoading } =
+ useResourcePermissions(ResourceType.REMOTE_AGENT, agent?._id || '');
const canShareThisAgent = hasPermission(PermissionBits.SHARE);
const canDeleteThisAgent = hasPermission(PermissionBits.DELETE);
+ const canShareRemoteAgent = hasRemoteAgentPermission(PermissionBits.SHARE);
const isSaving = createMutation.isLoading || updateMutation.isLoading || isAvatarUploading;
const renderSaveButton = () => {
if (isSaving) {
@@ -91,6 +99,25 @@ export default function AgentFooter({
resourceType={ResourceType.AGENT}
/>
)}
+ {(agent?.author === user?.id || user?.role === SystemRoles.ADMIN || canShareRemoteAgent) &&
+ hasAccessToShareRemoteAgents &&
+ !remotePermissionsLoading &&
+ agent?._id && (
+ <GenericGrantAccessDialog
+ resourceDbId={agent?._id}
+ resourceId={agent_id}
+ resourceName={agent?.name ?? ''}
+ resourceType={ResourceType.REMOTE_AGENT}
+ >
+ <button
+ type="button"
+ className="btn btn-neutral border-token-border-light h-9 px-3"
+ title={localize('com_ui_remote_access')}
+ >
+ <Globe className="h-4 w-4" aria-hidden="true" />
+ </button>
+ </GenericGrantAccessDialog>
+ )}
{agent && agent.author === user?.id && <DuplicateAgent agent_id={agent_id} />}
{/* Submit Button */}
<button
diff --git a/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx
index 3425f5a75c..8d882bffe8 100644
--- a/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx
+++ b/client/src/components/SidePanel/Agents/__tests__/AgentFooter.spec.tsx
@@ -174,7 +174,7 @@ jest.mock('~/components/Sharing', () => ({
resourceType: ResourceType;
}) => (
<div
- data-testid="grant-access-dialog"
+ data-testid={`grant-access-dialog-${resourceType}`}
data-resource-db-id={resourceDbId}
data-resource-id={resourceId}
data-resource-name={resourceName}
@@ -274,7 +274,7 @@ describe('AgentFooter', () => {
expect(screen.getByTestId('version-button')).toBeInTheDocument();
expect(screen.getByTestId('delete-button')).toBeInTheDocument();
expect(screen.queryByTestId('admin-settings')).not.toBeInTheDocument();
- expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();
+ expect(screen.getByTestId('grant-access-dialog-agent')).toBeInTheDocument();
expect(screen.getByTestId('duplicate-button')).toBeInTheDocument();
expect(screen.queryByTestId('spinner')).not.toBeInTheDocument();
});
@@ -338,7 +338,7 @@ describe('AgentFooter', () => {
expect(screen.getByText('Create')).toBeInTheDocument();
expect(screen.queryByTestId('version-button')).not.toBeInTheDocument();
expect(screen.queryByTestId('delete-button')).not.toBeInTheDocument();
- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();
+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();
expect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument();
});
@@ -346,7 +346,7 @@ describe('AgentFooter', () => {
mockUseAuthContext.mockReturnValue(createAuthContext(mockUsers.admin));
const { unmount } = render(<AgentFooter {...defaultProps} />);
expect(screen.getByTestId('admin-settings')).toBeInTheDocument();
- expect(screen.getByTestId('grant-access-dialog')).toBeInTheDocument();
+ expect(screen.getByTestId('grant-access-dialog-agent')).toBeInTheDocument();
// Clean up the first render
unmount();
@@ -363,7 +363,7 @@ describe('AgentFooter', () => {
return undefined;
});
render(<AgentFooter {...defaultProps} />);
- expect(screen.queryByTestId('grant-access-dialog')).toBeInTheDocument(); // Still shows because hasAccess is true
+ expect(screen.queryByTestId('grant-access-dialog-agent')).toBeInTheDocument(); // Still shows because hasAccess is true
expect(screen.queryByTestId('duplicate-agent')).not.toBeInTheDocument(); // Should not show for different author
});
@@ -392,7 +392,7 @@ describe('AgentFooter', () => {
permissionBits: 0,
});
render(<AgentFooter {...defaultProps} />);
- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();
+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();
});
test('hides action buttons when permissions are loading', () => {
@@ -419,7 +419,7 @@ describe('AgentFooter', () => {
});
render(<AgentFooter {...defaultProps} />);
expect(screen.queryByTestId('delete-button')).not.toBeInTheDocument();
- expect(screen.queryByTestId('grant-access-dialog')).not.toBeInTheDocument();
+ expect(screen.queryByTestId('grant-access-dialog-agent')).not.toBeInTheDocument();
// Duplicate button should still show as it doesn't depend on permissions loading
expect(screen.getByTestId('duplicate-button')).toBeInTheDocument();
});
diff --git a/client/src/data-provider/roles.ts b/client/src/data-provider/roles.ts
index 46edcd2dc9..356d9bd145 100644
--- a/client/src/data-provider/roles.ts
+++ b/client/src/data-provider/roles.ts
@@ -4,14 +4,15 @@ import {
dataService,
promptPermissionsSchema,
memoryPermissionsSchema,
+ mcpServersPermissionsSchema,
marketplacePermissionsSchema,
peoplePickerPermissionsSchema,
- mcpServersPermissionsSchema,
+ remoteAgentsPermissionsSchema,
} from 'librechat-data-provider';
import type {
- UseQueryOptions,
- UseMutationResult,
QueryObserverResult,
+ UseMutationResult,
+ UseQueryOptions,
} from '@tanstack/react-query';
import type * as t from 'librechat-data-provider';
@@ -243,3 +244,39 @@ export const useUpdateMarketplacePermissionsMutation = (
},
);
};
+
+export const useUpdateRemoteAgentsPermissionsMutation = (
+ options?: t.UpdateRemoteAgentsPermOptions,
+): UseMutationResult<
+ t.UpdatePermResponse,
+ t.TError | undefined,
+ t.UpdateRemoteAgentsPermVars,
+ unknown
+> => {
+ const queryClient = useQueryClient();
+ const { onMutate, onSuccess, onError } = options ?? {};
+ return useMutation(
+ (variables) => {
+ remoteAgentsPermissionsSchema.partial().parse(variables.updates);
+ return dataService.updateRemoteAgentsPermissions(variables);
+ },
+ {
+ onSuccess: (data, variables, context) => {
+ queryClient.invalidateQueries([QueryKeys.roles, variables.roleName]);
+ if (onSuccess) {
+ onSuccess(data, variables, context);
+ }
+ },
+ onError: (...args) => {
+ const error = args[0];
+ if (error != null) {
+ console.error('Failed to update remote agents permissions:', error);
+ }
+ if (onError) {
+ onError(...args);
+ }
+ },
+ onMutate,
+ },
+ );
+};
diff --git a/client/src/hooks/Sharing/useCanSharePublic.ts b/client/src/hooks/Sharing/useCanSharePublic.ts
index 699ccc9e73..54355dd9a8 100644
--- a/client/src/hooks/Sharing/useCanSharePublic.ts
+++ b/client/src/hooks/Sharing/useCanSharePublic.ts
@@ -1,10 +1,11 @@
import { ResourceType, PermissionTypes, Permissions } from 'librechat-data-provider';
import { useHasAccess } from '~/hooks';
-const resourceToPermissionMap: Record<ResourceType, PermissionTypes> = {
+const resourceToPermissionMap: Partial<Record<ResourceType, PermissionTypes>> = {
[ResourceType.AGENT]: PermissionTypes.AGENTS,
[ResourceType.PROMPTGROUP]: PermissionTypes.PROMPTS,
[ResourceType.MCPSERVER]: PermissionTypes.MCP_SERVERS,
+ [ResourceType.REMOTE_AGENT]: PermissionTypes.REMOTE_AGENTS,
};
/**
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index dfb866d690..47ccc04303 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -708,6 +708,21 @@
"com_ui_analyzing": "Analyzing",
"com_ui_analyzing_finished": "Finished analyzing",
"com_ui_api_key": "API Key",
+ "com_ui_api_key_copied": "API key copied to clipboard",
+ "com_ui_api_key_create_error": "Failed to create API key",
+ "com_ui_api_key_created": "API key created successfully",
+ "com_ui_api_key_delete_error": "Failed to delete API key",
+ "com_ui_api_key_deleted": "API key deleted successfully",
+ "com_ui_api_key_name": "Key Name",
+ "com_ui_api_key_name_placeholder": "My API Key",
+ "com_ui_api_key_name_required": "API key name is required",
+ "com_ui_api_key_warning": "Make sure to copy your API key now. You won't be able to see it again!",
+ "com_ui_api_keys_load_error": "Failed to load API keys",
+ "com_ui_agent_api_keys": "Agent API Keys",
+ "com_ui_agent_api_keys_description": "Create API keys to access agents remotely via the API",
+ "com_ui_create_api_key": "Create API Key",
+ "com_ui_no_api_keys": "No API keys yet. Create one to get started.",
+ "com_ui_your_api_key": "Your API Key",
"com_ui_archive": "Archive",
"com_ui_archive_delete_error": "Failed to delete archived conversation",
"com_ui_archive_error": "Failed to archive conversation",
@@ -838,6 +853,7 @@
"com_ui_copy_to_clipboard": "Copy to clipboard",
"com_ui_copy_url_to_clipboard": "Copy URL to clipboard",
"com_ui_create": "Create",
+ "com_ui_created": "Created",
"com_ui_create_assistant": "Create Assistant",
"com_ui_create_link": "Create link",
"com_ui_create_memory": "Create Memory",
@@ -1023,6 +1039,7 @@
"com_ui_hide_image_details": "Hide Image Details",
"com_ui_hide_password": "Hide password",
"com_ui_hide_qr": "Hide QR Code",
+ "com_ui_hide": "Hide",
"com_ui_high": "High",
"com_ui_host": "Host",
"com_ui_icon": "Icon",
@@ -1044,6 +1061,7 @@
"com_ui_instructions": "Instructions",
"com_ui_key": "Key",
"com_ui_key_required": "API key is required",
+ "com_ui_last_used": "Last used",
"com_ui_late_night": "Happy late night",
"com_ui_latest_footer": "Every AI for Everyone.",
"com_ui_latest_production_version": "Latest production version",
@@ -1089,6 +1107,13 @@
"com_ui_mcp_server_role_viewer": "MCP Server Viewer",
"com_ui_mcp_server_role_viewer_desc": "Can view and use MCP servers",
"com_ui_mcp_server_updated": "MCP server updated successfully",
+ "com_ui_remote_access": "Remote Access",
+ "com_ui_remote_agent_role_owner": "API Owner",
+ "com_ui_remote_agent_role_owner_desc": "Full API access and can grant remote access to others",
+ "com_ui_remote_agent_role_editor": "Editor",
+ "com_ui_remote_agent_role_editor_desc": "Can view and modify the agent via API",
+ "com_ui_remote_agent_role_viewer": "API Viewer",
+ "com_ui_remote_agent_role_viewer_desc": "Can query the agent via API",
"com_ui_mcp_server_url_placeholder": "https://mcp.example.com",
"com_ui_mcp_servers": "MCP Servers",
"com_ui_mcp_servers_allow_create": "Allow users to create MCP servers",
@@ -1238,6 +1263,11 @@
"com_ui_regenerating": "Regenerating...",
"com_ui_region": "Region",
"com_ui_reinitialize": "Reinitialize",
+ "com_ui_remote_agents": "Remote Agents (API)",
+ "com_ui_remote_agents_allow_use": "Allow users to create API keys and query agents remotely",
+ "com_ui_remote_agents_allow_create": "Allow users to create agents via API",
+ "com_ui_remote_agents_allow_share": "Allow users to grant API access to agents to others",
+ "com_ui_remote_agents_allow_share_public": "Allow users to grant API access to agents to all users",
"com_ui_remove_agent_from_chain": "Remove {{0}} from chain",
"com_ui_remove_user": "Remove {{0}}",
"com_ui_rename": "Rename",
@@ -1327,6 +1357,7 @@
"com_ui_shared_link_not_found": "Shared link not found",
"com_ui_shared_prompts": "Shared Prompts",
"com_ui_shop": "Shopping",
+ "com_ui_show": "Show",
"com_ui_show_all": "Show All",
"com_ui_show_code": "Show Code",
"com_ui_show_image_details": "Show Image Details",
diff --git a/client/src/utils/resources.ts b/client/src/utils/resources.ts
index f7c3586dfb..9b68cef3f6 100644
--- a/client/src/utils/resources.ts
+++ b/client/src/utils/resources.ts
@@ -47,6 +47,19 @@ export const RESOURCE_CONFIGS: Record<ResourceType, ResourceConfig> = {
`Manage permissions for ${name && name !== '' ? `"${name}"` : 'MCP server'}`,
getCopyUrlMessage: () => 'MCP Server URL copied',
},
+ [ResourceType.REMOTE_AGENT]: {
+ resourceType: ResourceType.REMOTE_AGENT,
+ defaultViewerRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,
+ defaultEditorRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,
+ defaultOwnerRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ getResourceUrl: () => `${window.location.origin}/api/v1/responses`,
+ getResourceName: (name?: string) => (name && name !== '' ? `"${name}"` : 'remote agent'),
+ getShareMessage: (name?: string) =>
+ name && name !== '' ? `"${name}" (API Access)` : 'remote agent access',
+ getManageMessage: (name?: string) =>
+ `Manage API access for ${name && name !== '' ? `"${name}"` : 'agent'}`,
+ getCopyUrlMessage: () => 'API endpoint copied',
+ },
};
export const getResourceConfig = (resourceType: ResourceType): ResourceConfig | undefined => {
diff --git a/client/src/utils/roles.ts b/client/src/utils/roles.ts
index 8bc38b7d52..1e8cb3d3b2 100644
--- a/client/src/utils/roles.ts
+++ b/client/src/utils/roles.ts
@@ -48,6 +48,18 @@ export const ROLE_LOCALIZATIONS = {
name: 'com_ui_mcp_server_role_owner' as const,
description: 'com_ui_mcp_server_role_owner_desc' as const,
} as const,
+ remoteAgent_viewer: {
+ name: 'com_ui_remote_agent_role_viewer' as const,
+ description: 'com_ui_remote_agent_role_viewer_desc' as const,
+ } as const,
+ remoteAgent_editor: {
+ name: 'com_ui_remote_agent_role_editor' as const,
+ description: 'com_ui_remote_agent_role_editor_desc' as const,
+ } as const,
+ remoteAgent_owner: {
+ name: 'com_ui_remote_agent_role_owner' as const,
+ description: 'com_ui_remote_agent_role_owner_desc' as const,
+ } as const,
};
/**
diff --git a/config/delete-user.js b/config/delete-user.js
index 2d4dea0b37..5ad85577a4 100644
--- a/config/delete-user.js
+++ b/config/delete-user.js
@@ -23,6 +23,7 @@ const {
PluginAuth,
MemoryEntry,
PromptGroup,
+ AgentApiKey,
Transaction,
Conversation,
ConversationTag,
@@ -79,6 +80,7 @@ async function gracefulExit(code = 0) {
const tasks = [
Action.deleteMany({ user: uid }),
Agent.deleteMany({ author: uid }),
+ AgentApiKey.deleteMany({ user: uid }),
Assistant.deleteMany({ user: uid }),
Balance.deleteMany({ user: uid }),
ConversationTag.deleteMany({ user: uid }),
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts
index 77e7f9e2cc..6539db3db1 100644
--- a/packages/api/src/agents/index.ts
+++ b/packages/api/src/agents/index.ts
@@ -6,6 +6,8 @@ export * from './initialize';
export * from './legacy';
export * from './memory';
export * from './migration';
+export * from './openai';
export * from './resources';
+export * from './responses';
export * from './run';
export * from './validation';
diff --git a/packages/api/src/agents/openai/handlers.ts b/packages/api/src/agents/openai/handlers.ts
new file mode 100644
index 0000000000..f4e4dff3d2
--- /dev/null
+++ b/packages/api/src/agents/openai/handlers.ts
@@ -0,0 +1,454 @@
+/**
+ * OpenAI-compatible event handlers for agent streaming.
+ *
+ * These handlers convert LibreChat's internal graph events into OpenAI-compatible
+ * streaming format (SSE with chat.completion.chunk objects).
+ */
+import type { Response as ServerResponse } from 'express';
+import type {
+ ChatCompletionChunkChoice,
+ OpenAIResponseContext,
+ ChatCompletionChunk,
+ CompletionUsage,
+ ToolCall,
+} from './types';
+
+/**
+ * Create a chat completion chunk in OpenAI format
+ */
+export function createChunk(
+ context: OpenAIResponseContext,
+ delta: ChatCompletionChunkChoice['delta'],
+ finishReason: ChatCompletionChunkChoice['finish_reason'] = null,
+ usage?: CompletionUsage,
+): ChatCompletionChunk {
+ return {
+ id: context.requestId,
+ object: 'chat.completion.chunk',
+ created: context.created,
+ model: context.model,
+ choices: [
+ {
+ index: 0,
+ delta,
+ finish_reason: finishReason,
+ },
+ ],
+ ...(usage && { usage }),
+ };
+}
+
+/**
+ * Write an SSE event to the response
+ */
+export function writeSSE(res: ServerResponse, data: ChatCompletionChunk | string): void {
+ if (typeof data === 'string') {
+ res.write(`data: ${data}\n\n`);
+ } else {
+ res.write(`data: ${JSON.stringify(data)}\n\n`);
+ }
+}
+
+/**
+ * Lightweight tracker for streaming responses.
+ * Only tracks what's needed for finish_reason and usage - doesn't store content.
+ */
+export interface OpenAIStreamTracker {
+ /** Whether any text content was emitted */
+ hasText: boolean;
+ /** Whether any reasoning content was emitted */
+ hasReasoning: boolean;
+ /** Accumulated tool calls by index */
+ toolCalls: Map<number, ToolCall>;
+ /** Accumulated usage metadata */
+ usage: {
+ promptTokens: number;
+ completionTokens: number;
+ reasoningTokens: number;
+ };
+ /** Mark that text was emitted */
+ addText: () => void;
+ /** Mark that reasoning was emitted */
+ addReasoning: () => void;
+}
+
+/**
+ * Create a lightweight stream tracker (doesn't store content)
+ */
+export function createOpenAIStreamTracker(): OpenAIStreamTracker {
+ const tracker: OpenAIStreamTracker = {
+ hasText: false,
+ hasReasoning: false,
+ toolCalls: new Map(),
+ usage: {
+ promptTokens: 0,
+ completionTokens: 0,
+ reasoningTokens: 0,
+ },
+ addText: () => {
+ tracker.hasText = true;
+ },
+ addReasoning: () => {
+ tracker.hasReasoning = true;
+ },
+ };
+ return tracker;
+}
+
+/**
+ * Content aggregator for non-streaming responses.
+ * Accumulates full text content, reasoning, and tool calls.
+ * Uses arrays for O(n) text accumulation instead of O(n²) string concatenation.
+ */
+export interface OpenAIContentAggregator {
+ /** Accumulated text chunks */
+ textChunks: string[];
+ /** Accumulated reasoning/thinking chunks */
+ reasoningChunks: string[];
+ /** Accumulated tool calls by index */
+ toolCalls: Map<number, ToolCall>;
+ /** Accumulated usage metadata */
+ usage: {
+ promptTokens: number;
+ completionTokens: number;
+ reasoningTokens: number;
+ };
+ /** Get accumulated text (joins chunks) */
+ getText: () => string;
+ /** Get accumulated reasoning (joins chunks) */
+ getReasoning: () => string;
+ /** Add text chunk */
+ addText: (text: string) => void;
+ /** Add reasoning chunk */
+ addReasoning: (text: string) => void;
+}
+
+/**
+ * Create a content aggregator for non-streaming responses
+ */
+export function createOpenAIContentAggregator(): OpenAIContentAggregator {
+ const textChunks: string[] = [];
+ const reasoningChunks: string[] = [];
+
+ return {
+ textChunks,
+ reasoningChunks,
+ toolCalls: new Map(),
+ usage: {
+ promptTokens: 0,
+ completionTokens: 0,
+ reasoningTokens: 0,
+ },
+ getText: () => textChunks.join(''),
+ getReasoning: () => reasoningChunks.join(''),
+ addText: (text: string) => textChunks.push(text),
+ addReasoning: (text: string) => reasoningChunks.push(text),
+ };
+}
+
+/**
+ * Handler configuration for OpenAI streaming
+ */
+export interface OpenAIStreamHandlerConfig {
+ res: ServerResponse;
+ context: OpenAIResponseContext;
+ tracker: OpenAIStreamTracker;
+}
+
+/**
+ * Graph event types from @librechat/agents
+ */
+export const GraphEvents = {
+ CHAT_MODEL_END: 'on_chat_model_end',
+ TOOL_END: 'on_tool_end',
+ CHAT_MODEL_STREAM: 'on_chat_model_stream',
+ ON_RUN_STEP: 'on_run_step',
+ ON_RUN_STEP_DELTA: 'on_run_step_delta',
+ ON_RUN_STEP_COMPLETED: 'on_run_step_completed',
+ ON_MESSAGE_DELTA: 'on_message_delta',
+ ON_REASONING_DELTA: 'on_reasoning_delta',
+} as const;
+
+/**
+ * Step types from librechat-data-provider
+ */
+export const StepTypes = {
+ MESSAGE_CREATION: 'message_creation',
+ TOOL_CALLS: 'tool_calls',
+} as const;
+
+/**
+ * Event data interfaces
+ */
+export interface MessageDeltaData {
+ id?: string;
+ content?: Array<{ type: string; text?: string }>;
+}
+
+export interface RunStepDeltaData {
+ id?: string;
+ delta?: {
+ type?: string;
+ tool_calls?: Array<{
+ index?: number;
+ id?: string;
+ type?: string;
+ function?: {
+ name?: string;
+ arguments?: string;
+ };
+ }>;
+ };
+}
+
+export interface ToolEndData {
+ output?: {
+ name?: string;
+ tool_call_id?: string;
+ content?: string;
+ };
+}
+
+export interface ModelEndData {
+ output?: {
+ usage_metadata?: {
+ input_tokens?: number;
+ output_tokens?: number;
+ model?: string;
+ };
+ };
+}
+
+/**
+ * Event handler interface
+ */
+export interface EventHandler {
+ handle(
+ event: string,
+ data: unknown,
+ metadata?: Record<string, unknown>,
+ graph?: unknown,
+ ): void | Promise<void>;
+}
+
+/**
+ * Handler for message delta events - streams text content
+ */
+export class OpenAIMessageDeltaHandler implements EventHandler {
+ constructor(private config: OpenAIStreamHandlerConfig) {}
+
+ handle(_event: string, data: MessageDeltaData): void {
+ const content = data?.content;
+ if (!content || !Array.isArray(content)) {
+ return;
+ }
+
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ this.config.tracker.addText();
+ const chunk = createChunk(this.config.context, { content: part.text });
+ writeSSE(this.config.res, chunk);
+ }
+ }
+ }
+}
+
+/**
+ * Handler for run step delta events - streams tool calls
+ */
+export class OpenAIRunStepDeltaHandler implements EventHandler {
+ constructor(private config: OpenAIStreamHandlerConfig) {}
+
+ handle(_event: string, data: RunStepDeltaData): void {
+ const delta = data?.delta;
+ if (!delta || delta.type !== StepTypes.TOOL_CALLS) {
+ return;
+ }
+
+ const toolCalls = delta.tool_calls;
+ if (!toolCalls || !Array.isArray(toolCalls)) {
+ return;
+ }
+
+ for (const tc of toolCalls) {
+ if (tc.index === undefined) {
+ continue;
+ }
+
+ // Initialize tool call in tracker if needed
+ let trackedTc = this.config.tracker.toolCalls.get(tc.index);
+ if (!trackedTc && tc.id) {
+ trackedTc = {
+ id: tc.id,
+ type: 'function',
+ function: {
+ name: '',
+ arguments: '',
+ },
+ };
+ this.config.tracker.toolCalls.set(tc.index, trackedTc);
+ }
+
+ // Build the streaming delta
+ const streamDelta: ChatCompletionChunkChoice['delta'] = {
+ tool_calls: [
+ {
+ index: tc.index,
+ ...(tc.id && { id: tc.id }),
+ ...(tc.type && { type: tc.type as 'function' }),
+ ...(tc.function && {
+ function: {
+ ...(tc.function.name && { name: tc.function.name }),
+ ...(tc.function.arguments && { arguments: tc.function.arguments }),
+ },
+ }),
+ },
+ ],
+ };
+
+ // Update tracked tool call
+ if (trackedTc) {
+ if (tc.function?.name) {
+ trackedTc.function.name += tc.function.name;
+ }
+ if (tc.function?.arguments) {
+ trackedTc.function.arguments += tc.function.arguments;
+ }
+ }
+
+ const chunk = createChunk(this.config.context, streamDelta);
+ writeSSE(this.config.res, chunk);
+ }
+ }
+}
+
+/**
+ * Handler for run step events - sends initial tool call info
+ */
+export class OpenAIRunStepHandler implements EventHandler {
+ constructor(private config: OpenAIStreamHandlerConfig) {}
+
+ handle(_event: string, data: { stepDetails?: { type?: string } }): void {
+ // Run step events are primarily for LibreChat UI, we use deltas for streaming
+ // This handler is a no-op for OpenAI format
+ if (data?.stepDetails?.type === StepTypes.TOOL_CALLS) {
+ // Tool calls will be streamed via delta events
+ }
+ }
+}
+
+/**
+ * Handler for model end events - captures usage
+ */
+export class OpenAIModelEndHandler implements EventHandler {
+ constructor(private config: OpenAIStreamHandlerConfig) {}
+
+ handle(_event: string, data: ModelEndData): void {
+ const usage = data?.output?.usage_metadata;
+ if (!usage) {
+ return;
+ }
+
+ this.config.tracker.usage.promptTokens += usage.input_tokens ?? 0;
+ this.config.tracker.usage.completionTokens += usage.output_tokens ?? 0;
+ }
+}
+
+/**
+ * Handler for chat model stream events
+ */
+export class OpenAIChatModelStreamHandler implements EventHandler {
+ handle(): void {
+ // Handled by message delta handler
+ }
+}
+
+/**
+ * Handler for tool end events
+ */
+export class OpenAIToolEndHandler implements EventHandler {
+ handle(): void {
+ // Tool results don't need to be streamed in OpenAI format
+ // They're used internally by the agent
+ }
+}
+
+/**
+ * Handler for reasoning delta events.
+ * Streams reasoning/thinking content using the `delta.reasoning` field (OpenRouter convention).
+ */
+export class OpenAIReasoningDeltaHandler implements EventHandler {
+ constructor(private config: OpenAIStreamHandlerConfig) {}
+
+ handle(_event: string, data: MessageDeltaData): void {
+ const content = data?.content;
+ if (!content || !Array.isArray(content)) {
+ return;
+ }
+
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ // Mark that reasoning was emitted
+ this.config.tracker.addReasoning();
+
+ // Stream as delta.reasoning (OpenRouter convention)
+ const chunk = createChunk(this.config.context, { reasoning: part.text });
+ writeSSE(this.config.res, chunk);
+ }
+ }
+ }
+}
+
+/**
+ * Create all handlers for OpenAI streaming format
+ */
+export function createOpenAIHandlers(
+ config: OpenAIStreamHandlerConfig,
+): Record<string, EventHandler> {
+ return {
+ [GraphEvents.ON_MESSAGE_DELTA]: new OpenAIMessageDeltaHandler(config),
+ [GraphEvents.ON_RUN_STEP_DELTA]: new OpenAIRunStepDeltaHandler(config),
+ [GraphEvents.ON_RUN_STEP]: new OpenAIRunStepHandler(config),
+ [GraphEvents.ON_RUN_STEP_COMPLETED]: new OpenAIRunStepHandler(config),
+ [GraphEvents.CHAT_MODEL_END]: new OpenAIModelEndHandler(config),
+ [GraphEvents.CHAT_MODEL_STREAM]: new OpenAIChatModelStreamHandler(),
+ [GraphEvents.TOOL_END]: new OpenAIToolEndHandler(),
+ [GraphEvents.ON_REASONING_DELTA]: new OpenAIReasoningDeltaHandler(config),
+ };
+}
+
+/**
+ * Send the final chunk with finish_reason and optional usage
+ */
+export function sendFinalChunk(
+ config: OpenAIStreamHandlerConfig,
+ finishReason: ChatCompletionChunkChoice['finish_reason'] = 'stop',
+): void {
+ const { res, context, tracker } = config;
+
+ // Determine finish reason based on content
+ let reason = finishReason;
+ if (tracker.toolCalls.size > 0 && !tracker.hasText) {
+ reason = 'tool_calls';
+ }
+
+ // Build usage object with reasoning token details (OpenRouter/OpenAI convention)
+ const usage: CompletionUsage = {
+ prompt_tokens: tracker.usage.promptTokens,
+ completion_tokens: tracker.usage.completionTokens,
+ total_tokens: tracker.usage.promptTokens + tracker.usage.completionTokens,
+ };
+
+ // Add reasoning token breakdown if there are reasoning tokens
+ if (tracker.usage.reasoningTokens > 0) {
+ usage.completion_tokens_details = {
+ reasoning_tokens: tracker.usage.reasoningTokens,
+ };
+ }
+
+ const finalChunk = createChunk(context, {}, reason, usage);
+ writeSSE(res, finalChunk);
+
+ // Send [DONE] marker
+ writeSSE(res, '[DONE]');
+}
diff --git a/packages/api/src/agents/openai/index.ts b/packages/api/src/agents/openai/index.ts
new file mode 100644
index 0000000000..3a0a016108
--- /dev/null
+++ b/packages/api/src/agents/openai/index.ts
@@ -0,0 +1,52 @@
+/**
+ * OpenAI-compatible API for LibreChat agents.
+ *
+ * This module provides an OpenAI v1/chat/completions compatible interface
+ * for interacting with LibreChat agents remotely via API.
+ *
+ * @example
+ * ```typescript
+ * import { createAgentChatCompletion, listAgentModels } from '@librechat/api';
+ *
+ * // POST /v1/chat/completions
+ * app.post('/v1/chat/completions', async (req, res) => {
+ * await createAgentChatCompletion(req, res, dependencies);
+ * });
+ *
+ * // GET /v1/models
+ * app.get('/v1/models', async (req, res) => {
+ * await listAgentModels(req, res, { getAgents });
+ * });
+ * ```
+ *
+ * Request format:
+ * ```json
+ * {
+ * "model": "agent_id_here",
+ * "messages": [
+ * {"role": "user", "content": "Hello!"}
+ * ],
+ * "stream": true
+ * }
+ * ```
+ *
+ * The "model" parameter should be the agent ID you want to invoke.
+ * Use the /v1/models endpoint to list available agents.
+ */
+
+export * from './types';
+export * from './handlers';
+export {
+ createAgentChatCompletion,
+ listAgentModels,
+ convertMessages,
+ validateRequest,
+ isChatCompletionValidationFailure,
+ createErrorResponse,
+ sendErrorResponse,
+ buildNonStreamingResponse,
+ type ChatCompletionDependencies,
+ type ChatCompletionValidationResult,
+ type ChatCompletionValidationSuccess,
+ type ChatCompletionValidationFailure,
+} from './service';
diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.ts
new file mode 100644
index 0000000000..3213e0123f
--- /dev/null
+++ b/packages/api/src/agents/openai/service.ts
@@ -0,0 +1,554 @@
+/**
+ * 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 type { Response as ServerResponse, Request } from 'express';
+import type {
+ ChatCompletionResponse,
+ OpenAIResponseContext,
+ ChatCompletionRequest,
+ OpenAIErrorResponse,
+ CompletionUsage,
+ ChatMessage,
+ ToolCall,
+} from './types';
+import type { OpenAIStreamHandlerConfig, EventHandler } from './handlers';
+import {
+ createOpenAIContentAggregator,
+ createOpenAIStreamTracker,
+ createOpenAIHandlers,
+ sendFinalChunk,
+ createChunk,
+ writeSSE,
+} from './handlers';
+
+/**
+ * Dependencies for the chat completion service
+ */
+export interface ChatCompletionDependencies {
+ /** 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 */
+ appConfig?: AppConfig;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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: unknown[];
+ toolContextMap: Record<string, unknown>;
+ maxContextTokens: number;
+ userMCPAuthMap?: Record<string, Record<string, string>>;
+ [key: string]: unknown;
+}
+
+/**
+ * Initialize agent params
+ */
+interface InitializeAgentParams {
+ req: Request;
+ res: ServerResponse;
+ agent: Agent;
+ conversationId?: string | null;
+ parentMessageId?: string | null;
+ requestFiles?: unknown[];
+ loadTools?: LoadToolsFn;
+ endpointOption?: Record<string, unknown>;
+ allowedProviders: Set<string>;
+ isInitialAgent?: 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;
+}) => Promise<{
+ tools: unknown[];
+ toolContextMap: Record<string, unknown>;
+ userMCPAuthMap?: Record<string, Record<string, string>>;
+} | null>;
+
+/**
+ * Create run function type
+ */
+type CreateRunFn = (params: {
+ agents: unknown[];
+ messages: unknown[];
+ runId: string;
+ signal: AbortSignal;
+ customHandlers: Record<string, EventHandler>;
+ requestBody: Record<string, unknown>;
+ user: Record<string, unknown>;
+ 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>;
+ [key: string]: unknown;
+}
+
+/**
+ * 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`,
+ };
+ }
+ }
+
+ 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,
+): ChatCompletionResponse {
+ const toolCallsArray = Array.from(toolCalls.values());
+ const finishReason = toolCallsArray.length > 0 && !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;
+
+ // 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();
+ 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>();
+
+ // Initialize the agent first to check for disableStreaming
+ const initializedAgent = await deps.initializeAgent({
+ req,
+ res,
+ agent,
+ conversationId,
+ parentMessageId: request.parent_message_id,
+ loadTools: deps.loadAgentTools,
+ endpointOption: {
+ endpoint: agent.provider,
+ model_parameters: agent.model_parameters ?? {},
+ },
+ allowedProviders,
+ isInitialAgent: true,
+ });
+
+ // 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: OpenAIStreamHandlerConfig | null =
+ isStreaming && tracker
+ ? {
+ res,
+ context,
+ tracker,
+ }
+ : null;
+
+ // Create event handlers
+ const eventHandlers = isStreaming && handlerConfig ? createOpenAIHandlers(handlerConfig) : {};
+
+ // Convert messages to internal format
+ const messages = convertMessages(request.messages);
+
+ // Create and run the agent
+ if (deps.createRun) {
+ const userId = (req as unknown as { user?: { id?: string } }).user?.id ?? 'api-user';
+
+ const run = await deps.createRun({
+ agents: [initializedAgent],
+ messages,
+ runId: requestId,
+ signal: abortController.signal,
+ customHandlers: eventHandlers,
+ requestBody: {
+ messageId: requestId,
+ conversationId,
+ },
+ user: { id: userId },
+ });
+
+ if (run) {
+ await run.processStream(
+ { messages },
+ {
+ runName: 'AgentRun',
+ configurable: {
+ thread_id: conversationId,
+ user_id: userId,
+ },
+ signal: abortController.signal,
+ streamMode: 'values',
+ version: 'v2',
+ },
+ {},
+ );
+ }
+ }
+
+ // Finalize response
+ if (isStreaming && handlerConfig) {
+ sendFinalChunk(handlerConfig);
+ res.end();
+ } else if (aggregator) {
+ // 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,
+ );
+ res.json(response);
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : 'An error occurred';
+
+ // 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 {
+ sendErrorResponse(res, 500, errorMessage, 'server_error');
+ }
+ }
+}
+
+/**
+ * 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');
+ }
+}
diff --git a/packages/api/src/agents/openai/types.ts b/packages/api/src/agents/openai/types.ts
new file mode 100644
index 0000000000..a33d01d085
--- /dev/null
+++ b/packages/api/src/agents/openai/types.ts
@@ -0,0 +1,194 @@
+/**
+ * OpenAI-compatible types for the agent chat completions API.
+ * These types follow the OpenAI API spec for /v1/chat/completions.
+ *
+ * Note: This API uses agent_id as the "model" parameter per OpenAI spec.
+ * In the future, this will be extended to support the Responses API.
+ */
+
+/**
+ * Content part types for OpenAI format
+ */
+export interface OpenAITextContentPart {
+ type: 'text';
+ text: string;
+}
+
+export interface OpenAIImageContentPart {
+ type: 'image_url';
+ image_url: {
+ url: string;
+ detail?: 'auto' | 'low' | 'high';
+ };
+}
+
+export type OpenAIContentPart = OpenAITextContentPart | OpenAIImageContentPart;
+
+/**
+ * Tool call in OpenAI format
+ */
+export interface ToolCall {
+ id: string;
+ type: 'function';
+ function: {
+ name: string;
+ arguments: string;
+ };
+}
+
+/**
+ * OpenAI chat message format
+ */
+export interface ChatMessage {
+ role: 'system' | 'user' | 'assistant' | 'tool';
+ content: string | OpenAIContentPart[] | null;
+ name?: string;
+ tool_calls?: ToolCall[];
+ tool_call_id?: string;
+}
+
+/**
+ * OpenAI chat completion request
+ */
+export interface ChatCompletionRequest {
+ /** Agent ID to invoke (maps to model in OpenAI spec) */
+ model: string;
+ /** Conversation messages */
+ messages: ChatMessage[];
+ /** Whether to stream the response */
+ stream?: boolean;
+ /** Maximum tokens to generate */
+ max_tokens?: number;
+ /** Temperature for sampling */
+ temperature?: number;
+ /** Top-p sampling */
+ top_p?: number;
+ /** Frequency penalty */
+ frequency_penalty?: number;
+ /** Presence penalty */
+ presence_penalty?: number;
+ /** Stop sequences */
+ stop?: string | string[];
+ /** User identifier */
+ user?: string;
+ /** Conversation ID (LibreChat extension) */
+ conversation_id?: string;
+ /** Parent message ID (LibreChat extension) */
+ parent_message_id?: string;
+}
+
+/**
+ * Token usage information
+ */
+export interface CompletionUsage {
+ prompt_tokens: number;
+ completion_tokens: number;
+ total_tokens: number;
+ /** Detailed breakdown of output tokens (OpenRouter/OpenAI convention) */
+ completion_tokens_details?: {
+ reasoning_tokens?: number;
+ };
+}
+
+/**
+ * Non-streaming choice
+ */
+export interface ChatCompletionChoice {
+ index: number;
+ message: {
+ role: 'assistant';
+ content: string | null;
+ /** Reasoning/thinking content (OpenRouter convention) */
+ reasoning?: string | null;
+ tool_calls?: ToolCall[];
+ };
+ finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+/**
+ * Non-streaming response
+ */
+export interface ChatCompletionResponse {
+ id: string;
+ object: 'chat.completion';
+ created: number;
+ model: string;
+ choices: ChatCompletionChoice[];
+ usage?: CompletionUsage;
+}
+
+/**
+ * Streaming choice delta
+ * Note: `reasoning` field follows OpenRouter convention for streaming reasoning/thinking content
+ */
+export interface ChatCompletionChunkChoice {
+ index: number;
+ delta: {
+ role?: 'assistant';
+ content?: string | null;
+ /** Reasoning/thinking content (OpenRouter convention) */
+ reasoning?: string | null;
+ tool_calls?: Array<{
+ index: number;
+ id?: string;
+ type?: 'function';
+ function?: {
+ name?: string;
+ arguments?: string;
+ };
+ }>;
+ };
+ finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+/**
+ * Streaming response chunk
+ */
+export interface ChatCompletionChunk {
+ id: string;
+ object: 'chat.completion.chunk';
+ created: number;
+ model: string;
+ choices: ChatCompletionChunkChoice[];
+ /** Final chunk may include usage */
+ usage?: CompletionUsage;
+}
+
+/**
+ * SSE event wrapper for streaming
+ */
+export interface SSEEvent {
+ data: ChatCompletionChunk | '[DONE]';
+}
+
+/**
+ * Context for building OpenAI responses
+ */
+export interface OpenAIResponseContext {
+ /** Request ID for the chat completion */
+ requestId: string;
+ /** Model/agent ID */
+ model: string;
+ /** Created timestamp */
+ created: number;
+}
+
+/**
+ * Aggregated content for building final response
+ */
+export interface AggregatedContent {
+ text: string;
+ toolCalls: ToolCall[];
+}
+
+/**
+ * Error response in OpenAI format
+ */
+export interface OpenAIErrorResponse {
+ error: {
+ message: string;
+ type: string;
+ param: string | null;
+ code: string | null;
+ };
+}
diff --git a/packages/api/src/agents/responses/handlers.ts b/packages/api/src/agents/responses/handlers.ts
new file mode 100644
index 0000000000..712be852bd
--- /dev/null
+++ b/packages/api/src/agents/responses/handlers.ts
@@ -0,0 +1,914 @@
+/**
+ * Open Responses API Handlers
+ *
+ * Semantic event emitters and response tracking for the Open Responses API.
+ * Events follow the Open Responses spec with proper lifecycle management.
+ */
+import type { Response as ServerResponse } from 'express';
+import type {
+ Response,
+ ResponseContext,
+ ResponseEvent,
+ OutputItem,
+ MessageItem,
+ FunctionCallItem,
+ FunctionCallOutputItem,
+ ReasoningItem,
+ OutputTextContent,
+ ReasoningTextContent,
+ ItemStatus,
+ ResponseStatus,
+} from './types';
+
+/* =============================================================================
+ * RESPONSE TRACKER
+ * ============================================================================= */
+
+/**
+ * Tracks the state of a response during streaming.
+ * Manages items, sequence numbers, and accumulated content.
+ */
+export interface ResponseTracker {
+ /** Current sequence number (monotonically increasing) */
+ sequenceNumber: number;
+ /** Output items being built */
+ items: OutputItem[];
+ /** Current message item (if any) */
+ currentMessage: MessageItem | null;
+ /** Current message content index */
+ currentContentIndex: number;
+ /** Current reasoning item (if any) */
+ currentReasoning: ReasoningItem | null;
+ /** Current reasoning content index */
+ currentReasoningContentIndex: number;
+ /** Map of function call items by call_id */
+ functionCalls: Map<string, FunctionCallItem>;
+ /** Map of function call outputs by call_id */
+ functionCallOutputs: Map<string, FunctionCallOutputItem>;
+ /** Accumulated text for current message */
+ accumulatedText: string;
+ /** Accumulated reasoning text */
+ accumulatedReasoningText: string;
+ /** Accumulated function call arguments by call_id */
+ accumulatedArguments: Map<string, string>;
+ /** Token usage */
+ usage: {
+ inputTokens: number;
+ outputTokens: number;
+ reasoningTokens: number;
+ cachedTokens: number;
+ };
+ /** Response status */
+ status: ResponseStatus;
+ /** Get next sequence number */
+ nextSequence: () => number;
+}
+
+/**
+ * Create a new response tracker
+ */
+export function createResponseTracker(): ResponseTracker {
+ const tracker: ResponseTracker = {
+ sequenceNumber: 0,
+ items: [],
+ currentMessage: null,
+ currentContentIndex: 0,
+ currentReasoning: null,
+ currentReasoningContentIndex: 0,
+ functionCalls: new Map(),
+ functionCallOutputs: new Map(),
+ accumulatedText: '',
+ accumulatedReasoningText: '',
+ accumulatedArguments: new Map(),
+ usage: {
+ inputTokens: 0,
+ outputTokens: 0,
+ reasoningTokens: 0,
+ cachedTokens: 0,
+ },
+ status: 'in_progress',
+ nextSequence: () => tracker.sequenceNumber++,
+ };
+ return tracker;
+}
+
+/* =============================================================================
+ * SSE EVENT WRITING
+ * ============================================================================= */
+
+/**
+ * Write a semantic SSE event to the response.
+ * The `event:` field matches the `type` in the data payload.
+ */
+export function writeEvent(res: ServerResponse, event: ResponseEvent): void {
+ res.write(`event: ${event.type}\n`);
+ res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+
+/**
+ * Write the terminal [DONE] event
+ */
+export function writeDone(res: ServerResponse): void {
+ res.write('data: [DONE]\n\n');
+}
+
+/* =============================================================================
+ * RESPONSE BUILDING
+ * ============================================================================= */
+
+/**
+ * Build a Response object from context and tracker
+ * Includes all required fields per Open Responses spec
+ */
+export function buildResponse(
+ context: ResponseContext,
+ tracker: ResponseTracker,
+ status: ResponseStatus = 'in_progress',
+): Response {
+ const isCompleted = status === 'completed';
+
+ return {
+ // Required fields
+ id: context.responseId,
+ object: 'response',
+ created_at: context.createdAt,
+ completed_at: isCompleted ? Math.floor(Date.now() / 1000) : null,
+ status,
+ incomplete_details: null,
+ model: context.model,
+ previous_response_id: context.previousResponseId ?? null,
+ instructions: context.instructions ?? null,
+ output: tracker.items,
+ error: null,
+ tools: [],
+ tool_choice: 'auto',
+ truncation: 'disabled',
+ parallel_tool_calls: true,
+ text: { format: { type: 'text' } },
+ temperature: 1,
+ top_p: 1,
+ presence_penalty: 0,
+ frequency_penalty: 0,
+ top_logprobs: 0,
+ reasoning: null,
+ user: null,
+ usage: isCompleted
+ ? {
+ input_tokens: tracker.usage.inputTokens,
+ output_tokens: tracker.usage.outputTokens,
+ total_tokens: tracker.usage.inputTokens + tracker.usage.outputTokens,
+ input_tokens_details: { cached_tokens: tracker.usage.cachedTokens },
+ output_tokens_details: { reasoning_tokens: tracker.usage.reasoningTokens },
+ }
+ : null,
+ max_output_tokens: null,
+ max_tool_calls: null,
+ store: false,
+ background: false,
+ service_tier: 'default',
+ metadata: {},
+ safety_identifier: null,
+ prompt_cache_key: null,
+ };
+}
+
+/* =============================================================================
+ * ITEM BUILDERS
+ * ============================================================================= */
+
+let itemIdCounter = 0;
+
+/**
+ * Generate a unique item ID
+ */
+export function generateItemId(prefix: string): string {
+ return `${prefix}_${Date.now().toString(36)}${(itemIdCounter++).toString(36)}`;
+}
+
+/**
+ * Create a new message item
+ */
+export function createMessageItem(status: ItemStatus = 'in_progress'): MessageItem {
+ return {
+ type: 'message',
+ id: generateItemId('msg'),
+ role: 'assistant',
+ status,
+ content: [],
+ };
+}
+
+/**
+ * Create a new function call item
+ */
+export function createFunctionCallItem(
+ callId: string,
+ name: string,
+ status: ItemStatus = 'in_progress',
+): FunctionCallItem {
+ return {
+ type: 'function_call',
+ id: generateItemId('fc'),
+ call_id: callId,
+ name,
+ arguments: '',
+ status,
+ };
+}
+
+/**
+ * Create a new function call output item
+ */
+export function createFunctionCallOutputItem(
+ callId: string,
+ output: string,
+ status: ItemStatus = 'completed',
+): FunctionCallOutputItem {
+ return {
+ type: 'function_call_output',
+ id: generateItemId('fco'),
+ call_id: callId,
+ output,
+ status,
+ };
+}
+
+/**
+ * Create a new reasoning item
+ */
+export function createReasoningItem(status: ItemStatus = 'in_progress'): ReasoningItem {
+ return {
+ type: 'reasoning',
+ id: generateItemId('reason'),
+ status,
+ content: [],
+ summary: [],
+ };
+}
+
+/**
+ * Create output text content
+ */
+export function createOutputTextContent(text: string = ''): OutputTextContent {
+ return {
+ type: 'output_text',
+ text,
+ annotations: [],
+ logprobs: [],
+ };
+}
+
+/**
+ * Create reasoning text content
+ */
+export function createReasoningTextContent(text: string = ''): ReasoningTextContent {
+ return {
+ type: 'reasoning_text',
+ text,
+ };
+}
+
+/* =============================================================================
+ * STREAMING EVENT EMITTERS
+ * ============================================================================= */
+
+export interface StreamHandlerConfig {
+ res: ServerResponse;
+ context: ResponseContext;
+ tracker: ResponseTracker;
+}
+
+/**
+ * Emit response.created event
+ * This is the first event emitted per the Open Responses spec
+ */
+export function emitResponseCreated(config: StreamHandlerConfig): void {
+ const { res, context, tracker } = config;
+ const response = buildResponse(context, tracker, 'in_progress');
+ writeEvent(res, {
+ type: 'response.created',
+ sequence_number: tracker.nextSequence(),
+ response,
+ });
+}
+
+/**
+ * Emit response.in_progress event
+ */
+export function emitResponseInProgress(config: StreamHandlerConfig): void {
+ const { res, context, tracker } = config;
+ const response = buildResponse(context, tracker, 'in_progress');
+ writeEvent(res, {
+ type: 'response.in_progress',
+ sequence_number: tracker.nextSequence(),
+ response,
+ });
+}
+
+/**
+ * Emit response.completed event
+ */
+export function emitResponseCompleted(config: StreamHandlerConfig): void {
+ const { res, context, tracker } = config;
+ tracker.status = 'completed';
+ const response = buildResponse(context, tracker, 'completed');
+ writeEvent(res, {
+ type: 'response.completed',
+ sequence_number: tracker.nextSequence(),
+ response,
+ });
+}
+
+/**
+ * Emit response.failed event
+ */
+export function emitResponseFailed(
+ config: StreamHandlerConfig,
+ error: { type: string; message: string; code?: string },
+): void {
+ const { res, context, tracker } = config;
+ tracker.status = 'failed';
+ const response = buildResponse(context, tracker, 'failed');
+ response.error = {
+ type: error.type as
+ | 'server_error'
+ | 'invalid_request'
+ | 'not_found'
+ | 'model_error'
+ | 'too_many_requests',
+ message: error.message,
+ code: error.code,
+ };
+ writeEvent(res, {
+ type: 'response.failed',
+ sequence_number: tracker.nextSequence(),
+ response,
+ });
+}
+
+/**
+ * Emit response.output_item.added event for a message
+ */
+export function emitMessageItemAdded(config: StreamHandlerConfig): MessageItem {
+ const { res, tracker } = config;
+ const item = createMessageItem('in_progress');
+ tracker.currentMessage = item;
+ tracker.currentContentIndex = 0;
+ tracker.accumulatedText = '';
+ tracker.items.push(item);
+
+ writeEvent(res, {
+ type: 'response.output_item.added',
+ sequence_number: tracker.nextSequence(),
+ output_index: tracker.items.length - 1,
+ item,
+ });
+
+ return item;
+}
+
+/**
+ * Emit response.output_item.done event for a message
+ */
+export function emitMessageItemDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentMessage) {
+ return;
+ }
+
+ tracker.currentMessage.status = 'completed';
+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);
+
+ writeEvent(res, {
+ type: 'response.output_item.done',
+ sequence_number: tracker.nextSequence(),
+ output_index: outputIndex,
+ item: tracker.currentMessage,
+ });
+
+ tracker.currentMessage = null;
+}
+
+/**
+ * Emit response.content_part.added for text content
+ */
+export function emitTextContentPartAdded(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentMessage) {
+ return;
+ }
+
+ const part = createOutputTextContent('');
+ tracker.currentMessage.content.push(part);
+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);
+
+ writeEvent(res, {
+ type: 'response.content_part.added',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentMessage.id,
+ output_index: outputIndex,
+ content_index: tracker.currentContentIndex,
+ part,
+ });
+}
+
+/**
+ * Emit response.output_text.delta event
+ */
+export function emitOutputTextDelta(config: StreamHandlerConfig, delta: string): void {
+ const { res, tracker } = config;
+ if (!tracker.currentMessage) {
+ return;
+ }
+
+ tracker.accumulatedText += delta;
+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);
+
+ writeEvent(res, {
+ type: 'response.output_text.delta',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentMessage.id,
+ output_index: outputIndex,
+ content_index: tracker.currentContentIndex,
+ delta,
+ logprobs: [],
+ });
+}
+
+/**
+ * Emit response.output_text.done event
+ */
+export function emitOutputTextDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentMessage) {
+ return;
+ }
+
+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);
+ const contentIndex = tracker.currentContentIndex;
+
+ // Update the content part with final text
+ if (tracker.currentMessage.content[contentIndex]) {
+ (tracker.currentMessage.content[contentIndex] as OutputTextContent).text =
+ tracker.accumulatedText;
+ }
+
+ writeEvent(res, {
+ type: 'response.output_text.done',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentMessage.id,
+ output_index: outputIndex,
+ content_index: contentIndex,
+ text: tracker.accumulatedText,
+ logprobs: [],
+ });
+}
+
+/**
+ * Emit response.content_part.done for text content
+ */
+export function emitTextContentPartDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentMessage) {
+ return;
+ }
+
+ const outputIndex = tracker.items.indexOf(tracker.currentMessage);
+ const contentIndex = tracker.currentContentIndex;
+ const part = tracker.currentMessage.content[contentIndex];
+
+ if (part) {
+ writeEvent(res, {
+ type: 'response.content_part.done',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentMessage.id,
+ output_index: outputIndex,
+ content_index: contentIndex,
+ part,
+ });
+ }
+
+ tracker.currentContentIndex++;
+}
+
+/* =============================================================================
+ * FUNCTION CALL EVENT EMITTERS
+ * ============================================================================= */
+
+/**
+ * Emit response.output_item.added for a function call
+ */
+export function emitFunctionCallItemAdded(
+ config: StreamHandlerConfig,
+ callId: string,
+ name: string,
+): FunctionCallItem {
+ const { res, tracker } = config;
+ const item = createFunctionCallItem(callId, name, 'in_progress');
+ tracker.functionCalls.set(callId, item);
+ tracker.accumulatedArguments.set(callId, '');
+ tracker.items.push(item);
+
+ writeEvent(res, {
+ type: 'response.output_item.added',
+ sequence_number: tracker.nextSequence(),
+ output_index: tracker.items.length - 1,
+ item,
+ });
+
+ return item;
+}
+
+/**
+ * Emit response.function_call_arguments.delta event
+ */
+export function emitFunctionCallArgumentsDelta(
+ config: StreamHandlerConfig,
+ callId: string,
+ delta: string,
+): void {
+ const { res, tracker } = config;
+ const item = tracker.functionCalls.get(callId);
+ if (!item) {
+ return;
+ }
+
+ const accumulated = (tracker.accumulatedArguments.get(callId) ?? '') + delta;
+ tracker.accumulatedArguments.set(callId, accumulated);
+ item.arguments = accumulated;
+
+ const outputIndex = tracker.items.indexOf(item);
+
+ writeEvent(res, {
+ type: 'response.function_call_arguments.delta',
+ sequence_number: tracker.nextSequence(),
+ item_id: item.id,
+ output_index: outputIndex,
+ call_id: callId,
+ delta,
+ });
+}
+
+/**
+ * Emit response.function_call_arguments.done event
+ */
+export function emitFunctionCallArgumentsDone(config: StreamHandlerConfig, callId: string): void {
+ const { res, tracker } = config;
+ const item = tracker.functionCalls.get(callId);
+ if (!item) {
+ return;
+ }
+
+ const outputIndex = tracker.items.indexOf(item);
+ const args = tracker.accumulatedArguments.get(callId) ?? '';
+
+ writeEvent(res, {
+ type: 'response.function_call_arguments.done',
+ sequence_number: tracker.nextSequence(),
+ item_id: item.id,
+ output_index: outputIndex,
+ call_id: callId,
+ arguments: args,
+ });
+}
+
+/**
+ * Emit response.output_item.done for a function call
+ */
+export function emitFunctionCallItemDone(config: StreamHandlerConfig, callId: string): void {
+ const { res, tracker } = config;
+ const item = tracker.functionCalls.get(callId);
+ if (!item) {
+ return;
+ }
+
+ item.status = 'completed';
+ const outputIndex = tracker.items.indexOf(item);
+
+ writeEvent(res, {
+ type: 'response.output_item.done',
+ sequence_number: tracker.nextSequence(),
+ output_index: outputIndex,
+ item,
+ });
+}
+
+/**
+ * Emit function call output item (internal tool result)
+ */
+export function emitFunctionCallOutputItem(
+ config: StreamHandlerConfig,
+ callId: string,
+ output: string,
+): void {
+ const { res, tracker } = config;
+ const item = createFunctionCallOutputItem(callId, output, 'completed');
+ tracker.functionCallOutputs.set(callId, item);
+ tracker.items.push(item);
+
+ // Emit added
+ writeEvent(res, {
+ type: 'response.output_item.added',
+ sequence_number: tracker.nextSequence(),
+ output_index: tracker.items.length - 1,
+ item,
+ });
+
+ // Immediately emit done since it's already complete
+ writeEvent(res, {
+ type: 'response.output_item.done',
+ sequence_number: tracker.nextSequence(),
+ output_index: tracker.items.length - 1,
+ item,
+ });
+}
+
+/* =============================================================================
+ * REASONING EVENT EMITTERS
+ * ============================================================================= */
+
+/**
+ * Emit response.output_item.added for reasoning
+ */
+export function emitReasoningItemAdded(config: StreamHandlerConfig): ReasoningItem {
+ const { res, tracker } = config;
+ const item = createReasoningItem('in_progress');
+ tracker.currentReasoning = item;
+ tracker.currentReasoningContentIndex = 0;
+ tracker.accumulatedReasoningText = '';
+ tracker.items.push(item);
+
+ writeEvent(res, {
+ type: 'response.output_item.added',
+ sequence_number: tracker.nextSequence(),
+ output_index: tracker.items.length - 1,
+ item,
+ });
+
+ return item;
+}
+
+/**
+ * Emit response.content_part.added for reasoning
+ */
+export function emitReasoningContentPartAdded(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentReasoning) {
+ return;
+ }
+
+ const part = createReasoningTextContent('');
+ if (!tracker.currentReasoning.content) {
+ tracker.currentReasoning.content = [];
+ }
+ tracker.currentReasoning.content.push(part);
+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);
+
+ writeEvent(res, {
+ type: 'response.content_part.added',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentReasoning.id,
+ output_index: outputIndex,
+ content_index: tracker.currentReasoningContentIndex,
+ part,
+ });
+}
+
+/**
+ * Emit response.reasoning.delta event
+ */
+export function emitReasoningDelta(config: StreamHandlerConfig, delta: string): void {
+ const { res, tracker } = config;
+ if (!tracker.currentReasoning) {
+ return;
+ }
+
+ tracker.accumulatedReasoningText += delta;
+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);
+
+ writeEvent(res, {
+ type: 'response.reasoning.delta',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentReasoning.id,
+ output_index: outputIndex,
+ content_index: tracker.currentReasoningContentIndex,
+ delta,
+ });
+}
+
+/**
+ * Emit response.reasoning.done event
+ */
+export function emitReasoningDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentReasoning || !tracker.currentReasoning.content) {
+ return;
+ }
+
+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);
+ const contentIndex = tracker.currentReasoningContentIndex;
+
+ // Update the content part with final text
+ if (tracker.currentReasoning.content[contentIndex]) {
+ (tracker.currentReasoning.content[contentIndex] as ReasoningTextContent).text =
+ tracker.accumulatedReasoningText;
+ }
+
+ writeEvent(res, {
+ type: 'response.reasoning.done',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentReasoning.id,
+ output_index: outputIndex,
+ content_index: contentIndex,
+ text: tracker.accumulatedReasoningText,
+ });
+}
+
+/**
+ * Emit response.content_part.done for reasoning
+ */
+export function emitReasoningContentPartDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentReasoning || !tracker.currentReasoning.content) {
+ return;
+ }
+
+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);
+ const contentIndex = tracker.currentReasoningContentIndex;
+ const part = tracker.currentReasoning.content[contentIndex];
+
+ if (part) {
+ writeEvent(res, {
+ type: 'response.content_part.done',
+ sequence_number: tracker.nextSequence(),
+ item_id: tracker.currentReasoning.id,
+ output_index: outputIndex,
+ content_index: contentIndex,
+ part,
+ });
+ }
+
+ tracker.currentReasoningContentIndex++;
+}
+
+/**
+ * Emit response.output_item.done for reasoning
+ */
+export function emitReasoningItemDone(config: StreamHandlerConfig): void {
+ const { res, tracker } = config;
+ if (!tracker.currentReasoning) {
+ return;
+ }
+
+ tracker.currentReasoning.status = 'completed';
+ const outputIndex = tracker.items.indexOf(tracker.currentReasoning);
+
+ writeEvent(res, {
+ type: 'response.output_item.done',
+ sequence_number: tracker.nextSequence(),
+ output_index: outputIndex,
+ item: tracker.currentReasoning,
+ });
+
+ tracker.currentReasoning = null;
+}
+
+/* =============================================================================
+ * ERROR HANDLING
+ * ============================================================================= */
+
+/**
+ * Emit error event
+ */
+export function emitError(
+ config: StreamHandlerConfig,
+ error: { type: string; message: string; code?: string },
+): void {
+ const { res, tracker } = config;
+
+ writeEvent(res, {
+ type: 'error',
+ sequence_number: tracker.nextSequence(),
+ error: {
+ type: error.type as 'server_error',
+ message: error.message,
+ code: error.code,
+ },
+ });
+}
+
+/* =============================================================================
+ * LIBRECHAT EXTENSION EVENTS
+ * Custom events prefixed with 'librechat:' per Open Responses spec
+ * @see https://openresponses.org/specification#extending-streaming-events
+ * ============================================================================= */
+
+/**
+ * Attachment data for librechat:attachment events
+ */
+export interface AttachmentData {
+ /** File ID in LibreChat storage */
+ file_id?: string;
+ /** Original filename */
+ filename?: string;
+ /** MIME type */
+ type?: string;
+ /** URL to access the file */
+ url?: string;
+ /** Base64-encoded image data (for inline images) */
+ image_url?: string;
+ /** Width for images */
+ width?: number;
+ /** Height for images */
+ height?: number;
+ /** Associated tool call ID */
+ tool_call_id?: string;
+ /** Additional metadata */
+ [key: string]: unknown;
+}
+
+/**
+ * Emit librechat:attachment event for file/image attachments
+ * This is a LibreChat extension to the Open Responses streaming protocol.
+ * External clients can safely ignore these events.
+ */
+export function emitAttachment(
+ config: StreamHandlerConfig,
+ attachment: AttachmentData,
+ options?: {
+ messageId?: string;
+ conversationId?: string;
+ },
+): void {
+ const { res, tracker } = config;
+
+ writeEvent(res, {
+ type: 'librechat:attachment',
+ sequence_number: tracker.nextSequence(),
+ attachment,
+ message_id: options?.messageId,
+ conversation_id: options?.conversationId,
+ });
+}
+
+/**
+ * Write attachment event directly to response (for use outside streaming context)
+ * Useful when attachment processing happens asynchronously
+ */
+export function writeAttachmentEvent(
+ res: ServerResponse,
+ sequenceNumber: number,
+ attachment: AttachmentData,
+ options?: {
+ messageId?: string;
+ conversationId?: string;
+ },
+): void {
+ writeEvent(res, {
+ type: 'librechat:attachment',
+ sequence_number: sequenceNumber,
+ attachment,
+ message_id: options?.messageId,
+ conversation_id: options?.conversationId,
+ });
+}
+
+/* =============================================================================
+ * NON-STREAMING RESPONSE BUILDER
+ * ============================================================================= */
+
+/**
+ * Build a complete non-streaming response
+ */
+export function buildResponsesNonStreamingResponse(
+ context: ResponseContext,
+ tracker: ResponseTracker,
+): Response {
+ return buildResponse(context, tracker, 'completed');
+}
+
+/**
+ * Update tracker usage from collected data
+ */
+export function updateTrackerUsage(
+ tracker: ResponseTracker,
+ usage: {
+ promptTokens?: number;
+ completionTokens?: number;
+ reasoningTokens?: number;
+ cachedTokens?: number;
+ },
+): void {
+ if (usage.promptTokens != null) {
+ tracker.usage.inputTokens = usage.promptTokens;
+ }
+ if (usage.completionTokens != null) {
+ tracker.usage.outputTokens = usage.completionTokens;
+ }
+ if (usage.reasoningTokens != null) {
+ tracker.usage.reasoningTokens = usage.reasoningTokens;
+ }
+ if (usage.cachedTokens != null) {
+ tracker.usage.cachedTokens = usage.cachedTokens;
+ }
+}
diff --git a/packages/api/src/agents/responses/index.ts b/packages/api/src/agents/responses/index.ts
new file mode 100644
index 0000000000..ecfb1c2047
--- /dev/null
+++ b/packages/api/src/agents/responses/index.ts
@@ -0,0 +1,183 @@
+/**
+ * Open Responses API Module
+ *
+ * Exports for the Open Responses API implementation.
+ * @see https://openresponses.org/specification
+ */
+
+// Types
+export type {
+ // Enums
+ ItemStatus,
+ ResponseStatus,
+ MessageRole,
+ ToolChoiceValue,
+ TruncationValue,
+ ServiceTier,
+ ReasoningEffort,
+ ReasoningSummary,
+ // Input content
+ InputTextContent,
+ InputImageContent,
+ InputFileContent,
+ InputContent,
+ // Output content
+ LogProb,
+ TopLogProb,
+ OutputTextContent,
+ RefusalContent,
+ ModelContent,
+ // Annotations
+ UrlCitationAnnotation,
+ FileCitationAnnotation,
+ Annotation,
+ // Reasoning content
+ ReasoningTextContent,
+ SummaryTextContent,
+ ReasoningContent,
+ // Input items
+ SystemMessageItemParam,
+ DeveloperMessageItemParam,
+ UserMessageItemParam,
+ AssistantMessageItemParam,
+ FunctionCallItemParam,
+ FunctionCallOutputItemParam,
+ ReasoningItemParam,
+ ItemReferenceParam,
+ InputItem,
+ // Output items
+ MessageItem,
+ FunctionCallItem,
+ FunctionCallOutputItem,
+ ReasoningItem,
+ OutputItem,
+ // Tools
+ FunctionTool,
+ HostedTool,
+ Tool,
+ FunctionToolChoice,
+ ToolChoice,
+ // Request
+ ReasoningConfig,
+ TextConfig,
+ StreamOptions,
+ Metadata,
+ ResponseRequest,
+ // Response field types
+ TextField,
+ // Response
+ InputTokensDetails,
+ OutputTokensDetails,
+ Usage,
+ IncompleteDetails,
+ ResponseError,
+ Response,
+ // Streaming events
+ BaseEvent,
+ ResponseCreatedEvent,
+ ResponseInProgressEvent,
+ ResponseCompletedEvent,
+ ResponseFailedEvent,
+ ResponseIncompleteEvent,
+ OutputItemAddedEvent,
+ OutputItemDoneEvent,
+ ContentPartAddedEvent,
+ ContentPartDoneEvent,
+ OutputTextDeltaEvent,
+ OutputTextDoneEvent,
+ RefusalDeltaEvent,
+ RefusalDoneEvent,
+ FunctionCallArgumentsDeltaEvent,
+ FunctionCallArgumentsDoneEvent,
+ ReasoningDeltaEvent,
+ ReasoningDoneEvent,
+ ErrorEvent,
+ ResponseEvent,
+ // LibreChat extensions
+ LibreChatAttachmentContent,
+ LibreChatAttachmentEvent,
+ // Internal
+ ResponseContext,
+ RequestValidationResult,
+} from './types';
+
+// Handlers
+export {
+ // Tracker
+ createResponseTracker,
+ type ResponseTracker,
+ // SSE
+ writeEvent,
+ writeDone,
+ // Response building
+ buildResponse,
+ // Item builders
+ generateItemId,
+ createMessageItem,
+ createFunctionCallItem,
+ createFunctionCallOutputItem,
+ createReasoningItem,
+ createOutputTextContent,
+ createReasoningTextContent,
+ // Stream config
+ type StreamHandlerConfig,
+ // Response events
+ emitResponseCreated,
+ emitResponseInProgress,
+ emitResponseCompleted,
+ emitResponseFailed,
+ // Message events
+ emitMessageItemAdded,
+ emitMessageItemDone,
+ emitTextContentPartAdded,
+ emitOutputTextDelta,
+ emitOutputTextDone,
+ emitTextContentPartDone,
+ // Function call events
+ emitFunctionCallItemAdded,
+ emitFunctionCallArgumentsDelta,
+ emitFunctionCallArgumentsDone,
+ emitFunctionCallItemDone,
+ emitFunctionCallOutputItem,
+ // Reasoning events
+ emitReasoningItemAdded,
+ emitReasoningContentPartAdded,
+ emitReasoningDelta,
+ emitReasoningDone,
+ emitReasoningContentPartDone,
+ emitReasoningItemDone,
+ // Error events
+ emitError,
+ // LibreChat extension events
+ emitAttachment,
+ writeAttachmentEvent,
+ type AttachmentData,
+ // Non-streaming
+ buildResponsesNonStreamingResponse,
+ updateTrackerUsage,
+} from './handlers';
+
+// Service
+export {
+ // Validation
+ validateResponseRequest,
+ isValidationFailure,
+ // Input conversion
+ convertInputToMessages,
+ mergeMessagesWithInput,
+ type InternalMessage,
+ // Error response
+ sendResponsesErrorResponse,
+ // Context
+ generateResponseId,
+ createResponseContext,
+ // Streaming setup
+ setupStreamingResponse,
+ // Event handlers
+ createResponsesEventHandlers,
+ // Non-streaming
+ createResponseAggregator,
+ buildAggregatedResponse,
+ createAggregatorEventHandlers,
+ type ResponseAggregator,
+} from './service';
diff --git a/packages/api/src/agents/responses/service.ts b/packages/api/src/agents/responses/service.ts
new file mode 100644
index 0000000000..842db86679
--- /dev/null
+++ b/packages/api/src/agents/responses/service.ts
@@ -0,0 +1,869 @@
+/**
+ * Open Responses API Service
+ *
+ * Core service for processing Open Responses API requests.
+ * Handles input conversion, message formatting, and request validation.
+ */
+import type { Response as ServerResponse } from 'express';
+import type {
+ ResponseRequest,
+ RequestValidationResult,
+ InputItem,
+ InputContent,
+ ResponseContext,
+ Response,
+} from './types';
+import {
+ writeDone,
+ emitResponseCompleted,
+ emitMessageItemAdded,
+ emitMessageItemDone,
+ emitTextContentPartAdded,
+ emitOutputTextDelta,
+ emitOutputTextDone,
+ emitTextContentPartDone,
+ emitFunctionCallItemAdded,
+ emitFunctionCallArgumentsDelta,
+ emitFunctionCallArgumentsDone,
+ emitFunctionCallItemDone,
+ emitFunctionCallOutputItem,
+ emitReasoningItemAdded,
+ emitReasoningContentPartAdded,
+ emitReasoningDelta,
+ emitReasoningDone,
+ emitReasoningContentPartDone,
+ emitReasoningItemDone,
+ updateTrackerUsage,
+ type StreamHandlerConfig,
+} from './handlers';
+
+/* =============================================================================
+ * REQUEST VALIDATION
+ * ============================================================================= */
+
+/**
+ * Validate a request body
+ */
+export function validateResponseRequest(body: unknown): RequestValidationResult {
+ if (!body || typeof body !== 'object') {
+ return { valid: false, error: 'Request body is required' };
+ }
+
+ const request = body as Record<string, unknown>;
+
+ // Required: model
+ if (!request.model || typeof request.model !== 'string') {
+ return { valid: false, error: 'model is required and must be a string' };
+ }
+
+ // Required: input (string or array)
+ if (request.input === undefined || request.input === null) {
+ return { valid: false, error: 'input is required' };
+ }
+
+ if (typeof request.input !== 'string' && !Array.isArray(request.input)) {
+ return { valid: false, error: 'input must be a string or array of items' };
+ }
+
+ // Optional validations
+ if (request.stream !== undefined && typeof request.stream !== 'boolean') {
+ return { valid: false, error: 'stream must be a boolean' };
+ }
+
+ if (request.temperature !== undefined) {
+ const temp = request.temperature as number;
+ if (typeof temp !== 'number' || temp < 0 || temp > 2) {
+ return { valid: false, error: 'temperature must be a number between 0 and 2' };
+ }
+ }
+
+ if (request.max_output_tokens !== undefined) {
+ if (typeof request.max_output_tokens !== 'number' || request.max_output_tokens < 1) {
+ return { valid: false, error: 'max_output_tokens must be a positive number' };
+ }
+ }
+
+ return { valid: true, request: request as unknown as ResponseRequest };
+}
+
+/**
+ * Check if validation failed
+ */
+export function isValidationFailure(
+ result: RequestValidationResult,
+): result is { valid: false; error: string } {
+ return !result.valid;
+}
+
+/* =============================================================================
+ * INPUT CONVERSION
+ * ============================================================================= */
+
+/** Internal message format (LibreChat-compatible) */
+export interface InternalMessage {
+ role: 'system' | 'user' | 'assistant' | 'tool';
+ content: string | Array<{ type: string; text?: string; image_url?: unknown }>;
+ name?: string;
+ tool_call_id?: string;
+ tool_calls?: Array<{
+ id: string;
+ type: 'function';
+ function: { name: string; arguments: string };
+ }>;
+}
+
+/**
+ * Convert Open Responses input to internal message format.
+ * Handles both string input and array of items.
+ */
+export function convertInputToMessages(input: string | InputItem[]): InternalMessage[] {
+ // Simple string input becomes a user message
+ if (typeof input === 'string') {
+ return [{ role: 'user', content: input }];
+ }
+
+ const messages: InternalMessage[] = [];
+
+ for (const item of input) {
+ if (item.type === 'item_reference') {
+ // Skip item references - they're handled by previous_response_id
+ continue;
+ }
+
+ if (item.type === 'message') {
+ const messageItem = item as {
+ type: 'message';
+ role: string;
+ content: string | InputContent[];
+ };
+
+ let content: InternalMessage['content'];
+
+ if (typeof messageItem.content === 'string') {
+ content = messageItem.content;
+ } else if (Array.isArray(messageItem.content)) {
+ content = messageItem.content.map((part) => {
+ if (part.type === 'input_text') {
+ return { type: 'text', text: part.text };
+ }
+ if (part.type === 'input_image') {
+ return {
+ type: 'image_url',
+ image_url: {
+ url: (part as { image_url?: string }).image_url,
+ detail: (part as { detail?: string }).detail,
+ },
+ };
+ }
+ return { type: part.type };
+ });
+ } else {
+ content = '';
+ }
+
+ // Map developer role to system (LibreChat convention)
+ let role: InternalMessage['role'];
+ if (messageItem.role === 'developer') {
+ role = 'system';
+ } else if (messageItem.role === 'user') {
+ role = 'user';
+ } else if (messageItem.role === 'assistant') {
+ role = 'assistant';
+ } else if (messageItem.role === 'system') {
+ role = 'system';
+ } else {
+ role = 'user';
+ }
+
+ messages.push({ role, content });
+ }
+
+ if (item.type === 'function_call') {
+ // Function call items represent prior tool calls from assistant
+ const fcItem = item as {
+ type: 'function_call';
+ call_id: string;
+ name: string;
+ arguments: string;
+ };
+
+ // Add as assistant message with tool_calls
+ messages.push({
+ role: 'assistant',
+ content: '',
+ tool_calls: [
+ {
+ id: fcItem.call_id,
+ type: 'function',
+ function: { name: fcItem.name, arguments: fcItem.arguments },
+ },
+ ],
+ });
+ }
+
+ if (item.type === 'function_call_output') {
+ // Function call output items represent tool results
+ const fcoItem = item as { type: 'function_call_output'; call_id: string; output: string };
+
+ messages.push({
+ role: 'tool',
+ content: fcoItem.output,
+ tool_call_id: fcoItem.call_id,
+ });
+ }
+
+ // Reasoning items are typically not passed back as input
+ // They're model-generated and may be encrypted
+ }
+
+ return messages;
+}
+
+/**
+ * Merge previous conversation messages with new input
+ */
+export function mergeMessagesWithInput(
+ previousMessages: InternalMessage[],
+ newInput: InternalMessage[],
+): InternalMessage[] {
+ return [...previousMessages, ...newInput];
+}
+
+/* =============================================================================
+ * ERROR RESPONSE
+ * ============================================================================= */
+
+/**
+ * Send an error response in Open Responses format
+ */
+export function sendResponsesErrorResponse(
+ res: ServerResponse,
+ statusCode: number,
+ message: string,
+ type: string = 'invalid_request',
+ code?: string,
+): void {
+ res.status(statusCode).json({
+ error: {
+ type,
+ message,
+ code: code ?? null,
+ param: null,
+ },
+ });
+}
+
+/* =============================================================================
+ * RESPONSE CONTEXT
+ * ============================================================================= */
+
+/**
+ * Generate a unique response ID
+ */
+export function generateResponseId(): string {
+ return `resp_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 8)}`;
+}
+
+/**
+ * Create a response context from request
+ */
+export function createResponseContext(
+ request: ResponseRequest,
+ responseId?: string,
+): ResponseContext {
+ return {
+ responseId: responseId ?? generateResponseId(),
+ model: request.model,
+ createdAt: Math.floor(Date.now() / 1000),
+ previousResponseId: request.previous_response_id,
+ instructions: request.instructions,
+ };
+}
+
+/* =============================================================================
+ * STREAMING SETUP
+ * ============================================================================= */
+
+/**
+ * Set up streaming response headers
+ */
+export function setupStreamingResponse(res: ServerResponse): void {
+ 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();
+}
+
+/* =============================================================================
+ * STREAM HANDLER FACTORY
+ * ============================================================================= */
+
+/**
+ * State for tracking streaming progress
+ */
+interface StreamState {
+ messageStarted: boolean;
+ messageContentStarted: boolean;
+ reasoningStarted: boolean;
+ reasoningContentStarted: boolean;
+ activeToolCalls: Set<string>;
+ completedToolCalls: Set<string>;
+}
+
+/**
+ * Create LibreChat event handlers that emit Open Responses events
+ */
+export function createResponsesEventHandlers(config: StreamHandlerConfig): {
+ handlers: Record<string, { handle: (event: string, data: unknown) => void }>;
+ state: StreamState;
+ finalizeStream: () => void;
+} {
+ const state: StreamState = {
+ messageStarted: false,
+ messageContentStarted: false,
+ reasoningStarted: false,
+ reasoningContentStarted: false,
+ activeToolCalls: new Set(),
+ completedToolCalls: new Set(),
+ };
+
+ /**
+ * Ensure message item is started
+ */
+ const ensureMessageStarted = (): void => {
+ if (!state.messageStarted) {
+ emitMessageItemAdded(config);
+ state.messageStarted = true;
+ }
+ };
+
+ /**
+ * Ensure message content part is started
+ */
+ const ensureMessageContentStarted = (): void => {
+ ensureMessageStarted();
+ if (!state.messageContentStarted) {
+ emitTextContentPartAdded(config);
+ state.messageContentStarted = true;
+ }
+ };
+
+ /**
+ * Ensure reasoning item is started
+ */
+ const ensureReasoningStarted = (): void => {
+ if (!state.reasoningStarted) {
+ emitReasoningItemAdded(config);
+ state.reasoningStarted = true;
+ }
+ };
+
+ /**
+ * Ensure reasoning content part is started
+ */
+ const ensureReasoningContentStarted = (): void => {
+ ensureReasoningStarted();
+ if (!state.reasoningContentStarted) {
+ emitReasoningContentPartAdded(config);
+ state.reasoningContentStarted = true;
+ }
+ };
+
+ /**
+ * Close any open content streams
+ */
+ const closeOpenStreams = (): void => {
+ // Close message content if open
+ if (state.messageContentStarted) {
+ emitOutputTextDone(config);
+ emitTextContentPartDone(config);
+ state.messageContentStarted = false;
+ }
+
+ // Close message item if open
+ if (state.messageStarted) {
+ emitMessageItemDone(config);
+ state.messageStarted = false;
+ }
+
+ // Close reasoning content if open
+ if (state.reasoningContentStarted) {
+ emitReasoningDone(config);
+ emitReasoningContentPartDone(config);
+ state.reasoningContentStarted = false;
+ }
+
+ // Close reasoning item if open
+ if (state.reasoningStarted) {
+ emitReasoningItemDone(config);
+ state.reasoningStarted = false;
+ }
+ };
+
+ const handlers = {
+ /**
+ * Handle text message deltas
+ */
+ on_message_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };
+ const content = deltaData?.delta?.content;
+
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ ensureMessageContentStarted();
+ emitOutputTextDelta(config, part.text);
+ }
+ }
+ }
+ },
+ },
+
+ /**
+ * Handle reasoning deltas
+ */
+ on_reasoning_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as {
+ delta?: { content?: Array<{ type: string; text?: string; think?: string }> };
+ };
+ const content = deltaData?.delta?.content;
+
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ const text = part.think || part.text;
+ if (text) {
+ ensureReasoningContentStarted();
+ emitReasoningDelta(config, text);
+ }
+ }
+ }
+ },
+ },
+
+ /**
+ * Handle run step (tool call initiation)
+ */
+ on_run_step: {
+ handle: (_event: string, data: unknown): void => {
+ const stepData = data as {
+ stepDetails?: { type: string; tool_calls?: Array<{ id?: string; name?: string }> };
+ };
+ const stepDetails = stepData?.stepDetails;
+
+ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
+ // Close any open message/reasoning before tool calls
+ closeOpenStreams();
+
+ for (const tc of stepDetails.tool_calls) {
+ const callId = tc.id ?? '';
+ const name = tc.name ?? '';
+
+ if (callId && !state.activeToolCalls.has(callId)) {
+ state.activeToolCalls.add(callId);
+ emitFunctionCallItemAdded(config, callId, name);
+ }
+ }
+ }
+ },
+ },
+
+ /**
+ * Handle run step delta (tool call argument streaming)
+ */
+ on_run_step_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as {
+ delta?: { type: string; tool_calls?: Array<{ index?: number; args?: string }> };
+ };
+ const delta = deltaData?.delta;
+
+ if (delta?.type === 'tool_calls' && delta.tool_calls) {
+ for (const tc of delta.tool_calls) {
+ const args = tc.args ?? '';
+ if (!args) {
+ continue;
+ }
+
+ // Find the call_id for this tool call by index
+ const toolCallsArray = Array.from(state.activeToolCalls);
+ const callId = toolCallsArray[tc.index ?? 0];
+
+ if (callId) {
+ emitFunctionCallArgumentsDelta(config, callId, args);
+ }
+ }
+ }
+ },
+ },
+
+ /**
+ * Handle tool end (tool execution complete)
+ */
+ on_tool_end: {
+ handle: (_event: string, data: unknown): void => {
+ const toolData = data as { tool_call_id?: string; output?: string };
+ const callId = toolData?.tool_call_id;
+ const output = toolData?.output ?? '';
+
+ if (callId && state.activeToolCalls.has(callId) && !state.completedToolCalls.has(callId)) {
+ state.completedToolCalls.add(callId);
+
+ // Complete the function call item
+ emitFunctionCallArgumentsDone(config, callId);
+ emitFunctionCallItemDone(config, callId);
+
+ // Emit the function call output (internal tool result)
+ emitFunctionCallOutputItem(config, callId, output);
+ }
+ },
+ },
+
+ /**
+ * Handle chat model end (usage collection)
+ */
+ on_chat_model_end: {
+ handle: (_event: string, data: unknown): void => {
+ const endData = data as {
+ output?: {
+ usage_metadata?: {
+ input_tokens?: number;
+ output_tokens?: number;
+ // OpenAI format
+ input_token_details?: {
+ cache_creation?: number;
+ cache_read?: number;
+ };
+ // Anthropic format
+ cache_creation_input_tokens?: number;
+ cache_read_input_tokens?: number;
+ };
+ };
+ };
+
+ const usage = endData?.output?.usage_metadata;
+ if (usage) {
+ // Extract cached tokens from either OpenAI or Anthropic format
+ const cachedTokens =
+ (usage.input_token_details?.cache_read ?? 0) + (usage.cache_read_input_tokens ?? 0);
+
+ updateTrackerUsage(config.tracker, {
+ promptTokens: usage.input_tokens,
+ completionTokens: usage.output_tokens,
+ cachedTokens,
+ });
+ }
+ },
+ },
+ };
+
+ /**
+ * Finalize the stream - close open items and emit completed
+ */
+ const finalizeStream = (): void => {
+ closeOpenStreams();
+ emitResponseCompleted(config);
+ writeDone(config.res);
+ };
+
+ return { handlers, state, finalizeStream };
+}
+
+/* =============================================================================
+ * NON-STREAMING AGGREGATOR
+ * ============================================================================= */
+
+/**
+ * Aggregator for non-streaming responses
+ */
+export interface ResponseAggregator {
+ textChunks: string[];
+ reasoningChunks: string[];
+ toolCalls: Map<
+ string,
+ {
+ id: string;
+ name: string;
+ arguments: string;
+ }
+ >;
+ toolOutputs: Map<string, string>;
+ usage: {
+ inputTokens: number;
+ outputTokens: number;
+ reasoningTokens: number;
+ cachedTokens: number;
+ };
+ addText: (text: string) => void;
+ addReasoning: (text: string) => void;
+ getText: () => string;
+ getReasoning: () => string;
+}
+
+/**
+ * Create an aggregator for non-streaming responses
+ */
+export function createResponseAggregator(): ResponseAggregator {
+ const aggregator: ResponseAggregator = {
+ textChunks: [],
+ reasoningChunks: [],
+ toolCalls: new Map(),
+ toolOutputs: new Map(),
+ usage: {
+ inputTokens: 0,
+ outputTokens: 0,
+ reasoningTokens: 0,
+ cachedTokens: 0,
+ },
+ addText: (text: string) => {
+ aggregator.textChunks.push(text);
+ },
+ addReasoning: (text: string) => {
+ aggregator.reasoningChunks.push(text);
+ },
+ getText: () => aggregator.textChunks.join(''),
+ getReasoning: () => aggregator.reasoningChunks.join(''),
+ };
+ return aggregator;
+}
+
+/**
+ * Build a non-streaming response from aggregator
+ * Includes all required fields per Open Responses spec
+ */
+export function buildAggregatedResponse(
+ context: ResponseContext,
+ aggregator: ResponseAggregator,
+): Response {
+ const output: Response['output'] = [];
+
+ // Add reasoning item if present
+ const reasoningText = aggregator.getReasoning();
+ if (reasoningText) {
+ output.push({
+ type: 'reasoning',
+ id: `reason_${Date.now().toString(36)}`,
+ status: 'completed',
+ content: [{ type: 'reasoning_text', text: reasoningText }],
+ summary: [],
+ });
+ }
+
+ // Add function calls and outputs
+ for (const [callId, tc] of aggregator.toolCalls) {
+ output.push({
+ type: 'function_call',
+ id: `fc_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,
+ call_id: callId,
+ name: tc.name,
+ arguments: tc.arguments,
+ status: 'completed',
+ });
+
+ const toolOutput = aggregator.toolOutputs.get(callId);
+ if (toolOutput) {
+ output.push({
+ type: 'function_call_output',
+ id: `fco_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 6)}`,
+ call_id: callId,
+ output: toolOutput,
+ status: 'completed',
+ });
+ }
+ }
+
+ // Add message item if there's text (or always add one if no other output)
+ const text = aggregator.getText();
+ if (text || output.length === 0) {
+ output.push({
+ type: 'message',
+ id: `msg_${Date.now().toString(36)}`,
+ role: 'assistant',
+ status: 'completed',
+ content: text ? [{ type: 'output_text', text, annotations: [], logprobs: [] }] : [],
+ });
+ }
+
+ return {
+ // Required fields per Open Responses spec
+ id: context.responseId,
+ object: 'response',
+ created_at: context.createdAt,
+ completed_at: Math.floor(Date.now() / 1000),
+ status: 'completed',
+ incomplete_details: null,
+ model: context.model,
+ previous_response_id: context.previousResponseId ?? null,
+ instructions: context.instructions ?? null,
+ output,
+ error: null,
+ tools: [],
+ tool_choice: 'auto',
+ truncation: 'disabled',
+ parallel_tool_calls: true,
+ text: { format: { type: 'text' } },
+ temperature: 1,
+ top_p: 1,
+ presence_penalty: 0,
+ frequency_penalty: 0,
+ top_logprobs: 0,
+ reasoning: null,
+ user: null,
+ usage: {
+ input_tokens: aggregator.usage.inputTokens,
+ output_tokens: aggregator.usage.outputTokens,
+ total_tokens: aggregator.usage.inputTokens + aggregator.usage.outputTokens,
+ input_tokens_details: { cached_tokens: aggregator.usage.cachedTokens },
+ output_tokens_details: { reasoning_tokens: aggregator.usage.reasoningTokens },
+ },
+ max_output_tokens: null,
+ max_tool_calls: null,
+ store: false,
+ background: false,
+ service_tier: 'default',
+ metadata: {},
+ safety_identifier: null,
+ prompt_cache_key: null,
+ };
+}
+
+/**
+ * Create event handlers for non-streaming aggregation
+ */
+export function createAggregatorEventHandlers(aggregator: ResponseAggregator): Record<
+ string,
+ {
+ handle: (event: string, data: unknown) => void;
+ }
+> {
+ const activeToolCalls = new Set<string>();
+
+ return {
+ on_message_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as { delta?: { content?: Array<{ type: string; text?: string }> } };
+ const content = deltaData?.delta?.content;
+
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ if (part.type === 'text' && part.text) {
+ aggregator.addText(part.text);
+ }
+ }
+ }
+ },
+ },
+
+ on_reasoning_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as {
+ delta?: { content?: Array<{ type: string; text?: string; think?: string }> };
+ };
+ const content = deltaData?.delta?.content;
+
+ if (Array.isArray(content)) {
+ for (const part of content) {
+ const text = part.think || part.text;
+ if (text) {
+ aggregator.addReasoning(text);
+ }
+ }
+ }
+ },
+ },
+
+ on_run_step: {
+ handle: (_event: string, data: unknown): void => {
+ const stepData = data as {
+ stepDetails?: { type: string; tool_calls?: Array<{ id?: string; name?: string }> };
+ };
+ const stepDetails = stepData?.stepDetails;
+
+ if (stepDetails?.type === 'tool_calls' && stepDetails.tool_calls) {
+ for (const tc of stepDetails.tool_calls) {
+ const callId = tc.id ?? '';
+ const name = tc.name ?? '';
+
+ if (callId && !activeToolCalls.has(callId)) {
+ activeToolCalls.add(callId);
+ aggregator.toolCalls.set(callId, { id: callId, name, arguments: '' });
+ }
+ }
+ }
+ },
+ },
+
+ on_run_step_delta: {
+ handle: (_event: string, data: unknown): void => {
+ const deltaData = data as {
+ delta?: { type: string; tool_calls?: Array<{ index?: number; args?: string }> };
+ };
+ const delta = deltaData?.delta;
+
+ if (delta?.type === 'tool_calls' && delta.tool_calls) {
+ for (const tc of delta.tool_calls) {
+ const args = tc.args ?? '';
+ if (!args) {
+ continue;
+ }
+
+ const toolCallsArray = Array.from(activeToolCalls);
+ const callId = toolCallsArray[tc.index ?? 0];
+
+ if (callId) {
+ const existing = aggregator.toolCalls.get(callId);
+ if (existing) {
+ existing.arguments += args;
+ }
+ }
+ }
+ }
+ },
+ },
+
+ on_tool_end: {
+ handle: (_event: string, data: unknown): void => {
+ const toolData = data as { tool_call_id?: string; output?: string };
+ const callId = toolData?.tool_call_id;
+ const output = toolData?.output ?? '';
+
+ if (callId) {
+ aggregator.toolOutputs.set(callId, output);
+ }
+ },
+ },
+
+ on_chat_model_end: {
+ handle: (_event: string, data: unknown): void => {
+ const endData = data as {
+ output?: {
+ usage_metadata?: {
+ input_tokens?: number;
+ output_tokens?: number;
+ // OpenAI format
+ input_token_details?: {
+ cache_creation?: number;
+ cache_read?: number;
+ };
+ // Anthropic format
+ cache_creation_input_tokens?: number;
+ cache_read_input_tokens?: number;
+ };
+ };
+ };
+
+ const usage = endData?.output?.usage_metadata;
+ if (usage) {
+ aggregator.usage.inputTokens = usage.input_tokens ?? 0;
+ aggregator.usage.outputTokens = usage.output_tokens ?? 0;
+
+ // Extract cached tokens from either OpenAI or Anthropic format
+ aggregator.usage.cachedTokens =
+ (usage.input_token_details?.cache_read ?? 0) + (usage.cache_read_input_tokens ?? 0);
+ }
+ },
+ },
+ };
+}
diff --git a/packages/api/src/agents/responses/types.ts b/packages/api/src/agents/responses/types.ts
new file mode 100644
index 0000000000..65e5887ab8
--- /dev/null
+++ b/packages/api/src/agents/responses/types.ts
@@ -0,0 +1,779 @@
+/**
+ * Open Responses API Types
+ *
+ * Types following the Open Responses specification for building multi-provider,
+ * interoperable LLM interfaces. Items are the fundamental unit of context,
+ * and streaming uses semantic events rather than simple deltas.
+ *
+ * @see https://openresponses.org/specification
+ */
+
+/* =============================================================================
+ * ENUMS
+ * ============================================================================= */
+
+/** Item status lifecycle */
+export type ItemStatus = 'in_progress' | 'incomplete' | 'completed';
+
+/** Response status lifecycle */
+export type ResponseStatus = 'in_progress' | 'completed' | 'failed' | 'incomplete';
+
+/** Message roles */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'developer';
+
+/** Tool choice options */
+export type ToolChoiceValue = 'none' | 'auto' | 'required';
+
+/** Truncation options */
+export type TruncationValue = 'auto' | 'disabled';
+
+/** Service tier options */
+export type ServiceTier = 'auto' | 'default' | 'flex' | 'priority';
+
+/** Reasoning effort levels */
+export type ReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+
+/** Reasoning summary options */
+export type ReasoningSummary = 'concise' | 'detailed' | 'auto';
+
+/* =============================================================================
+ * INPUT CONTENT TYPES
+ * ============================================================================= */
+
+/** Text input content */
+export interface InputTextContent {
+ type: 'input_text';
+ text: string;
+}
+
+/** Image input content */
+export interface InputImageContent {
+ type: 'input_image';
+ image_url?: string;
+ file_id?: string;
+ detail?: 'auto' | 'low' | 'high';
+}
+
+/** File input content */
+export interface InputFileContent {
+ type: 'input_file';
+ file_id?: string;
+ file_data?: string;
+ filename?: string;
+}
+
+/** Union of all input content types */
+export type InputContent = InputTextContent | InputImageContent | InputFileContent;
+
+/* =============================================================================
+ * OUTPUT CONTENT TYPES
+ * ============================================================================= */
+
+/** Log probability for a token */
+export interface LogProb {
+ token: string;
+ logprob: number;
+ bytes?: number[];
+ top_logprobs?: TopLogProb[];
+}
+
+/** Top log probability entry */
+export interface TopLogProb {
+ token: string;
+ logprob: number;
+ bytes?: number[];
+}
+
+/** Text output content */
+export interface OutputTextContent {
+ type: 'output_text';
+ text: string;
+ annotations: Annotation[];
+ logprobs: LogProb[];
+}
+
+/** Refusal content */
+export interface RefusalContent {
+ type: 'refusal';
+ refusal: string;
+}
+
+/** Union of model output content types */
+export type ModelContent = OutputTextContent | RefusalContent;
+
+/* =============================================================================
+ * ANNOTATIONS
+ * ============================================================================= */
+
+/** URL citation annotation */
+export interface UrlCitationAnnotation {
+ type: 'url_citation';
+ url: string;
+ title?: string;
+ start_index: number;
+ end_index: number;
+}
+
+/** File citation annotation */
+export interface FileCitationAnnotation {
+ type: 'file_citation';
+ file_id: string;
+ start_index: number;
+ end_index: number;
+}
+
+/** Union of annotation types */
+export type Annotation = UrlCitationAnnotation | FileCitationAnnotation;
+
+/* =============================================================================
+ * REASONING CONTENT
+ * ============================================================================= */
+
+/** Reasoning text content */
+export interface ReasoningTextContent {
+ type: 'reasoning_text';
+ text: string;
+}
+
+/** Summary text content */
+export interface SummaryTextContent {
+ type: 'summary_text';
+ text: string;
+}
+
+/** Reasoning content union */
+export type ReasoningContent = ReasoningTextContent;
+
+/* =============================================================================
+ * INPUT ITEMS (for request)
+ * ============================================================================= */
+
+/** System message input item */
+export interface SystemMessageItemParam {
+ type: 'message';
+ role: 'system';
+ content: string | InputContent[];
+}
+
+/** Developer message input item */
+export interface DeveloperMessageItemParam {
+ type: 'message';
+ role: 'developer';
+ content: string | InputContent[];
+}
+
+/** User message input item */
+export interface UserMessageItemParam {
+ type: 'message';
+ role: 'user';
+ content: string | InputContent[];
+}
+
+/** Assistant message input item */
+export interface AssistantMessageItemParam {
+ type: 'message';
+ role: 'assistant';
+ content: string | ModelContent[];
+}
+
+/** Function call input item (for providing context) */
+export interface FunctionCallItemParam {
+ type: 'function_call';
+ id: string;
+ call_id: string;
+ name: string;
+ arguments: string;
+ status?: ItemStatus;
+}
+
+/** Function call output input item (for providing tool results) */
+export interface FunctionCallOutputItemParam {
+ type: 'function_call_output';
+ call_id: string;
+ output: string;
+ status?: ItemStatus;
+}
+
+/** Reasoning input item */
+export interface ReasoningItemParam {
+ type: 'reasoning';
+ id?: string;
+ content?: ReasoningContent[];
+ encrypted_content?: string;
+ summary?: SummaryTextContent[];
+ status?: ItemStatus;
+}
+
+/** Item reference (for referencing existing items) */
+export interface ItemReferenceParam {
+ type: 'item_reference';
+ id: string;
+}
+
+/** Union of all input item types */
+export type InputItem =
+ | SystemMessageItemParam
+ | DeveloperMessageItemParam
+ | UserMessageItemParam
+ | AssistantMessageItemParam
+ | FunctionCallItemParam
+ | FunctionCallOutputItemParam
+ | ReasoningItemParam
+ | ItemReferenceParam;
+
+/* =============================================================================
+ * OUTPUT ITEMS (in response)
+ * ============================================================================= */
+
+/** Message output item */
+export interface MessageItem {
+ type: 'message';
+ id: string;
+ role: 'assistant';
+ status: ItemStatus;
+ content: ModelContent[];
+}
+
+/** Function call output item */
+export interface FunctionCallItem {
+ type: 'function_call';
+ id: string;
+ call_id: string;
+ name: string;
+ arguments: string;
+ status: ItemStatus;
+}
+
+/** Function call output result item (internal tool execution result) */
+export interface FunctionCallOutputItem {
+ type: 'function_call_output';
+ id: string;
+ call_id: string;
+ output: string;
+ status: ItemStatus;
+}
+
+/** Reasoning output item */
+export interface ReasoningItem {
+ type: 'reasoning';
+ id: string;
+ status?: ItemStatus;
+ content?: ReasoningContent[];
+ encrypted_content?: string;
+ /** Required per Open Responses spec - summary content parts */
+ summary: SummaryTextContent[];
+}
+
+/** Union of all output item types */
+export type OutputItem = MessageItem | FunctionCallItem | FunctionCallOutputItem | ReasoningItem;
+
+/* =============================================================================
+ * TOOLS
+ * ============================================================================= */
+
+/** Function tool definition */
+export interface FunctionTool {
+ type: 'function';
+ name: string;
+ description?: string;
+ parameters?: Record<string, unknown>;
+ strict?: boolean;
+}
+
+/** Hosted tool (provider-specific) */
+export interface HostedTool {
+ type: string; // e.g., 'librechat:web_search'
+ [key: string]: unknown;
+}
+
+/** Union of tool types */
+export type Tool = FunctionTool | HostedTool;
+
+/** Specific function tool choice */
+export interface FunctionToolChoice {
+ type: 'function';
+ name: string;
+}
+
+/** Tool choice parameter */
+export type ToolChoice = ToolChoiceValue | FunctionToolChoice;
+
+/* =============================================================================
+ * REQUEST
+ * ============================================================================= */
+
+/** Reasoning configuration */
+export interface ReasoningConfig {
+ effort?: ReasoningEffort;
+ summary?: ReasoningSummary;
+}
+
+/** Text output configuration */
+export interface TextConfig {
+ format?: {
+ type: 'text' | 'json_object' | 'json_schema';
+ json_schema?: Record<string, unknown>;
+ };
+}
+
+/** Stream options */
+export interface StreamOptions {
+ include_usage?: boolean;
+}
+
+/** Metadata (key-value pairs) */
+export type Metadata = Record<string, string>;
+
+/** Open Responses API Request */
+export interface ResponseRequest {
+ /** Model/agent ID to use */
+ model: string;
+
+ /** Input context - string or array of items */
+ input: string | InputItem[];
+
+ /** Previous response ID for conversation continuation */
+ previous_response_id?: string;
+
+ /** Tools available to the model */
+ tools?: Tool[];
+
+ /** Tool choice configuration */
+ tool_choice?: ToolChoice;
+
+ /** Whether to stream the response */
+ stream?: boolean;
+
+ /** Stream options */
+ stream_options?: StreamOptions;
+
+ /** Additional instructions */
+ instructions?: string;
+
+ /** Maximum output tokens */
+ max_output_tokens?: number;
+
+ /** Maximum tool calls */
+ max_tool_calls?: number;
+
+ /** Sampling temperature */
+ temperature?: number;
+
+ /** Top-p sampling */
+ top_p?: number;
+
+ /** Presence penalty */
+ presence_penalty?: number;
+
+ /** Frequency penalty */
+ frequency_penalty?: number;
+
+ /** Reasoning configuration */
+ reasoning?: ReasoningConfig;
+
+ /** Text output configuration */
+ text?: TextConfig;
+
+ /** Truncation behavior */
+ truncation?: TruncationValue;
+
+ /** Service tier */
+ service_tier?: ServiceTier;
+
+ /** Whether to store the response */
+ store?: boolean;
+
+ /** Metadata */
+ metadata?: Metadata;
+
+ /** Whether model can call multiple tools in parallel */
+ parallel_tool_calls?: boolean;
+
+ /** User identifier for safety */
+ user?: string;
+}
+
+/* =============================================================================
+ * RESPONSE
+ * ============================================================================= */
+
+/** Token usage details */
+export interface InputTokensDetails {
+ cached_tokens: number;
+}
+
+/** Output tokens details */
+export interface OutputTokensDetails {
+ reasoning_tokens: number;
+}
+
+/** Token usage statistics */
+export interface Usage {
+ input_tokens: number;
+ output_tokens: number;
+ total_tokens: number;
+ input_tokens_details: InputTokensDetails;
+ output_tokens_details: OutputTokensDetails;
+}
+
+/** Incomplete details */
+export interface IncompleteDetails {
+ reason: 'max_output_tokens' | 'max_tool_calls' | 'content_filter' | 'other';
+}
+
+/** Error object */
+export interface ResponseError {
+ type: 'server_error' | 'invalid_request' | 'not_found' | 'model_error' | 'too_many_requests';
+ code?: string;
+ message: string;
+ param?: string;
+}
+
+/** Text field configuration */
+export interface TextField {
+ format?: {
+ type: 'text' | 'json_object' | 'json_schema';
+ json_schema?: Record<string, unknown>;
+ };
+}
+
+/** Open Responses API Response - All required fields per spec */
+export interface Response {
+ /** Response ID */
+ id: string;
+
+ /** Object type - always "response" */
+ object: 'response';
+
+ /** Creation timestamp (Unix seconds) */
+ created_at: number;
+
+ /** Completion timestamp (Unix seconds) - null if not completed */
+ completed_at: number | null;
+
+ /** Response status */
+ status: ResponseStatus;
+
+ /** Incomplete details - null if not incomplete */
+ incomplete_details: IncompleteDetails | null;
+
+ /** Model that generated the response */
+ model: string;
+
+ /** Previous response ID - null if not a continuation */
+ previous_response_id: string | null;
+
+ /** Instructions used - null if none */
+ instructions: string | null;
+
+ /** Output items */
+ output: OutputItem[];
+
+ /** Error - null if no error */
+ error: ResponseError | null;
+
+ /** Tools available */
+ tools: Tool[];
+
+ /** Tool choice setting */
+ tool_choice: ToolChoice;
+
+ /** Truncation setting used */
+ truncation: TruncationValue;
+
+ /** Whether parallel tool calls were allowed */
+ parallel_tool_calls: boolean;
+
+ /** Text configuration used */
+ text: TextField;
+
+ /** Temperature used */
+ temperature: number;
+
+ /** Top-p used */
+ top_p: number;
+
+ /** Presence penalty used */
+ presence_penalty: number;
+
+ /** Frequency penalty used */
+ frequency_penalty: number;
+
+ /** Top logprobs - number of most likely tokens to return */
+ top_logprobs: number;
+
+ /** Reasoning configuration - null if none */
+ reasoning: ReasoningConfig | null;
+
+ /** User identifier - null if none */
+ user: string | null;
+
+ /** Token usage - null if not available */
+ usage: Usage | null;
+
+ /** Max output tokens - null if not set */
+ max_output_tokens: number | null;
+
+ /** Max tool calls - null if not set */
+ max_tool_calls: number | null;
+
+ /** Whether response was stored */
+ store: boolean;
+
+ /** Whether request was run in background */
+ background: boolean;
+
+ /** Service tier used */
+ service_tier: string;
+
+ /** Metadata */
+ metadata: Metadata;
+
+ /** Safety identifier - null if none */
+ safety_identifier: string | null;
+
+ /** Prompt cache key - null if none */
+ prompt_cache_key: string | null;
+}
+
+/* =============================================================================
+ * STREAMING EVENTS
+ * ============================================================================= */
+
+/** Base event structure */
+export interface BaseEvent {
+ type: string;
+ sequence_number: number;
+}
+
+/** Response created event (first event in stream) */
+export interface ResponseCreatedEvent extends BaseEvent {
+ type: 'response.created';
+ response: Response;
+}
+
+/** Response in_progress event */
+export interface ResponseInProgressEvent extends BaseEvent {
+ type: 'response.in_progress';
+ response: Response;
+}
+
+/** Response completed event */
+export interface ResponseCompletedEvent extends BaseEvent {
+ type: 'response.completed';
+ response: Response;
+}
+
+/** Response failed event */
+export interface ResponseFailedEvent extends BaseEvent {
+ type: 'response.failed';
+ response: Response;
+}
+
+/** Response incomplete event */
+export interface ResponseIncompleteEvent extends BaseEvent {
+ type: 'response.incomplete';
+ response: Response;
+}
+
+/** Output item added event */
+export interface OutputItemAddedEvent extends BaseEvent {
+ type: 'response.output_item.added';
+ output_index: number;
+ item: OutputItem;
+}
+
+/** Output item done event */
+export interface OutputItemDoneEvent extends BaseEvent {
+ type: 'response.output_item.done';
+ output_index: number;
+ item: OutputItem;
+}
+
+/** Content part added event */
+export interface ContentPartAddedEvent extends BaseEvent {
+ type: 'response.content_part.added';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ part: ModelContent | ReasoningContent;
+}
+
+/** Content part done event */
+export interface ContentPartDoneEvent extends BaseEvent {
+ type: 'response.content_part.done';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ part: ModelContent | ReasoningContent;
+}
+
+/** Output text delta event */
+export interface OutputTextDeltaEvent extends BaseEvent {
+ type: 'response.output_text.delta';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ delta: string;
+ logprobs: LogProb[];
+}
+
+/** Output text done event */
+export interface OutputTextDoneEvent extends BaseEvent {
+ type: 'response.output_text.done';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ text: string;
+ logprobs: LogProb[];
+}
+
+/** Refusal delta event */
+export interface RefusalDeltaEvent extends BaseEvent {
+ type: 'response.refusal.delta';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ delta: string;
+}
+
+/** Refusal done event */
+export interface RefusalDoneEvent extends BaseEvent {
+ type: 'response.refusal.done';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ refusal: string;
+}
+
+/** Function call arguments delta event */
+export interface FunctionCallArgumentsDeltaEvent extends BaseEvent {
+ type: 'response.function_call_arguments.delta';
+ item_id: string;
+ output_index: number;
+ call_id: string;
+ delta: string;
+}
+
+/** Function call arguments done event */
+export interface FunctionCallArgumentsDoneEvent extends BaseEvent {
+ type: 'response.function_call_arguments.done';
+ item_id: string;
+ output_index: number;
+ call_id: string;
+ arguments: string;
+}
+
+/** Reasoning delta event */
+export interface ReasoningDeltaEvent extends BaseEvent {
+ type: 'response.reasoning.delta';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ delta: string;
+}
+
+/** Reasoning done event */
+export interface ReasoningDoneEvent extends BaseEvent {
+ type: 'response.reasoning.done';
+ item_id: string;
+ output_index: number;
+ content_index: number;
+ text: string;
+}
+
+/** Error event */
+export interface ErrorEvent extends BaseEvent {
+ type: 'error';
+ error: ResponseError;
+}
+
+/* =============================================================================
+ * LIBRECHAT EXTENSION TYPES
+ * Per Open Responses spec, custom types MUST be prefixed with implementor slug
+ * @see https://openresponses.org/specification#extending-streaming-events
+ * ============================================================================= */
+
+/** Attachment content types for LibreChat extensions */
+export interface LibreChatAttachmentContent {
+ /** File ID in LibreChat storage */
+ file_id?: string;
+ /** Original filename */
+ filename?: string;
+ /** MIME type */
+ type?: string;
+ /** URL to access the file */
+ url?: string;
+ /** Base64-encoded image data (for inline images) */
+ image_url?: string;
+ /** Width for images */
+ width?: number;
+ /** Height for images */
+ height?: number;
+ /** Associated tool call ID */
+ tool_call_id?: string;
+ /** Additional metadata */
+ [key: string]: unknown;
+}
+
+/**
+ * LibreChat attachment event - custom streaming event for file/image attachments
+ * Follows Open Responses extension pattern with librechat: prefix
+ */
+export interface LibreChatAttachmentEvent extends BaseEvent {
+ type: 'librechat:attachment';
+ /** The attachment data */
+ attachment: LibreChatAttachmentContent;
+ /** Associated message ID */
+ message_id?: string;
+ /** Associated conversation ID */
+ conversation_id?: string;
+}
+
+/** Union of all streaming events (including LibreChat extensions) */
+export type ResponseEvent =
+ | ResponseCreatedEvent
+ | ResponseInProgressEvent
+ | ResponseCompletedEvent
+ | ResponseFailedEvent
+ | ResponseIncompleteEvent
+ | OutputItemAddedEvent
+ | OutputItemDoneEvent
+ | ContentPartAddedEvent
+ | ContentPartDoneEvent
+ | OutputTextDeltaEvent
+ | OutputTextDoneEvent
+ | RefusalDeltaEvent
+ | RefusalDoneEvent
+ | FunctionCallArgumentsDeltaEvent
+ | FunctionCallArgumentsDoneEvent
+ | ReasoningDeltaEvent
+ | ReasoningDoneEvent
+ | ErrorEvent
+ // LibreChat extensions (prefixed per Open Responses spec)
+ | LibreChatAttachmentEvent;
+
+/* =============================================================================
+ * INTERNAL TYPES
+ * ============================================================================= */
+
+/** Context for building responses */
+export interface ResponseContext {
+ /** Response ID */
+ responseId: string;
+ /** Model/agent ID */
+ model: string;
+ /** Creation timestamp */
+ createdAt: number;
+ /** Previous response ID */
+ previousResponseId?: string;
+ /** Instructions */
+ instructions?: string;
+}
+
+/** Validation result for requests */
+export interface RequestValidationResult {
+ valid: boolean;
+ request?: ResponseRequest;
+ error?: string;
+}
diff --git a/packages/api/src/apiKeys/handlers.ts b/packages/api/src/apiKeys/handlers.ts
new file mode 100644
index 0000000000..61d23ccde9
--- /dev/null
+++ b/packages/api/src/apiKeys/handlers.ts
@@ -0,0 +1,129 @@
+import type { Request, Response } from 'express';
+import type { Types } from 'mongoose';
+import { logger } from '@librechat/data-schemas';
+
+export interface ApiKeyHandlerDependencies {
+ createAgentApiKey: (params: {
+ userId: string | Types.ObjectId;
+ name: string;
+ expiresAt?: Date | null;
+ }) => Promise<{
+ id: string;
+ name: string;
+ key: string;
+ keyPrefix: string;
+ createdAt: Date;
+ expiresAt?: Date;
+ }>;
+ listAgentApiKeys: (userId: string | Types.ObjectId) => Promise<
+ Array<{
+ id: string;
+ name: string;
+ keyPrefix: string;
+ lastUsedAt?: Date;
+ expiresAt?: Date;
+ createdAt: Date;
+ }>
+ >;
+ deleteAgentApiKey: (
+ keyId: string | Types.ObjectId,
+ userId: string | Types.ObjectId,
+ ) => Promise<boolean>;
+ getAgentApiKeyById: (
+ keyId: string | Types.ObjectId,
+ userId: string | Types.ObjectId,
+ ) => Promise<{
+ id: string;
+ name: string;
+ keyPrefix: string;
+ lastUsedAt?: Date;
+ expiresAt?: Date;
+ createdAt: Date;
+ } | null>;
+}
+
+interface AuthenticatedRequest extends Request {
+ user?: {
+ id: string;
+ _id: Types.ObjectId;
+ };
+}
+
+export function createApiKeyHandlers(deps: ApiKeyHandlerDependencies) {
+ async function createApiKey(req: AuthenticatedRequest, res: Response) {
+ try {
+ const { name, expiresAt } = req.body;
+
+ if (!name || typeof name !== 'string' || name.trim() === '') {
+ return res.status(400).json({
+ error: 'API key name is required',
+ });
+ }
+
+ const result = await deps.createAgentApiKey({
+ userId: req.user?.id || '',
+ name: name.trim(),
+ expiresAt: expiresAt ? new Date(expiresAt) : null,
+ });
+
+ res.status(201).json({
+ id: result.id,
+ name: result.name,
+ key: result.key,
+ keyPrefix: result.keyPrefix,
+ createdAt: result.createdAt,
+ expiresAt: result.expiresAt,
+ });
+ } catch (error) {
+ logger.error('[createApiKey] Error creating API key:', error);
+ res.status(500).json({ error: 'Failed to create API key' });
+ }
+ }
+
+ async function listApiKeys(req: AuthenticatedRequest, res: Response) {
+ try {
+ const keys = await deps.listAgentApiKeys(req.user?.id || '');
+ res.status(200).json({ keys });
+ } catch (error) {
+ logger.error('[listApiKeys] Error listing API keys:', error);
+ res.status(500).json({ error: 'Failed to list API keys' });
+ }
+ }
+
+ async function getApiKey(req: AuthenticatedRequest, res: Response) {
+ try {
+ const key = await deps.getAgentApiKeyById(req.params.id, req.user?.id || '');
+
+ if (!key) {
+ return res.status(404).json({ error: 'API key not found' });
+ }
+
+ res.status(200).json(key);
+ } catch (error) {
+ logger.error('[getApiKey] Error getting API key:', error);
+ res.status(500).json({ error: 'Failed to get API key' });
+ }
+ }
+
+ async function deleteApiKey(req: AuthenticatedRequest, res: Response) {
+ try {
+ const deleted = await deps.deleteAgentApiKey(req.params.id, req.user?.id || '');
+
+ if (!deleted) {
+ return res.status(404).json({ error: 'API key not found' });
+ }
+
+ res.status(204).send();
+ } catch (error) {
+ logger.error('[deleteApiKey] Error deleting API key:', error);
+ res.status(500).json({ error: 'Failed to delete API key' });
+ }
+ }
+
+ return {
+ createApiKey,
+ listApiKeys,
+ getApiKey,
+ deleteApiKey,
+ };
+}
diff --git a/packages/api/src/apiKeys/index.ts b/packages/api/src/apiKeys/index.ts
new file mode 100644
index 0000000000..69fd7b5c1a
--- /dev/null
+++ b/packages/api/src/apiKeys/index.ts
@@ -0,0 +1,4 @@
+export * from './service';
+export * from './middleware';
+export * from './handlers';
+export * from './permissions';
diff --git a/packages/api/src/apiKeys/middleware.ts b/packages/api/src/apiKeys/middleware.ts
new file mode 100644
index 0000000000..2a50353648
--- /dev/null
+++ b/packages/api/src/apiKeys/middleware.ts
@@ -0,0 +1,163 @@
+import { logger } from '@librechat/data-schemas';
+import { ResourceType, PermissionBits, hasPermissions } from 'librechat-data-provider';
+import type { Request, Response, NextFunction } from 'express';
+import type { IUser } from '@librechat/data-schemas';
+import type { Types } from 'mongoose';
+import { getRemoteAgentPermissions } from './service';
+
+export interface ApiKeyAuthDependencies {
+ validateAgentApiKey: (apiKey: string) => Promise<{
+ userId: Types.ObjectId;
+ keyId: Types.ObjectId;
+ } | null>;
+ findUser: (query: { _id: string | Types.ObjectId }) => Promise<IUser | null>;
+}
+
+export interface RemoteAgentAccessDependencies {
+ getAgent: (query: {
+ id: string;
+ }) => Promise<{ _id: Types.ObjectId; [key: string]: unknown } | null>;
+ getEffectivePermissions: (params: {
+ userId: string;
+ role?: string;
+ resourceType: ResourceType;
+ resourceId: string | Types.ObjectId;
+ }) => Promise<number>;
+}
+
+export interface ApiKeyAuthRequest extends Request {
+ user?: IUser & { id: string };
+ apiKeyId?: Types.ObjectId;
+}
+
+export interface RemoteAgentAccessRequest extends ApiKeyAuthRequest {
+ agent?: { _id: Types.ObjectId; [key: string]: unknown };
+ agentPermissions?: number;
+}
+
+export function createRequireApiKeyAuth(deps: ApiKeyAuthDependencies) {
+ return async (req: ApiKeyAuthRequest, res: Response, next: NextFunction) => {
+ const authHeader = req.headers.authorization;
+
+ if (!authHeader || !authHeader.startsWith('Bearer ')) {
+ return res.status(401).json({
+ error: {
+ message: 'Missing or invalid Authorization header. Expected: Bearer <api_key>',
+ type: 'invalid_request_error',
+ code: 'missing_api_key',
+ },
+ });
+ }
+
+ const apiKey = authHeader.slice(7);
+
+ if (!apiKey || apiKey.trim() === '') {
+ return res.status(401).json({
+ error: {
+ message: 'API key is required',
+ type: 'invalid_request_error',
+ code: 'missing_api_key',
+ },
+ });
+ }
+
+ try {
+ const keyValidation = await deps.validateAgentApiKey(apiKey);
+
+ if (!keyValidation) {
+ return res.status(401).json({
+ error: {
+ message: 'Invalid API key',
+ type: 'invalid_request_error',
+ code: 'invalid_api_key',
+ },
+ });
+ }
+
+ const user = await deps.findUser({ _id: keyValidation.userId });
+
+ if (!user) {
+ return res.status(401).json({
+ error: {
+ message: 'User not found for this API key',
+ type: 'invalid_request_error',
+ code: 'invalid_api_key',
+ },
+ });
+ }
+
+ user.id = (user._id as Types.ObjectId).toString();
+ req.user = user as IUser & { id: string };
+ req.apiKeyId = keyValidation.keyId;
+
+ next();
+ } catch (error) {
+ logger.error('[requireApiKeyAuth] Error validating API key:', error);
+ return res.status(500).json({
+ error: {
+ message: 'Internal server error during authentication',
+ type: 'server_error',
+ code: 'internal_error',
+ },
+ });
+ }
+ };
+}
+
+export function createCheckRemoteAgentAccess(deps: RemoteAgentAccessDependencies) {
+ return async (req: RemoteAgentAccessRequest, res: Response, next: NextFunction) => {
+ const agentId = req.body?.model || req.params?.model;
+
+ if (!agentId) {
+ return res.status(400).json({
+ error: {
+ message: 'Model (agent ID) is required',
+ type: 'invalid_request_error',
+ code: 'missing_model',
+ },
+ });
+ }
+
+ try {
+ const agent = await deps.getAgent({ id: agentId });
+
+ if (!agent) {
+ return res.status(404).json({
+ error: {
+ message: `Agent not found: ${agentId}`,
+ type: 'invalid_request_error',
+ code: 'model_not_found',
+ },
+ });
+ }
+
+ const userId = req.user?.id || '';
+
+ const permissions = await getRemoteAgentPermissions(deps, userId, req.user?.role, agent._id);
+
+ if (!hasPermissions(permissions, PermissionBits.VIEW)) {
+ return res.status(403).json({
+ error: {
+ message: `No remote access to agent: ${agentId}`,
+ type: 'permission_error',
+ code: 'access_denied',
+ },
+ });
+ }
+
+ req.agent = agent;
+ req.agentPermissions = permissions;
+
+ next();
+ } catch (error) {
+ logger.error('[checkRemoteAgentAccess] Error checking agent access:', error);
+ return res.status(500).json({
+ error: {
+ message: 'Internal server error while checking agent access',
+ type: 'server_error',
+ code: 'internal_error',
+ },
+ });
+ }
+ };
+}
diff --git a/packages/api/src/apiKeys/permissions.ts b/packages/api/src/apiKeys/permissions.ts
new file mode 100644
index 0000000000..2556f25b57
--- /dev/null
+++ b/packages/api/src/apiKeys/permissions.ts
@@ -0,0 +1,169 @@
+import {
+ ResourceType,
+ PrincipalType,
+ PermissionBits,
+ AccessRoleIds,
+} from 'librechat-data-provider';
+import type { Types, Model } from 'mongoose';
+
+export interface Principal {
+ type: string;
+ id: string;
+ name: string;
+ email?: string;
+ avatar?: string;
+ source?: string;
+ idOnTheSource?: string;
+ accessRoleId: string;
+ isImplicit?: boolean;
+}
+
+export interface EnricherDependencies {
+ AclEntry: Model<{
+ principalType: string;
+ principalId: Types.ObjectId;
+ resourceType: string;
+ resourceId: Types.ObjectId;
+ permBits: number;
+ roleId: Types.ObjectId;
+ grantedBy: Types.ObjectId;
+ grantedAt: Date;
+ }>;
+ AccessRole: Model<{
+ accessRoleId: string;
+ permBits: number;
+ }>;
+ logger: { error: (msg: string, ...args: unknown[]) => void };
+}
+
+export interface EnrichResult {
+ principals: Principal[];
+ entriesToBackfill: Types.ObjectId[];
+}
+
+/** Enriches REMOTE_AGENT principals with implicit AGENT owners */
+export async function enrichRemoteAgentPrincipals(
+ deps: EnricherDependencies,
+ resourceId: string | Types.ObjectId,
+ principals: Principal[],
+): Promise<EnrichResult> {
+ const { AclEntry } = deps;
+
+ const resourceObjectId =
+ typeof resourceId === 'string' && /^[a-f\d]{24}$/i.test(resourceId)
+ ? deps.AclEntry.base.Types.ObjectId.createFromHexString(resourceId)
+ : resourceId;
+
+ const agentOwnerEntries = await AclEntry.aggregate([
+ {
+ $match: {
+ resourceType: ResourceType.AGENT,
+ resourceId: resourceObjectId,
+ principalType: PrincipalType.USER,
+ permBits: { $bitsAllSet: PermissionBits.SHARE },
+ },
+ },
+ {
+ $lookup: {
+ from: 'users',
+ localField: 'principalId',
+ foreignField: '_id',
+ as: 'userInfo',
+ },
+ },
+ {
+ $project: {
+ principalId: 1,
+ userInfo: { $arrayElemAt: ['$userInfo', 0] },
+ },
+ },
+ ]);
+
+ const enrichedPrincipals = [...principals];
+ const entriesToBackfill: Types.ObjectId[] = [];
+
+ for (const entry of agentOwnerEntries) {
+ if (!entry.userInfo) {
+ continue;
+ }
+
+ const alreadyIncluded = enrichedPrincipals.some(
+ (p) => p.type === PrincipalType.USER && p.id === entry.principalId.toString(),
+ );
+
+ if (!alreadyIncluded) {
+ enrichedPrincipals.unshift({
+ type: PrincipalType.USER,
+ id: entry.userInfo._id.toString(),
+ name: entry.userInfo.name || entry.userInfo.username,
+ email: entry.userInfo.email,
+ avatar: entry.userInfo.avatar,
+ source: 'local',
+ idOnTheSource: entry.userInfo.idOnTheSource || entry.userInfo._id.toString(),
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ isImplicit: true,
+ });
+
+ entriesToBackfill.push(entry.principalId);
+ }
+ }
+
+ return { principals: enrichedPrincipals, entriesToBackfill };
+}
+
+/** Backfills REMOTE_AGENT ACL entries for AGENT owners (fire-and-forget) */
+export function backfillRemoteAgentPermissions(
+ deps: EnricherDependencies,
+ resourceId: string | Types.ObjectId,
+ entriesToBackfill: Types.ObjectId[],
+): void {
+ if (entriesToBackfill.length === 0) {
+ return;
+ }
+
+ const { AclEntry, AccessRole, logger } = deps;
+
+ const resourceObjectId =
+ typeof resourceId === 'string' && /^[a-f\d]{24}$/i.test(resourceId)
+ ? AclEntry.base.Types.ObjectId.createFromHexString(resourceId)
+ : resourceId;
+
+ AccessRole.findOne({ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER })
+ .lean()
+ .then((role) => {
+ if (!role) {
+ logger.error('[backfillRemoteAgentPermissions] REMOTE_AGENT_OWNER role not found');
+ return;
+ }
+
+ const bulkOps = entriesToBackfill.map((principalId) => ({
+ updateOne: {
+ filter: {
+ principalType: PrincipalType.USER,
+ principalId,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: resourceObjectId,
+ },
+ update: {
+ $setOnInsert: {
+ principalType: PrincipalType.USER,
+ principalId,
+ principalModel: 'User',
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId: resourceObjectId,
+ permBits: role.permBits,
+ roleId: role._id,
+ grantedBy: principalId,
+ grantedAt: new Date(),
+ },
+ },
+ upsert: true,
+ },
+ }));
+
+ return AclEntry.bulkWrite(bulkOps, { ordered: false });
+ })
+ .catch((err) => {
+ logger.error('[backfillRemoteAgentPermissions] Failed to backfill:', err);
+ });
+}
diff --git a/packages/api/src/apiKeys/service.ts b/packages/api/src/apiKeys/service.ts
new file mode 100644
index 0000000000..30ae0afb53
--- /dev/null
+++ b/packages/api/src/apiKeys/service.ts
@@ -0,0 +1,146 @@
+import { createMethods } from '@librechat/data-schemas';
+import { ResourceType, PermissionBits, hasPermissions } from 'librechat-data-provider';
+import type { AllMethods, IUser } from '@librechat/data-schemas';
+import type { Types } from 'mongoose';
+
+export interface ApiKeyServiceDependencies {
+ validateAgentApiKey: AllMethods['validateAgentApiKey'];
+ createAgentApiKey: AllMethods['createAgentApiKey'];
+ listAgentApiKeys: AllMethods['listAgentApiKeys'];
+ deleteAgentApiKey: AllMethods['deleteAgentApiKey'];
+ getAgentApiKeyById: AllMethods['getAgentApiKeyById'];
+ findUser: (query: { _id: string | Types.ObjectId }) => Promise<IUser | null>;
+}
+
+export interface RemoteAgentAccessResult {
+ hasAccess: boolean;
+ permissions: number;
+ agent: { _id: Types.ObjectId; [key: string]: unknown } | null;
+}
+
+export class AgentApiKeyService {
+ private deps: ApiKeyServiceDependencies;
+
+ constructor(deps: ApiKeyServiceDependencies) {
+ this.deps = deps;
+ }
+
+ async validateApiKey(apiKey: string): Promise<{
+ userId: Types.ObjectId;
+ keyId: Types.ObjectId;
+ } | null> {
+ return this.deps.validateAgentApiKey(apiKey);
+ }
+
+ async createApiKey(params: {
+ userId: string | Types.ObjectId;
+ name: string;
+ expiresAt?: Date | null;
+ }) {
+ return this.deps.createAgentApiKey(params);
+ }
+
+ async listApiKeys(userId: string | Types.ObjectId) {
+ return this.deps.listAgentApiKeys(userId);
+ }
+
+ async deleteApiKey(keyId: string | Types.ObjectId, userId: string | Types.ObjectId) {
+ return this.deps.deleteAgentApiKey(keyId, userId);
+ }
+
+ async getApiKeyById(keyId: string | Types.ObjectId, userId: string | Types.ObjectId) {
+ return this.deps.getAgentApiKeyById(keyId, userId);
+ }
+
+ async getUserFromApiKey(apiKey: string): Promise<IUser | null> {
+ const keyValidation = await this.validateApiKey(apiKey);
+ if (!keyValidation) {
+ return null;
+ }
+
+ return this.deps.findUser({ _id: keyValidation.userId });
+ }
+}
+
+export function createApiKeyServiceDependencies(
+ mongoose: typeof import('mongoose'),
+): ApiKeyServiceDependencies {
+ const methods = createMethods(mongoose);
+ return {
+ validateAgentApiKey: methods.validateAgentApiKey,
+ createAgentApiKey: methods.createAgentApiKey,
+ listAgentApiKeys: methods.listAgentApiKeys,
+ deleteAgentApiKey: methods.deleteAgentApiKey,
+ getAgentApiKeyById: methods.getAgentApiKeyById,
+ findUser: methods.findUser,
+ };
+}
+
+export interface GetRemoteAgentPermissionsDeps {
+ getEffectivePermissions: (params: {
+ userId: string;
+ role?: string;
+ resourceType: ResourceType;
+ resourceId: string | Types.ObjectId;
+ }) => Promise<number>;
+}
+
+/** AGENT owners automatically have full REMOTE_AGENT permissions */
+export async function getRemoteAgentPermissions(
+ deps: GetRemoteAgentPermissionsDeps,
+ userId: string,
+ role: string | undefined,
+ resourceId: string | Types.ObjectId,
+): Promise<number> {
+ const agentPerms = await deps.getEffectivePermissions({
+ userId,
+ role,
+ resourceType: ResourceType.AGENT,
+ resourceId,
+ });
+
+ if (hasPermissions(agentPerms, PermissionBits.SHARE)) {
+ return PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE;
+ }
+
+ return deps.getEffectivePermissions({
+ userId,
+ role,
+ resourceType: ResourceType.REMOTE_AGENT,
+ resourceId,
+ });
+}
+
+export async function checkRemoteAgentAccess(params: {
+ userId: string;
+ role?: string;
+ agentId: string;
+ getAgent: (query: {
+ id: string;
+ }) => Promise<{ _id: Types.ObjectId; [key: string]: unknown } | null>;
+ getEffectivePermissions: (params: {
+ userId: string;
+ role?: string;
+ resourceType: ResourceType;
+ resourceId: string | Types.ObjectId;
+ }) => Promise<number>;
+}): Promise<RemoteAgentAccessResult> {
+ const { userId, role, agentId, getAgent, getEffectivePermissions } = params;
+
+ const agent = await getAgent({ id: agentId });
+
+ if (!agent) {
+ return { hasAccess: false, permissions: 0, agent: null };
+ }
+
+ const permissions = await getRemoteAgentPermissions(
+ { getEffectivePermissions },
+ userId,
+ role,
+ agent._id,
+ );
+
+ const hasAccess = hasPermissions(permissions, PermissionBits.VIEW);
+
+ return { hasAccess, permissions, agent };
+}
diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.ts
index b84ad63498..a787c0c3a3 100644
--- a/packages/api/src/app/permissions.spec.ts
+++ b/packages/api/src/app/permissions.spec.ts
@@ -100,6 +100,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -141,6 +147,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -246,6 +258,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -287,6 +305,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -378,6 +402,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -419,6 +449,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -523,6 +559,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -564,6 +606,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -655,6 +703,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -696,6 +750,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -784,6 +844,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -813,6 +879,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
@@ -920,6 +992,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: false,
[Permissions.SHARE_PUBLIC]: false,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: false,
+ [Permissions.CREATE]: false,
+ [Permissions.SHARE]: false,
+ [Permissions.SHARE_PUBLIC]: false,
+ },
};
const expectedPermissionsForAdmin = {
@@ -955,6 +1033,12 @@ describe('updateInterfacePermissions - permissions', () => {
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
};
expect(mockUpdateAccessPermissions).toHaveBeenCalledTimes(2);
diff --git a/packages/api/src/app/permissions.ts b/packages/api/src/app/permissions.ts
index bfa49e6bbd..8f97236823 100644
--- a/packages/api/src/app/permissions.ts
+++ b/packages/api/src/app/permissions.ts
@@ -43,6 +43,8 @@ function hasExplicitConfig(
return interfaceConfig?.fileCitations !== undefined;
case PermissionTypes.MCP_SERVERS:
return interfaceConfig?.mcpServers !== undefined;
+ case PermissionTypes.REMOTE_AGENTS:
+ return interfaceConfig?.remoteAgents !== undefined;
default:
return false;
}
@@ -101,7 +103,9 @@ export async function updateInterfacePermissions({
const defaultPerms = roleDefaults[roleName]?.permissions;
const existingRole = await getRoleByName(roleName);
- const existingPermissions = existingRole?.permissions;
+ const existingPermissions = existingRole?.permissions as
+ | Partial<Record<PermissionTypes, Record<string, boolean | undefined>>>
+ | undefined;
const permissionsToUpdate: Partial<
Record<PermissionTypes, Record<string, boolean | undefined>>
> = {};
@@ -335,6 +339,28 @@ export async function updateInterfacePermissions({
defaults.mcpServers?.public,
),
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: getPermissionValue(
+ loadedInterface.remoteAgents?.use,
+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.USE],
+ defaults.remoteAgents?.use,
+ ),
+ [Permissions.CREATE]: getPermissionValue(
+ loadedInterface.remoteAgents?.create,
+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.CREATE],
+ defaults.remoteAgents?.create,
+ ),
+ [Permissions.SHARE]: getPermissionValue(
+ loadedInterface.remoteAgents?.share,
+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.SHARE],
+ defaults.remoteAgents?.share,
+ ),
+ [Permissions.SHARE_PUBLIC]: getPermissionValue(
+ loadedInterface.remoteAgents?.public,
+ defaultPerms[PermissionTypes.REMOTE_AGENTS]?.[Permissions.SHARE_PUBLIC],
+ defaults.remoteAgents?.public,
+ ),
+ },
};
// Check and add each permission type if needed
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index 492b59f232..fefdafaefd 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -2,6 +2,8 @@ export * from './app';
export * from './cdn';
/* Auth */
export * from './auth';
+/* API Keys */
+export * from './apiKeys';
/* MCP */
export * from './mcp/registry/MCPServersRegistry';
export * from './mcp/MCPManager';
diff --git a/packages/data-provider/src/accessPermissions.ts b/packages/data-provider/src/accessPermissions.ts
index 5fa288e4b3..f2431fcf9a 100644
--- a/packages/data-provider/src/accessPermissions.ts
+++ b/packages/data-provider/src/accessPermissions.ts
@@ -46,6 +46,7 @@ export enum ResourceType {
AGENT = 'agent',
PROMPTGROUP = 'promptGroup',
MCPSERVER = 'mcpServer',
+ REMOTE_AGENT = 'remoteAgent',
}
/**
@@ -75,6 +76,9 @@ export enum AccessRoleIds {
MCPSERVER_VIEWER = 'mcpServer_viewer',
MCPSERVER_EDITOR = 'mcpServer_editor',
MCPSERVER_OWNER = 'mcpServer_owner',
+ REMOTE_AGENT_VIEWER = 'remoteAgent_viewer',
+ REMOTE_AGENT_EDITOR = 'remoteAgent_editor',
+ REMOTE_AGENT_OWNER = 'remoteAgent_owner',
}
// ===== ZOD SCHEMAS =====
@@ -310,11 +314,22 @@ export function permBitsToAccessLevel(permBits: number): TAccessLevel {
export function accessRoleToPermBits(accessRoleId: string): number {
switch (accessRoleId) {
case AccessRoleIds.AGENT_VIEWER:
+ case AccessRoleIds.PROMPTGROUP_VIEWER:
+ case AccessRoleIds.MCPSERVER_VIEWER:
+ case AccessRoleIds.REMOTE_AGENT_VIEWER:
return PermissionBits.VIEW;
case AccessRoleIds.AGENT_EDITOR:
+ case AccessRoleIds.PROMPTGROUP_EDITOR:
+ case AccessRoleIds.MCPSERVER_EDITOR:
+ case AccessRoleIds.REMOTE_AGENT_EDITOR:
return PermissionBits.VIEW | PermissionBits.EDIT;
case AccessRoleIds.AGENT_OWNER:
- return PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE;
+ case AccessRoleIds.PROMPTGROUP_OWNER:
+ case AccessRoleIds.MCPSERVER_OWNER:
+ case AccessRoleIds.REMOTE_AGENT_OWNER:
+ return (
+ PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE
+ );
default:
return PermissionBits.VIEW;
}
diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.ts
index ef7e0d6cfb..d49535b094 100644
--- a/packages/data-provider/src/api-endpoints.ts
+++ b/packages/data-provider/src/api-endpoints.ts
@@ -95,6 +95,12 @@ export const revokeUserKey = (name: string) => `${keysEndpoint}/${name}`;
export const revokeAllUserKeys = () => `${keysEndpoint}?all=true`;
+const apiKeysEndpoint = `${BASE_URL}/api/api-keys`;
+
+export const apiKeys = () => apiKeysEndpoint;
+
+export const apiKeyById = (id: string) => `${apiKeysEndpoint}/${id}`;
+
export const conversationsRoot = `${BASE_URL}/api/convos`;
export const conversations = (params: q.ConversationListParams) => {
@@ -329,6 +335,8 @@ export const updateAgentPermissions = (roleName: string) => `${getRole(roleName)
export const updatePeoplePickerPermissions = (roleName: string) =>
`${getRole(roleName)}/people-picker`;
export const updateMCPServersPermissions = (roleName: string) => `${getRole(roleName)}/mcp-servers`;
+export const updateRemoteAgentsPermissions = (roleName: string) =>
+ `${getRole(roleName)}/remote-agents`;
export const updateMarketplacePermissions = (roleName: string) =>
`${getRole(roleName)}/marketplace`;
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 4eb143f414..c609de0e41 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -660,6 +660,14 @@ export const interfaceSchema = z
.optional(),
fileSearch: z.boolean().optional(),
fileCitations: z.boolean().optional(),
+ remoteAgents: z
+ .object({
+ use: z.boolean().optional(),
+ create: z.boolean().optional(),
+ share: z.boolean().optional(),
+ public: z.boolean().optional(),
+ })
+ .optional(),
})
.default({
endpointsMenu: true,
@@ -699,6 +707,12 @@ export const interfaceSchema = z
},
fileSearch: true,
fileCitations: true,
+ remoteAgents: {
+ use: false,
+ create: false,
+ share: false,
+ public: false,
+ },
});
export type TInterfaceConfig = z.infer<typeof interfaceSchema>;
diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.ts
index 911cc7863c..8919e2589b 100644
--- a/packages/data-provider/src/data-service.ts
+++ b/packages/data-provider/src/data-service.ts
@@ -81,6 +81,20 @@ export function updateUserKey(payload: t.TUpdateUserKeyRequest) {
return request.put(endpoints.keys(), payload);
}
+export function getAgentApiKeys(): Promise<t.TAgentApiKeyListResponse> {
+ return request.get(endpoints.apiKeys());
+}
+
+export function createAgentApiKey(
+ payload: t.TAgentApiKeyCreateRequest,
+): Promise<t.TAgentApiKeyCreateResponse> {
+ return request.post(endpoints.apiKeys(), payload);
+}
+
+export function deleteAgentApiKey(id: string): Promise<void> {
+ return request.delete(endpoints.apiKeyById(id));
+}
+
export function getPresets(): Promise<s.TPreset[]> {
return request.get(endpoints.presets());
}
@@ -877,6 +891,15 @@ export function updateMCPServersPermissions(
return request.put(endpoints.updateMCPServersPermissions(variables.roleName), variables.updates);
}
+export function updateRemoteAgentsPermissions(
+ variables: m.UpdateRemoteAgentsPermVars,
+): Promise<m.UpdatePermResponse> {
+ return request.put(
+ endpoints.updateRemoteAgentsPermissions(variables.roleName),
+ variables.updates,
+ );
+}
+
export function updateMarketplacePermissions(
variables: m.UpdateMarketplacePermVars,
): Promise<m.UpdatePermResponse> {
diff --git a/packages/data-provider/src/keys.ts b/packages/data-provider/src/keys.ts
index 235baf4ebe..a5e67878ed 100644
--- a/packages/data-provider/src/keys.ts
+++ b/packages/data-provider/src/keys.ts
@@ -62,6 +62,8 @@ export enum QueryKeys {
mcpServer = 'mcpServer',
/* Active Jobs */
activeJobs = 'activeJobs',
+ /* Agent API Keys */
+ agentApiKeys = 'agentApiKeys',
}
// Dynamic query keys that require parameters
@@ -70,6 +72,8 @@ export const DynamicQueryKeys = {
} as const;
export enum MutationKeys {
+ createAgentApiKey = 'createAgentApiKey',
+ deleteAgentApiKey = 'deleteAgentApiKey',
fileUpload = 'fileUpload',
fileDelete = 'fileDelete',
updatePreset = 'updatePreset',
diff --git a/packages/data-provider/src/permissions.ts b/packages/data-provider/src/permissions.ts
index 0d53dbe29b..7a3144c82d 100644
--- a/packages/data-provider/src/permissions.ts
+++ b/packages/data-provider/src/permissions.ts
@@ -56,6 +56,10 @@ export enum PermissionTypes {
* Type for MCP Server Permissions
*/
MCP_SERVERS = 'MCP_SERVERS',
+ /**
+ * Type for Remote Agent (API) Permissions
+ */
+ REMOTE_AGENTS = 'REMOTE_AGENTS',
}
/**
@@ -157,6 +161,14 @@ export const mcpServersPermissionsSchema = z.object({
});
export type TMcpServersPermissions = z.infer<typeof mcpServersPermissionsSchema>;
+export const remoteAgentsPermissionsSchema = z.object({
+ [Permissions.USE]: z.boolean().default(false),
+ [Permissions.CREATE]: z.boolean().default(false),
+ [Permissions.SHARE]: z.boolean().default(false),
+ [Permissions.SHARE_PUBLIC]: z.boolean().default(false),
+});
+export type TRemoteAgentsPermissions = z.infer<typeof remoteAgentsPermissionsSchema>;
+
// Define a single permissions schema that holds all permission types.
export const permissionsSchema = z.object({
[PermissionTypes.PROMPTS]: promptPermissionsSchema,
@@ -172,4 +184,5 @@ export const permissionsSchema = z.object({
[PermissionTypes.FILE_SEARCH]: fileSearchPermissionsSchema,
[PermissionTypes.FILE_CITATIONS]: fileCitationsPermissionsSchema,
[PermissionTypes.MCP_SERVERS]: mcpServersPermissionsSchema,
+ [PermissionTypes.REMOTE_AGENTS]: remoteAgentsPermissionsSchema,
});
diff --git a/packages/data-provider/src/react-query/react-query-service.ts b/packages/data-provider/src/react-query/react-query-service.ts
index cd259fb50c..9d08d9d56a 100644
--- a/packages/data-provider/src/react-query/react-query-service.ts
+++ b/packages/data-provider/src/react-query/react-query-service.ts
@@ -524,3 +524,43 @@ export const useMCPServerConnectionStatusQuery = (
},
);
};
+
+export const useGetAgentApiKeysQuery = (
+ config?: UseQueryOptions<t.TAgentApiKeyListResponse>,
+): QueryObserverResult<t.TAgentApiKeyListResponse> => {
+ return useQuery<t.TAgentApiKeyListResponse>(
+ [QueryKeys.agentApiKeys],
+ () => dataService.getAgentApiKeys(),
+ {
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ ...config,
+ },
+ );
+};
+
+export const useCreateAgentApiKeyMutation = (): UseMutationResult<
+ t.TAgentApiKeyCreateResponse,
+ unknown,
+ t.TAgentApiKeyCreateRequest
+> => {
+ const queryClient = useQueryClient();
+ return useMutation(
+ (payload: t.TAgentApiKeyCreateRequest) => dataService.createAgentApiKey(payload),
+ {
+ onSuccess: () => {
+ queryClient.invalidateQueries([QueryKeys.agentApiKeys]);
+ },
+ },
+ );
+};
+
+export const useDeleteAgentApiKeyMutation = (): UseMutationResult<void, unknown, string> => {
+ const queryClient = useQueryClient();
+ return useMutation((id: string) => dataService.deleteAgentApiKey(id), {
+ onSuccess: () => {
+ queryClient.invalidateQueries([QueryKeys.agentApiKeys]);
+ },
+ });
+};
diff --git a/packages/data-provider/src/roles.ts b/packages/data-provider/src/roles.ts
index b3d44a49d9..b494ee5817 100644
--- a/packages/data-provider/src/roles.ts
+++ b/packages/data-provider/src/roles.ts
@@ -11,10 +11,11 @@ import {
webSearchPermissionsSchema,
fileSearchPermissionsSchema,
multiConvoPermissionsSchema,
- temporaryChatPermissionsSchema,
+ mcpServersPermissionsSchema,
peoplePickerPermissionsSchema,
+ remoteAgentsPermissionsSchema,
+ temporaryChatPermissionsSchema,
fileCitationsPermissionsSchema,
- mcpServersPermissionsSchema,
} from './permissions';
/**
@@ -96,6 +97,12 @@ const defaultRolesSchema = z.object({
[Permissions.SHARE]: z.boolean().default(true),
[Permissions.SHARE_PUBLIC]: z.boolean().default(true),
}),
+ [PermissionTypes.REMOTE_AGENTS]: remoteAgentsPermissionsSchema.extend({
+ [Permissions.USE]: z.boolean().default(true),
+ [Permissions.CREATE]: z.boolean().default(true),
+ [Permissions.SHARE]: z.boolean().default(true),
+ [Permissions.SHARE_PUBLIC]: z.boolean().default(true),
+ }),
}),
}),
[SystemRoles.USER]: roleSchema.extend({
@@ -162,6 +169,12 @@ export const roleDefaults = defaultRolesSchema.parse({
[Permissions.SHARE]: true,
[Permissions.SHARE_PUBLIC]: true,
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: true,
+ [Permissions.CREATE]: true,
+ [Permissions.SHARE]: true,
+ [Permissions.SHARE_PUBLIC]: true,
+ },
},
},
[SystemRoles.USER]: {
@@ -186,6 +199,7 @@ export const roleDefaults = defaultRolesSchema.parse({
[PermissionTypes.FILE_SEARCH]: {},
[PermissionTypes.FILE_CITATIONS]: {},
[PermissionTypes.MCP_SERVERS]: {},
+ [PermissionTypes.REMOTE_AGENTS]: {},
},
},
});
diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.ts
index d9050a07f0..2190b2cfe1 100644
--- a/packages/data-provider/src/types.ts
+++ b/packages/data-provider/src/types.ts
@@ -235,6 +235,33 @@ export type TUpdateUserKeyRequest = {
expiresAt: string;
};
+export type TAgentApiKeyCreateRequest = {
+ name: string;
+ expiresAt?: string | null;
+};
+
+export type TAgentApiKeyCreateResponse = {
+ id: string;
+ name: string;
+ key: string;
+ keyPrefix: string;
+ createdAt: string;
+ expiresAt?: string;
+};
+
+export type TAgentApiKeyListItem = {
+ id: string;
+ name: string;
+ keyPrefix: string;
+ lastUsedAt?: string;
+ expiresAt?: string;
+ createdAt: string;
+};
+
+export type TAgentApiKeyListResponse = {
+ keys: TAgentApiKeyListItem[];
+};
+
export type TUpdateConversationRequest = {
conversationId: string;
title: string;
diff --git a/packages/data-provider/src/types/mutations.ts b/packages/data-provider/src/types/mutations.ts
index 1a7211edfa..15f0cd2329 100644
--- a/packages/data-provider/src/types/mutations.ts
+++ b/packages/data-provider/src/types/mutations.ts
@@ -313,6 +313,15 @@ export type UpdateMCPServersPermOptions = MutationOptions<
types.TError | null | undefined
>;
+export type UpdateRemoteAgentsPermVars = UpdatePermVars<p.TRemoteAgentsPermissions>;
+
+export type UpdateRemoteAgentsPermOptions = MutationOptions<
+ UpdatePermResponse,
+ UpdateRemoteAgentsPermVars,
+ unknown,
+ types.TError | null | undefined
+>;
+
export type UpdateMarketplacePermVars = UpdatePermVars<p.TMarketplacePermissions>;
export type UpdateMarketplacePermOptions = MutationOptions<
diff --git a/packages/data-schemas/src/methods/accessRole.spec.ts b/packages/data-schemas/src/methods/accessRole.spec.ts
index b0f7ba70ef..6919e6c7df 100644
--- a/packages/data-schemas/src/methods/accessRole.spec.ts
+++ b/packages/data-schemas/src/methods/accessRole.spec.ts
@@ -203,6 +203,9 @@ describe('AccessRole Model Tests', () => {
AccessRoleIds.MCPSERVER_EDITOR,
AccessRoleIds.MCPSERVER_OWNER,
AccessRoleIds.MCPSERVER_VIEWER,
+ AccessRoleIds.REMOTE_AGENT_EDITOR,
+ AccessRoleIds.REMOTE_AGENT_OWNER,
+ AccessRoleIds.REMOTE_AGENT_VIEWER,
].sort(),
);
diff --git a/packages/data-schemas/src/methods/accessRole.ts b/packages/data-schemas/src/methods/accessRole.ts
index 0971c0f9e8..ab2cffbad8 100644
--- a/packages/data-schemas/src/methods/accessRole.ts
+++ b/packages/data-schemas/src/methods/accessRole.ts
@@ -167,6 +167,27 @@ export function createAccessRoleMethods(mongoose: typeof import('mongoose')) {
resourceType: ResourceType.MCPSERVER,
permBits: RoleBits.OWNER,
},
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_VIEWER,
+ name: 'com_ui_remote_agent_role_viewer',
+ description: 'com_ui_remote_agent_role_viewer_desc',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits: RoleBits.VIEWER,
+ },
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_EDITOR,
+ name: 'com_ui_remote_agent_role_editor',
+ description: 'com_ui_remote_agent_role_editor_desc',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits: RoleBits.EDITOR,
+ },
+ {
+ accessRoleId: AccessRoleIds.REMOTE_AGENT_OWNER,
+ name: 'com_ui_remote_agent_role_owner',
+ description: 'com_ui_remote_agent_role_owner_desc',
+ resourceType: ResourceType.REMOTE_AGENT,
+ permBits: RoleBits.OWNER,
+ },
];
const result: Record<string, IAccessRole> = {};
diff --git a/packages/data-schemas/src/methods/agentApiKey.ts b/packages/data-schemas/src/methods/agentApiKey.ts
new file mode 100644
index 0000000000..3462f9ff84
--- /dev/null
+++ b/packages/data-schemas/src/methods/agentApiKey.ts
@@ -0,0 +1,164 @@
+import type { Types } from 'mongoose';
+import type {
+ AgentApiKeyCreateResult,
+ AgentApiKeyCreateData,
+ AgentApiKeyListItem,
+ IAgentApiKey,
+} from '~/types';
+import { hashToken, getRandomValues } from '~/crypto';
+import logger from '~/config/winston';
+
+const API_KEY_PREFIX = 'sk-';
+const API_KEY_LENGTH = 32;
+
+export function createAgentApiKeyMethods(mongoose: typeof import('mongoose')) {
+ async function generateApiKey(): Promise<{ key: string; keyHash: string; keyPrefix: string }> {
+ const randomPart = await getRandomValues(API_KEY_LENGTH);
+ const key = `${API_KEY_PREFIX}${randomPart}`;
+ const keyHash = await hashToken(key);
+ const keyPrefix = key.slice(0, 8);
+ return { key, keyHash, keyPrefix };
+ }
+
+ async function createAgentApiKey(data: AgentApiKeyCreateData): Promise<AgentApiKeyCreateResult> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const { key, keyHash, keyPrefix } = await generateApiKey();
+
+ const apiKeyDoc = await AgentApiKey.create({
+ userId: data.userId,
+ name: data.name,
+ keyHash,
+ keyPrefix,
+ expiresAt: data.expiresAt || undefined,
+ });
+
+ return {
+ id: apiKeyDoc._id.toString(),
+ name: apiKeyDoc.name,
+ keyPrefix,
+ key,
+ createdAt: apiKeyDoc.createdAt,
+ expiresAt: apiKeyDoc.expiresAt,
+ };
+ } catch (error) {
+ logger.error('[createAgentApiKey] Error creating API key:', error);
+ throw error;
+ }
+ }
+
+ async function validateAgentApiKey(
+ apiKey: string,
+ ): Promise<{ userId: Types.ObjectId; keyId: Types.ObjectId } | null> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const keyHash = await hashToken(apiKey);
+
+ const keyDoc = (await AgentApiKey.findOne({ keyHash }).lean()) as IAgentApiKey | null;
+
+ if (!keyDoc) {
+ return null;
+ }
+
+ if (keyDoc.expiresAt && new Date(keyDoc.expiresAt) < new Date()) {
+ return null;
+ }
+
+ await AgentApiKey.updateOne({ _id: keyDoc._id }, { $set: { lastUsedAt: new Date() } });
+
+ return {
+ userId: keyDoc.userId,
+ keyId: keyDoc._id as Types.ObjectId,
+ };
+ } catch (error) {
+ logger.error('[validateAgentApiKey] Error validating API key:', error);
+ return null;
+ }
+ }
+
+ async function listAgentApiKeys(userId: string | Types.ObjectId): Promise<AgentApiKeyListItem[]> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const keys = (await AgentApiKey.find({ userId })
+ .sort({ createdAt: -1 })
+ .lean()) as unknown as IAgentApiKey[];
+
+ return keys.map((key) => ({
+ id: (key._id as Types.ObjectId).toString(),
+ name: key.name,
+ keyPrefix: key.keyPrefix,
+ lastUsedAt: key.lastUsedAt,
+ expiresAt: key.expiresAt,
+ createdAt: key.createdAt,
+ }));
+ } catch (error) {
+ logger.error('[listAgentApiKeys] Error listing API keys:', error);
+ throw error;
+ }
+ }
+
+ async function deleteAgentApiKey(
+ keyId: string | Types.ObjectId,
+ userId: string | Types.ObjectId,
+ ): Promise<boolean> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const result = await AgentApiKey.deleteOne({ _id: keyId, userId });
+ return result.deletedCount > 0;
+ } catch (error) {
+ logger.error('[deleteAgentApiKey] Error deleting API key:', error);
+ throw error;
+ }
+ }
+
+ async function deleteAllAgentApiKeys(userId: string | Types.ObjectId): Promise<number> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const result = await AgentApiKey.deleteMany({ userId });
+ return result.deletedCount;
+ } catch (error) {
+ logger.error('[deleteAllAgentApiKeys] Error deleting all API keys:', error);
+ throw error;
+ }
+ }
+
+ async function getAgentApiKeyById(
+ keyId: string | Types.ObjectId,
+ userId: string | Types.ObjectId,
+ ): Promise<AgentApiKeyListItem | null> {
+ try {
+ const AgentApiKey = mongoose.models.AgentApiKey;
+ const keyDoc = (await AgentApiKey.findOne({
+ _id: keyId,
+ userId,
+ }).lean()) as IAgentApiKey | null;
+
+ if (!keyDoc) {
+ return null;
+ }
+
+ return {
+ id: (keyDoc._id as Types.ObjectId).toString(),
+ name: keyDoc.name,
+ keyPrefix: keyDoc.keyPrefix,
+ lastUsedAt: keyDoc.lastUsedAt,
+ expiresAt: keyDoc.expiresAt,
+ createdAt: keyDoc.createdAt,
+ };
+ } catch (error) {
+ logger.error('[getAgentApiKeyById] Error getting API key:', error);
+ throw error;
+ }
+ }
+
+ return {
+ createAgentApiKey,
+ validateAgentApiKey,
+ listAgentApiKeys,
+ deleteAgentApiKey,
+ deleteAllAgentApiKeys,
+ getAgentApiKeyById,
+ };
+}
+
+export type AgentApiKeyMethods = ReturnType<typeof createAgentApiKeyMethods>;
diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.ts
index b6f1be64e9..2f20b67fec 100644
--- a/packages/data-schemas/src/methods/index.ts
+++ b/packages/data-schemas/src/methods/index.ts
@@ -10,6 +10,8 @@ import { createFileMethods, type FileMethods } from './file';
import { createMemoryMethods, type MemoryMethods } from './memory';
/* Agent Categories */
import { createAgentCategoryMethods, type AgentCategoryMethods } from './agentCategory';
+/* Agent API Keys */
+import { createAgentApiKeyMethods, type AgentApiKeyMethods } from './agentApiKey';
/* MCP Servers */
import { createMCPServerMethods, type MCPServerMethods } from './mcpServer';
/* Plugin Auth */
@@ -28,6 +30,7 @@ export type AllMethods = UserMethods &
FileMethods &
MemoryMethods &
AgentCategoryMethods &
+ AgentApiKeyMethods &
MCPServerMethods &
UserGroupMethods &
AclEntryMethods &
@@ -49,6 +52,7 @@ export function createMethods(mongoose: typeof import('mongoose')): AllMethods {
...createFileMethods(mongoose),
...createMemoryMethods(mongoose),
...createAgentCategoryMethods(mongoose),
+ ...createAgentApiKeyMethods(mongoose),
...createMCPServerMethods(mongoose),
...createAccessRoleMethods(mongoose),
...createUserGroupMethods(mongoose),
@@ -67,6 +71,7 @@ export type {
FileMethods,
MemoryMethods,
AgentCategoryMethods,
+ AgentApiKeyMethods,
MCPServerMethods,
UserGroupMethods,
AclEntryMethods,
diff --git a/packages/data-schemas/src/models/agentApiKey.ts b/packages/data-schemas/src/models/agentApiKey.ts
new file mode 100644
index 0000000000..70387a2cef
--- /dev/null
+++ b/packages/data-schemas/src/models/agentApiKey.ts
@@ -0,0 +1,7 @@
+import agentApiKeySchema, { IAgentApiKey } from '~/schema/agentApiKey';
+
+export function createAgentApiKeyModel(mongoose: typeof import('mongoose')) {
+ return (
+ mongoose.models.AgentApiKey || mongoose.model<IAgentApiKey>('AgentApiKey', agentApiKeySchema)
+ );
+}
diff --git a/packages/data-schemas/src/models/index.ts b/packages/data-schemas/src/models/index.ts
index 45516d5a7c..ca1a6259be 100644
--- a/packages/data-schemas/src/models/index.ts
+++ b/packages/data-schemas/src/models/index.ts
@@ -5,6 +5,7 @@ import { createBalanceModel } from './balance';
import { createConversationModel } from './convo';
import { createMessageModel } from './message';
import { createAgentModel } from './agent';
+import { createAgentApiKeyModel } from './agentApiKey';
import { createAgentCategoryModel } from './agentCategory';
import { createMCPServerModel } from './mcpServer';
import { createRoleModel } from './role';
@@ -39,6 +40,7 @@ export function createModels(mongoose: typeof import('mongoose')) {
Conversation: createConversationModel(mongoose),
Message: createMessageModel(mongoose),
Agent: createAgentModel(mongoose),
+ AgentApiKey: createAgentApiKeyModel(mongoose),
AgentCategory: createAgentCategoryModel(mongoose),
MCPServer: createMCPServerModel(mongoose),
Role: createRoleModel(mongoose),
diff --git a/packages/data-schemas/src/schema/accessRole.ts b/packages/data-schemas/src/schema/accessRole.ts
index 082c28a5f0..52f9e796c0 100644
--- a/packages/data-schemas/src/schema/accessRole.ts
+++ b/packages/data-schemas/src/schema/accessRole.ts
@@ -16,7 +16,7 @@ const accessRoleSchema = new Schema<IAccessRole>(
description: String,
resourceType: {
type: String,
- enum: ['agent', 'project', 'file', 'promptGroup', 'mcpServer'],
+ enum: ['agent', 'project', 'file', 'promptGroup', 'mcpServer', 'remoteAgent'],
required: true,
default: 'agent',
},
diff --git a/packages/data-schemas/src/schema/agentApiKey.ts b/packages/data-schemas/src/schema/agentApiKey.ts
new file mode 100644
index 0000000000..d7037f857f
--- /dev/null
+++ b/packages/data-schemas/src/schema/agentApiKey.ts
@@ -0,0 +1,59 @@
+import mongoose, { Schema, Document, Types } from 'mongoose';
+
+export interface IAgentApiKey extends Document {
+ userId: Types.ObjectId;
+ name: string;
+ keyHash: string;
+ keyPrefix: string;
+ lastUsedAt?: Date;
+ expiresAt?: Date;
+ createdAt: Date;
+ updatedAt: Date;
+}
+
+const agentApiKeySchema: Schema<IAgentApiKey> = new Schema(
+ {
+ userId: {
+ type: mongoose.Schema.Types.ObjectId,
+ ref: 'User',
+ required: true,
+ index: true,
+ },
+ name: {
+ type: String,
+ required: true,
+ trim: true,
+ maxlength: 100,
+ },
+ keyHash: {
+ type: String,
+ required: true,
+ select: false,
+ index: true,
+ },
+ keyPrefix: {
+ type: String,
+ required: true,
+ index: true,
+ },
+ lastUsedAt: {
+ type: Date,
+ },
+ expiresAt: {
+ type: Date,
+ },
+ },
+ { timestamps: true },
+);
+
+agentApiKeySchema.index({ userId: 1, name: 1 });
+
+/**
+ * TTL index for automatic cleanup of expired keys.
+ * MongoDB deletes documents when expiresAt passes (expireAfterSeconds: 0 means immediate).
+ * Note: Expired keys are permanently removed, not soft-deleted.
+ * If audit trails are needed, remove this index and check expiration programmatically.
+ */
+agentApiKeySchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+
+export default agentApiKeySchema;
diff --git a/packages/data-schemas/src/schema/index.ts b/packages/data-schemas/src/schema/index.ts
index 2d94db5301..454780b8bf 100644
--- a/packages/data-schemas/src/schema/index.ts
+++ b/packages/data-schemas/src/schema/index.ts
@@ -1,5 +1,6 @@
export { default as actionSchema } from './action';
export { default as agentSchema } from './agent';
+export { default as agentApiKeySchema } from './agentApiKey';
export { default as agentCategorySchema } from './agentCategory';
export { default as assistantSchema } from './assistant';
export { default as balanceSchema } from './balance';
diff --git a/packages/data-schemas/src/schema/role.ts b/packages/data-schemas/src/schema/role.ts
index 3ac0a7f8a2..e4821ba405 100644
--- a/packages/data-schemas/src/schema/role.ts
+++ b/packages/data-schemas/src/schema/role.ts
@@ -61,6 +61,12 @@ const rolePermissionsSchema = new Schema(
[Permissions.SHARE]: { type: Boolean },
[Permissions.SHARE_PUBLIC]: { type: Boolean },
},
+ [PermissionTypes.REMOTE_AGENTS]: {
+ [Permissions.USE]: { type: Boolean },
+ [Permissions.CREATE]: { type: Boolean },
+ [Permissions.SHARE]: { type: Boolean },
+ [Permissions.SHARE_PUBLIC]: { type: Boolean },
+ },
},
{ _id: false },
);
diff --git a/packages/data-schemas/src/types/agentApiKey.ts b/packages/data-schemas/src/types/agentApiKey.ts
new file mode 100644
index 0000000000..968937a717
--- /dev/null
+++ b/packages/data-schemas/src/types/agentApiKey.ts
@@ -0,0 +1,46 @@
+import { Document, Types } from 'mongoose';
+
+export interface IAgentApiKey extends Document {
+ userId: Types.ObjectId;
+ name: string;
+ keyHash: string;
+ keyPrefix: string;
+ lastUsedAt?: Date;
+ expiresAt?: Date;
+ createdAt: Date;
+ updatedAt: Date;
+}
+
+export interface AgentApiKeyCreateData {
+ userId: Types.ObjectId | string;
+ name: string;
+ expiresAt?: Date | null;
+}
+
+export interface AgentApiKeyCreateResult {
+ id: string;
+ name: string;
+ keyPrefix: string;
+ key: string;
+ createdAt: Date;
+ expiresAt?: Date;
+}
+
+export interface AgentApiKeyListItem {
+ id: string;
+ name: string;
+ keyPrefix: string;
+ lastUsedAt?: Date;
+ expiresAt?: Date;
+ createdAt: Date;
+}
+
+export interface AgentApiKeyQuery {
+ userId?: Types.ObjectId | string;
+ keyPrefix?: string;
+ id?: string;
+}
+
+export interface AgentApiKeyDeleteResult {
+ deletedCount?: number;
+}
diff --git a/packages/data-schemas/src/types/index.ts b/packages/data-schemas/src/types/index.ts
index 828cdf9c8f..38f9f22b50 100644
--- a/packages/data-schemas/src/types/index.ts
+++ b/packages/data-schemas/src/types/index.ts
@@ -10,6 +10,7 @@ export * from './balance';
export * from './banner';
export * from './message';
export * from './agent';
+export * from './agentApiKey';
export * from './agentCategory';
export * from './role';
export * from './action';
diff --git a/packages/data-schemas/src/types/role.ts b/packages/data-schemas/src/types/role.ts
index fc6340da2c..e70e29204a 100644
--- a/packages/data-schemas/src/types/role.ts
+++ b/packages/data-schemas/src/types/role.ts
@@ -59,6 +59,12 @@ export interface IRole extends Document {
[Permissions.SHARE]?: boolean;
[Permissions.SHARE_PUBLIC]?: boolean;
};
+ [PermissionTypes.REMOTE_AGENTS]?: {
+ [Permissions.USE]?: boolean;
+ [Permissions.CREATE]?: boolean;
+ [Permissions.SHARE]?: boolean;
+ [Permissions.SHARE_PUBLIC]?: boolean;
+ };
};
}