🏇 feat: Register SDK-Backed Agents for Native Chat (#18114)
Some checks are pending
Docker Dev Images Build / publish (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run

* feat: register SDK-backed agents through agent management

* fix: gate SDK binding writes and preserve native lifecycle
This commit is contained in:
Danny Avila 2026-11-13 13:02:53 -05:00 • committed by GitHub
parent fb3b299de6
commit fad2c51da4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 775 additions and 3 deletions

View file

@ -53,6 +53,8 @@ const {
applyInstructionsPromptUnset,
instructionsContentForScan,
authorizeAgentRestore,
applySdkAgentBindingWrite,
getSdkAgentWriteErrorStatus,
} = require('@librechat/api');
const {
Time,
@ -765,6 +767,12 @@ const createAgentHandler = async (req, res) => {
normalizeToolResourceFiles(req.body?.tool_resources);
const validatedData = agentCreateSchema.parse(req.body);
const { tools = [], ...agentData } = removeNullishValues(validatedData);
applySdkAgentBindingWrite(
agentData,
validatedData.sdk_runtime,
req.config?.endpoints?.agents,
req.user?.role,
);
if (
(!isCodeInterpreterCapabilityEnabled(req) || !tools.includes(Tools.execute_code)) &&
@ -1109,6 +1117,12 @@ const updateAgentHandler = async (req, res) => {
...rest
} = validatedData;
let updateData = removeNullishValues(rest);
applySdkAgentBindingWrite(
updateData,
validatedData.sdk_runtime,
req.config?.endpoints?.agents,
req.user?.role,
);
if (codeEnvironmentIdField !== undefined) {
updateData.code_environment_id = codeEnvironmentIdField;
}
@ -1519,6 +1533,12 @@ const duplicateAgentHandler = async (req, res) => {
id: newAgentId,
author: userId,
});
applySdkAgentBindingWrite(
newAgentData,
newAgentData.sdk_runtime,
req.config?.endpoints?.agents,
req.user?.role,
);
if (!validateAgentCodeEnvironmentAllowlist(req, res, newAgentData.code_environment_ids)) {
return;
}
@ -1746,7 +1766,7 @@ const duplicateAgentHandler = async (req, res) => {
if (error?.statusCode === 409) {
return res.status(409).json({ error: error.message });
}
res.status(500).json({ error: error.message });
res.status(getSdkAgentWriteErrorStatus(error)).json({ error: error.message });
}
};
@ -2096,6 +2116,12 @@ const revertAgentVersionHandler = async (req, res) => {
if (!revertVersion) {
return res.status(404).json({ error: `Version ${version_index} not found` });
}
applySdkAgentBindingWrite(
revertVersion,
revertVersion.sdk_runtime,
req.config?.endpoints?.agents,
req.user?.role,
);
if (!validateAgentCodeEnvironmentAllowlist(req, res, revertVersion.code_environment_ids)) {
return;
}
@ -2260,7 +2286,7 @@ const revertAgentVersionHandler = async (req, res) => {
if (error?.statusCode === 409) {
return res.status(409).json({ error: error.message });
}
res.status(500).json({ error: error.message });
res.status(getSdkAgentWriteErrorStatus(error)).json({ error: error.message });
}
};
/**

93
docs/sdk/agents.md Normal file
View file

@ -0,0 +1,93 @@
# Registering SDK-backed agents
An SDK-backed agent is an ordinary saved agent with an operator-installed execution binding.
Create, discover, share, version, and delete it through the existing Agents Management API.
Select it in the normal agent picker; chat uses the native SDK handlers, persistence, approvals,
and cancellation paths. The runtime returns a real `@librechat/agents` `Run` instead of translating
events into a second chat protocol.
## Install a trusted runtime
Install the module in the LibreChat server environment and configure it in `librechat.yaml`:
```yaml
endpoints:
agents:
sdkRuntimes:
schema-advisor:
module: ./runtimes/schema-advisor.cjs
roles: [ADMIN]
```
Paths resolve from the server working directory. Package names are supported too. Modules are
trusted server code with the server process's privileges; only operators configure them.
Agent requests cannot supply module paths, URLs, code, or credentials. Runtime use is disabled
unless its ID is configured and the authenticated caller's role is in `roles` (default: `ADMIN`).
The normal saved-agent permissions continue to apply. Restart the server after changing a module;
Node caches installed modules.
The module exports this contract (types are exported by `@librechat/api`):
```js
const { Run } = require('@librechat/agents');
module.exports = {
protocolVersion: 1,
async createRun({ config, identity }) {
// Use identity.agentId as the saved identity and identity.runId for this execution.
// Customize the graph with your SDK integration here. Retain the host-owned config:
// handlers, hooks, signal, checkpointing, policy, and usage callbacks.
return Run.create(config);
},
};
```
Use the server's installed SDK as a peer dependency so the returned Run uses the same SDK
instance as the host. The immutable identity contains `agentId`, `runtimeId`, `runId`,
`userId`, and optional `conversationId` and `tenantId`, all supplied by the server. Stateless
execution APIs do not invent a saved conversation identity. A module must not
replace authenticated identity or broaden the caller's tool permissions. A different run ID is
rejected before execution.
## Register the agent
Using the existing management credentials, create through `POST /api/agents/v1/agents`:
```json
{
"name": "Schema Advisor",
"provider": "openAI",
"model": "gpt-4.1",
"sdk_runtime": { "id": "schema-advisor", "protocolVersion": 1 }
}
```
Provider/model continue to use the host's native configured endpoint and model policies.
The response has the usual server-assigned agent ID and the binding. Use that ID in the agent
picker or existing execution APIs. `PATCH /api/agents/v1/agents/:id` can replace the binding;
`sdk_runtime: null` returns the agent to native execution. Ownership, sharing, and version access
are unchanged. The binding grants no authority by itself.
## Compatibility and validation
Protocol 1 runs inside the LibreChat process. It establishes saved identity and execution binding;
it does not claim remote process isolation or an HTTP registration/event-ingestion protocol.
Native agent chains and configured native subagent compositions containing a runtime binding
are rejected rather than silently ignoring execution bindings. A runtime can construct its own SDK graph while retaining the host configuration.
Before enabling a runtime for a role, verify text/tool events, final persistence, retry, stop,
approval/resume when used, org switching, and latency against the same native agent. A factory
that drops the host's handlers or hooks does not satisfy the integration contract. Loading an
unknown module/version fails closed; normal agents require no runtime module or extra database read.
## Rollout and rollback
Deploy the supporting code to every replica before adding `sdkRuntimes` configuration and
registering bindings. Older servers do not understand this field and could execute the agent
as a native agent. Creation, update, duplication, and version restoration reject non-null
bindings unless the runtime is configured for the caller's role.
Before downgrading any replica, remove the runtime configuration to stop new bindings and
clear existing bindings with `sdk_runtime: null`. Verify that no active runs or current agent
bindings depend on a runtime before the downgrade. Removing configuration alone disables
execution on supported servers; it does not rewrite stored agents.

View file

@ -180,6 +180,10 @@ endpoints:
# Default capabilities plus run_in_background (off by default upstream) so the
# background tool-call e2e can opt an MCP tool into detached dispatch.
agents:
sdkRuntimes:
e2e-sdk:
module: ./e2e/setup/sdk-runtime.cjs
roles: [ADMIN]
subagentActivity:
contentRecoveryEnabled: true
fileSharing:

11
e2e/setup/sdk-runtime.cjs Normal file
View file

@ -0,0 +1,11 @@
const { Run } = require('@librechat/agents');
module.exports = {
protocolVersion: 1,
async createRun({ config, identity }) {
if (!Object.isFrozen(identity) || identity.runId !== config.runId || !identity.userId) {
throw new Error('SDK runtime identity was not established by the host');
}
return Run.create(config);
},
};

View file

@ -1,4 +1,6 @@
import fs from 'fs';
import jwt from 'jsonwebtoken';
import { randomUUID } from 'crypto';
import path from 'path';
import mongoose from 'mongoose';
import { expect, test } from '@playwright/test';
@ -72,6 +74,89 @@ test.describe('agent management file lifecycle', () => {
}
});
test('registers an SDK agent and executes it through native chat and persistence', async ({
request,
}) => {
const binding = { id: 'e2e-sdk', protocolVersion: 1 };
const created = await request.post(agentsPath, {
headers,
data: {
name: 'SDK runtime agent',
provider: 'Mock Provider A',
model: 'mock-model-a',
sdk_runtime: binding,
},
});
expect(created.status(), await created.text()).toBe(201);
const agent = await created.json();
expect(agent.sdk_runtime).toEqual(binding);
const secret = process.env.JWT_SECRET;
if (!secret) throw new Error('Test JWT secret is unavailable');
const chatHeaders = {
Authorization: `Bearer ${jwt.sign({ id: managementUserId }, secret, { expiresIn: '5m' })}`,
'X-Tenant-Id': managementTenantId,
'User-Agent': 'Mozilla/5.0 Chrome/126.0.0.0 Safari/537.36',
};
try {
const read = await request.get(`${agentsPath}/${agent.id}`, { headers });
expect((await read.json()).sdk_runtime).toEqual(binding);
const run = async () => {
const admitted = await request.post('/api/agents/chat/agents', {
headers: chatHeaders,
data: {
text: 'E2E_REPLY:sdk-runtime',
sender: 'User',
isCreatedByUser: true,
parentMessageId: '00000000-0000-0000-0000-000000000000',
messageId: randomUUID(),
endpoint: 'agents',
agent_id: agent.id,
key: 'never',
isTemporary: false,
isRegenerate: false,
isContinued: false,
},
});
expect(admitted.status(), await admitted.text()).toBe(200);
const { streamId, conversationId } = await admitted.json();
const stream = await request.get(`/api/agents/chat/stream/${streamId}`, {
headers: chatHeaders,
});
expect(stream.status(), await stream.text()).toBe(200);
const saved = await request.get(`/api/messages/${conversationId}`, {
headers: chatHeaders,
});
expect(saved.status(), await saved.text()).toBe(200);
return JSON.stringify(await saved.json());
};
expect(await run()).toContain('E2E reply sdk-runtime');
const changed = await request.patch(`${agentsPath}/${agent.id}`, {
headers,
data: { sdk_runtime: { id: 'not-configured', protocolVersion: 1 } },
});
expect(changed.status(), await changed.text()).toBe(400);
// Simulate an existing binding whose operator configuration was removed.
await withMongo(async (db) => {
await db
.collection('agents')
.updateOne(
{ id: agent.id, tenantId: managementTenantId },
{ $set: { sdk_runtime: { id: 'not-configured', protocolVersion: 1 } } },
);
});
expect(await run()).not.toContain('E2E reply sdk-runtime');
const cleared = await request.patch(`${agentsPath}/${agent.id}`, {
headers,
data: { sdk_runtime: null },
});
expect(cleared.status(), await cleared.text()).toBe(200);
expect((await cleared.json()).sdk_runtime).toBeNull();
expect(await run()).toContain('E2E reply sdk-runtime');
} finally {
await request.delete(`${agentsPath}/${agent.id}`, { headers });
}
});
for (const purpose of ['context', 'file_search', 'execute_code']) {
test(`uploads, persists, lists and unlinks ${purpose} files`, async ({ request }) => {
const created = await request.post(agentsPath, {

View file

@ -2381,6 +2381,31 @@
"AgentCreateRequest": {
"type": "object",
"properties": {
"sdk_runtime": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
},
"protocolVersion": {
"type": "number",
"const": 1
}
},
"required": [
"id",
"protocolVersion"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@ -2872,6 +2897,31 @@
"AgentUpdateRequest": {
"type": "object",
"properties": {
"sdk_runtime": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
},
"protocolVersion": {
"type": "number",
"const": 1
}
},
"required": [
"id",
"protocolVersion"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@ -3344,6 +3394,31 @@
"Agent": {
"type": "object",
"properties": {
"sdk_runtime": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
},
"protocolVersion": {
"type": "number",
"const": 1
}
},
"required": [
"id",
"protocolVersion"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",

View file

@ -75,6 +75,7 @@ export * from './run';
export * from './fading';
export * from './publication';
export * from './runtime';
export * from './sdk';
export * from './convoPersistence';
export * from './testHook';
export * from './tools';

View file

@ -277,6 +277,7 @@ export function projectAgentManagementResponse(
return agentManagementResponseSchema.parse({
id: source.id,
provider: source.provider,
sdk_runtime: source.sdk_runtime,
model: source.model,
version: getVersion(source),
createdAt: toTimestamp(source.createdAt),

View file

@ -69,6 +69,7 @@ import type { ReviewedToolApprovals } from './hitl/modes';
import type { SubagentUsageEvent } from '~/agents/usage';
import type { ProvisionState } from '~/agents/resources';
import type { RunFileSession } from './files/session';
import type { SdkAgentRuntimeLoader } from './sdk';
import type { RunFadingTiers } from './fading';
import type * as t from '~/types';
import {
@ -122,6 +123,7 @@ import { applyCustomHandoffPromptKeyCompatibility } from '~/agents/handoffPrompt
import { stripIntentFromToolRegistry, stripIntentFromToolDefinitions } from '~/agents/intent';
import { createAgentToolApprovalSession, bindRunToolApprovalSession } from './hitl/modes';
import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils/headers';
import { createSdkAgentRun, resolveSdkAgentBinding, SdkAgentRuntimeError } from './sdk';
import { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools';
import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';
import { reportSubagentResolutionFailure } from '~/agents/failures/subagent';
@ -2316,6 +2318,7 @@ export async function createRun({
toolApprovalAllows,
toolInputValidationErrors,
sessionStartSource,
loadSdkRuntime,
streaming = true,
streamUsage = true,
}: {
@ -2470,11 +2473,13 @@ export async function createRun({
sessionStartSource?: string;
/** Request-scoped tool input failures consumed by the completion handler. */
toolInputValidationErrors?: Map<string, ToolInputValidationError>;
loadSdkRuntime?: SdkAgentRuntimeLoader;
} & Pick<
RunConfig,
'tokenCounter' | 'customHandlers' | 'indexTokenCountMap' | 'initialSessions'
>): Promise<Run<IState>> {
const resolvedRunId = runId ?? randomUUID();
const registration = resolveSdkAgentBinding(agents, appConfig?.endpoints?.agents, user?.role);
const runFilesActive =
runFiles?.activate(
resolvedRunId,
@ -2548,6 +2553,9 @@ export async function createRun({
const preparedCodeFileAgents = new WeakSet(codeFileAgents.values());
const buildAgentInput = (agent: RunAgent, opts: { isSubagent?: boolean } = {}): AgentInputs => {
if (agent.id !== agents[0]?.id && agent.sdk_runtime != null) {
throw new SdkAgentRuntimeError('sdk_runtime_composition_unsupported');
}
if (!preparedCodeFileAgents.has(agent)) {
if (agent.provisionState) agent.provisionState.codeEnvDestinations = undefined;
codeFileAgents.set(agent.id, agent);
@ -3309,7 +3317,20 @@ export async function createRun({
// older versions ignore the field.
...(streamLimits && { streamLimits }),
};
const run = await Run.create(runConfig);
const run = registration
? await createSdkAgentRun({
registration,
config: runConfig,
loadModule: loadSdkRuntime,
signal,
identity: {
agentId: agents[0].id,
conversationId: conversationId ?? requestBody?.conversationId ?? undefined,
userId: user?.id ?? '',
tenantId: tenantId ?? user?.tenantId,
},
})
: await Run.create(runConfig);
if (approvalWiring != null) bindRunToolApprovalSession(run, agentApprovalSession);
runMCPToolAliases.set(run, mcpToolAliases);

View file

@ -0,0 +1,229 @@
import { agentsEndpointSchema } from 'librechat-data-provider';
import { HumanMessage } from '@librechat/agents/langchain/messages';
import { Run, Providers, GraphEvents, FakeChatModel } from '@librechat/agents';
import type { AppConfig, IUser } from '@librechat/data-schemas';
import type { RunConfig } from '@librechat/agents';
import { createSdkAgentRun, resolveSdkAgentBinding, applySdkAgentBindingWrite } from './sdk';
import { agentManagementCreateSchema, projectAgentManagementResponse } from './management';
import { createRun } from './run';
const binding = { id: 'schema-advisor', protocolVersion: 1 as const };
const identity = {
agentId: 'agent_saved',
userId: 'authenticated',
tenantId: 'authorized',
conversationId: 'conversation',
};
const endpoint = {
sdkRuntimes: { 'schema-advisor': { module: './approved.cjs', roles: ['ADMIN'] } },
};
function config(): RunConfig {
return {
runId: 'run_server',
skipCleanup: true,
tokenCounter: () => 1,
graphConfig: {
type: 'standard',
maxContextTokens: 100_000,
llmConfig: { provider: Providers.OPENAI, streaming: true, apiKey: 'test' },
tools: [],
},
};
}
function args() {
return { registration: { binding, module: './approved.cjs' }, config: config(), identity };
}
describe('SDK agent registration and native execution', () => {
it('dispatches the root through the full host path, including isolated-input prebuilding', async () => {
const factory = jest.fn(async ({ config: cfg }: { config: RunConfig }) => {
const run = await Run.create(cfg);
if (!run.Graph) throw new Error('Missing graph');
run.Graph.overrideModel = new FakeChatModel({ responses: ['Host SDK reply'] });
return run;
});
const deltas: string[] = [];
const run = await createRun({
runId: 'host-sdk-run',
conversationId: identity.conversationId,
signal: new AbortController().signal,
messages: [new HumanMessage('hello')],
tokenCounter: () => 1,
user: { id: identity.userId, role: 'ADMIN', tenantId: identity.tenantId } as IUser,
appConfig: { endpoints: { agents: agentsEndpointSchema.parse(endpoint) } } as AppConfig,
agents: [
{
id: identity.agentId,
name: 'SDK agent',
description: '',
created_at: 0,
avatar: null,
provider: Providers.OPENAI,
model: 'gpt-4.1',
model_parameters: {
model: 'gpt-4.1',
temperature: null,
maxContextTokens: null,
max_context_tokens: null,
max_output_tokens: null,
top_p: null,
frequency_penalty: null,
presence_penalty: null,
},
sdk_runtime: binding,
},
],
customHandlers: {
[GraphEvents.ON_MESSAGE_DELTA]: {
handle: async () => {
deltas.push('delta');
},
},
},
loadSdkRuntime: () => ({ protocolVersion: 1, createRun: factory }),
});
expect(factory).toHaveBeenCalledTimes(1);
await run.processStream({ messages: [new HumanMessage('hello')] }, { version: 'v2' });
expect(deltas).toContain('delta');
});
it('gates all binding writes and retains explicit removal', () => {
const patch: { sdk_runtime?: typeof binding | null } = {};
expect(() => applySdkAgentBindingWrite(patch, binding, undefined, 'ADMIN')).toThrow();
expect(() => applySdkAgentBindingWrite(patch, binding, endpoint, 'USER')).toThrow();
expect(patch).toEqual({});
applySdkAgentBindingWrite(patch, binding, endpoint, 'ADMIN');
expect(patch.sdk_runtime).toEqual(binding);
applySdkAgentBindingWrite(patch, undefined, undefined, undefined);
expect(patch.sdk_runtime).toEqual(binding);
applySdkAgentBindingWrite(patch, null, undefined, undefined);
expect(patch.sdk_runtime).toBeNull();
});
it('round-trips the binding through management without executable fields', () => {
const data = agentManagementCreateSchema.parse({
name: 'Advisor',
provider: 'openAI',
model: 'gpt-4.1',
sdk_runtime: binding,
});
expect(
projectAgentManagementResponse({
...data,
id: identity.agentId,
version: 1,
createdAt: '2026-11-13T00:00:00Z',
updatedAt: '2026-11-13T00:00:00Z',
}).sdk_runtime,
).toEqual(binding);
expect(
agentManagementCreateSchema.safeParse({
provider: 'openAI',
model: 'gpt-4.1',
sdk_runtime: { ...binding, module: './untrusted.cjs' },
}).success,
).toBe(false);
});
it('leaves native agents on the existing path', () => {
expect(resolveSdkAgentBinding([{ id: 'native' }], undefined, 'USER')).toBeUndefined();
});
it('requires configured runtime and role', () => {
const agents = [{ id: identity.agentId, sdk_runtime: binding }];
expect(resolveSdkAgentBinding(agents, endpoint, 'ADMIN')).toEqual({
binding,
module: './approved.cjs',
});
expect(() => resolveSdkAgentBinding(agents, endpoint, 'USER')).toThrow(
expect.objectContaining({ code: 'sdk_runtime_forbidden' }),
);
expect(() => resolveSdkAgentBinding(agents, undefined, 'ADMIN')).toThrow(
expect.objectContaining({ code: 'sdk_runtime_unavailable' }),
);
expect(() =>
resolveSdkAgentBinding(
[{ id: 'saved', sdk_runtime: { ...binding, id: 'constructor' } }],
endpoint,
'ADMIN',
),
).toThrow(expect.objectContaining({ code: 'sdk_runtime_unavailable' }));
});
it('does not silently drop native chain members', () => {
expect(() =>
resolveSdkAgentBinding(
[{ id: 'native' }, { id: 'sdk', sdk_runtime: binding }],
endpoint,
'ADMIN',
),
).toThrow(expect.objectContaining({ code: 'sdk_runtime_composition_unsupported' }));
});
it('runs a real SDK graph through native event handlers with immutable host identity', async () => {
const events: string[] = [];
const cfg = config();
cfg.customHandlers = {
[GraphEvents.ON_MESSAGE_DELTA]: {
handle: async () => {
events.push('delta');
},
},
};
const factory = jest.fn(async (input: { config: RunConfig; identity: typeof identity }) => {
expect(Object.isFrozen(input.identity)).toBe(true);
const run = await Run.create(input.config);
if (!run.Graph) throw new Error('Missing graph');
run.Graph.overrideModel = new FakeChatModel({ responses: ['Shared native events'] });
return run;
});
const run = await createSdkAgentRun({
...args(),
config: cfg,
loadModule: () => ({ protocolVersion: 1, createRun: factory }),
});
expect(factory.mock.calls[0][0]).toEqual({
config: cfg,
identity: { ...identity, runtimeId: binding.id, runId: cfg.runId },
});
await run.processStream(
{ messages: [new HumanMessage('hello')] },
{ configurable: { thread_id: identity.conversationId }, version: 'v2' },
);
expect(events).toContain('delta');
expect(run.getInterrupt()).toBeUndefined();
});
it('sanitizes module errors and rejects unsupported versions', async () => {
await expect(
createSdkAgentRun({
...args(),
loadModule: () => {
throw new Error('secret');
},
}),
).rejects.toMatchObject({
code: 'sdk_runtime_invalid',
message: 'The SDK agent runtime is unavailable for this request.',
});
await expect(
createSdkAgentRun({ ...args(), loadModule: () => ({ protocolVersion: 2 }) }),
).rejects.toMatchObject({ code: 'sdk_runtime_invalid' });
});
it('rejects replacement run identities', async () => {
await expect(
createSdkAgentRun({
...args(),
loadModule: () => ({
protocolVersion: 1,
createRun: () => Run.create({ ...config(), runId: 'other' }),
}),
}),
).rejects.toMatchObject({ code: 'sdk_runtime_identity_mismatch' });
});
it('does not load modules for aborted requests or missing principals', async () => {
const controller = new AbortController();
controller.abort();
const loadModule = jest.fn();
await expect(
createSdkAgentRun({ ...args(), loadModule, signal: controller.signal }),
).rejects.toThrow();
await expect(
createSdkAgentRun({ ...args(), loadModule, identity: { ...identity, userId: '' } }),
).rejects.toMatchObject({ code: 'sdk_runtime_identity_mismatch' });
expect(loadModule).not.toHaveBeenCalled();
});
});

View file

@ -0,0 +1,139 @@
import { z } from 'zod';
import { resolve } from 'node:path';
import { Run } from '@librechat/agents';
import { createRequire } from 'node:module';
import type { Agent, SdkRuntimeBinding, TAgentsEndpoint } from 'librechat-data-provider';
import type { RunConfig } from '@librechat/agents';
export interface SdkAgentIdentity {
readonly agentId: string;
readonly runtimeId: string;
readonly runId: string;
readonly conversationId?: string;
readonly userId: string;
readonly tenantId?: string;
}
export interface SdkAgentRuntime {
protocolVersion: 1;
/** Retain the host config's handlers, hooks, signal, and run identity. */
createRun(input: {
config: RunConfig;
identity: SdkAgentIdentity;
}): ReturnType<typeof Run.create>;
}
export type SdkAgentRuntimeLoader = (module: string) => unknown;
type AgentBinding = Pick<Agent, 'id' | 'sdk_runtime' | 'subagents'>;
type RuntimeConfig = Pick<NonNullable<TAgentsEndpoint>, 'sdkRuntimes'>;
export class SdkAgentRuntimeError extends Error {
constructor(
public readonly code:
| 'sdk_runtime_unavailable'
| 'sdk_runtime_forbidden'
| 'sdk_runtime_composition_unsupported'
| 'sdk_runtime_invalid'
| 'sdk_runtime_identity_mismatch',
) {
super('The SDK agent runtime is unavailable for this request.');
this.name = 'SdkAgentRuntimeError';
}
}
const runtimeModuleSchema = z.object({
protocolVersion: z.literal(1),
createRun: z.custom<SdkAgentRuntime['createRun']>((value) => typeof value === 'function'),
});
// Only operator configuration chooses modules. Node caches modules; no per-turn filesystem scan.
const requireRuntime = (module: string): unknown =>
createRequire(resolve(process.cwd(), 'package.json'))(module);
/** Classifies binding rejection at the legacy duplicate/restore error boundary. */
export function getSdkAgentWriteErrorStatus(error: unknown): number {
return error instanceof z.ZodError &&
error.issues.some((issue) => issue.path[0] === 'sdk_runtime')
? 400
: 500;
}
/** Applies an explicit write only after the operator has enabled its execution binding. */
export function applySdkAgentBindingWrite(
patch: { sdk_runtime?: SdkRuntimeBinding | null },
binding: SdkRuntimeBinding | null | undefined,
endpoint: RuntimeConfig | undefined,
role: string | undefined,
): void {
if (binding === undefined) return;
if (binding != null) {
try {
resolveSdkAgentBinding([{ id: '', sdk_runtime: binding }], endpoint, role);
} catch (error) {
if (!(error instanceof SdkAgentRuntimeError)) throw error;
throw new z.ZodError([{ code: 'custom', path: ['sdk_runtime'], message: error.message }]);
}
}
patch.sdk_runtime = binding;
}
export function resolveSdkAgentBinding(
agents: readonly AgentBinding[],
endpoint: RuntimeConfig | undefined,
role: string | undefined,
): { binding: SdkRuntimeBinding; module: string } | undefined {
if (!agents.some((agent) => agent.sdk_runtime != null)) return undefined;
const binding = agents[0]?.sdk_runtime;
if (agents.length !== 1 || binding == null || agents[0]?.subagents?.enabled === true) {
throw new SdkAgentRuntimeError('sdk_runtime_composition_unsupported');
}
const configured = Object.prototype.hasOwnProperty.call(endpoint?.sdkRuntimes ?? {}, binding.id)
? endpoint?.sdkRuntimes?.[binding.id]
: undefined;
if (binding.protocolVersion !== 1 || configured == null) {
throw new SdkAgentRuntimeError('sdk_runtime_unavailable');
}
if (role == null || !configured.roles.includes(role)) {
throw new SdkAgentRuntimeError('sdk_runtime_forbidden');
}
return { binding, module: configured.module };
}
/** Dispatch an already-authorized agent through its operator-installed SDK factory. */
export async function createSdkAgentRun({
registration,
config,
identity,
signal,
loadModule = requireRuntime,
}: {
registration: { binding: SdkRuntimeBinding; module: string };
config: RunConfig;
identity: Omit<SdkAgentIdentity, 'runtimeId' | 'runId'>;
signal?: AbortSignal;
loadModule?: SdkAgentRuntimeLoader;
}): ReturnType<typeof Run.create> {
signal?.throwIfAborted();
if (!identity.agentId || !identity.userId) {
throw new SdkAgentRuntimeError('sdk_runtime_identity_mismatch');
}
let runtime: SdkAgentRuntime;
try {
runtime = runtimeModuleSchema.parse(loadModule(registration.module));
} catch {
throw new SdkAgentRuntimeError('sdk_runtime_invalid');
}
const run = await runtime.createRun({
config,
identity: Object.freeze({
...identity,
runId: config.runId,
runtimeId: registration.binding.id,
}),
});
if (!(run instanceof Run) || run.id !== config.runId) {
throw new SdkAgentRuntimeError('sdk_runtime_identity_mismatch');
}
return run;
}

View file

@ -12,6 +12,7 @@ import {
ErrorTypes,
MAX_SUBAGENT_GRAPH_NODES,
MAX_GRAPH_SUBAGENT_MEMBERS,
sdkRuntimeBindingSchema,
} from 'librechat-data-provider';
import type {
Agent,
@ -458,6 +459,7 @@ type AgentBaseShape = {
code_workspace_id: z.ZodOptional<typeof agentCodeWorkspaceIdSchema>;
repositoryInstructions: z.ZodOptional<EnumOf<'prefer' | 'defer' | 'off'>>;
git_identity: typeof agentGitIdentitySchema;
sdk_runtime: z.ZodOptional<z.ZodNullable<typeof sdkRuntimeBindingSchema>>;
artifacts: z.ZodOptional<z.ZodString>;
recursion_limit: z.ZodOptional<z.ZodNumber>;
conversation_starters: z.ZodOptional<z.ZodArray<z.ZodString>>;
@ -469,6 +471,7 @@ type AgentBaseShape = {
};
export const agentBaseSchema: z.ZodObject<AgentBaseShape> = z.object({
sdk_runtime: sdkRuntimeBindingSchema.nullable().optional(),
name: z.string().nullable().optional(),
description: z.string().nullable().optional(),
instructions: z.string().nullable().optional(),

View file

@ -1883,6 +1883,18 @@ export const agentsEndpointSchema = baseEndpointSchema
.merge(
z.object({
/* agents specific */
/** Trusted server-side SDK modules. Unconfigured runtimes cannot execute. */
sdkRuntimes: z
.record(
z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
z
.object({
module: z.string().min(1),
roles: z.array(z.string().min(1)).min(1).default(['ADMIN']),
})
.strict(),
)
.optional(),
hostFileEdits: hostFileEditLimitsSchema.optional(),
/** Maximum provider error characters retained in unprotected terminal failures. */
maxProviderErrorChars: z

View file

@ -1109,6 +1109,15 @@ export const InstructionsPromptErrorCode = {
export type InstructionsPromptErrorCode =
(typeof InstructionsPromptErrorCode)[keyof typeof InstructionsPromptErrorCode];
export const sdkRuntimeBindingSchema = z
.object({
id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/),
protocolVersion: z.literal(1),
})
.strict();
export type SdkRuntimeBinding = z.infer<typeof sdkRuntimeBindingSchema>;
export type Agent = {
_id?: string;
id: string;
@ -1128,6 +1137,8 @@ export type Agent = {
tool_kwargs?: Record<string, unknown>;
metadata?: Record<string, unknown>;
provider: AgentProvider;
/** Selects an operator-installed SDK runtime; never contains executable code or credentials. */
sdk_runtime?: SdkRuntimeBinding | null;
model: string | null;
model_parameters: AgentModelParameters;
conversation_starters?: string[];
@ -1193,6 +1204,7 @@ export type Agent = {
export type TAgentsMap = Record<string, Agent | undefined>;
export type AgentCreateParams = {
sdk_runtime?: SdkRuntimeBinding | null;
git_identity?: AgentGitIdentity;
name?: string | null;
description?: string | null;
@ -1232,6 +1244,7 @@ export type AgentCreateParams = {
>;
export type AgentUpdateParams = {
sdk_runtime?: SdkRuntimeBinding | null;
name?: string | null;
description?: string | null;
avatar?: AgentAvatar | null;

View file

@ -3327,6 +3327,24 @@ describe('Agent Methods', () => {
expect((await getAgent({ id: agentId }))?.name).toBe('Concurrent');
});
test('restores SDK bindings and removes them when reverting to a native version', async () => {
const id = `agent_${uuidv4()}`;
await createAgent({
id,
name: 'Native',
provider: 'test',
model: 'test-model',
author: new mongoose.Types.ObjectId(),
});
const binding = { id: 'advisor', protocolVersion: 1 };
await updateAgent({ id }, { sdk_runtime: binding });
expect((await getAgent({ id }))?.sdk_runtime).toEqual(binding);
await revertAgentVersion({ id }, 0);
expect((await getAgent({ id }))?.sdk_runtime).toBeUndefined();
await revertAgentVersion({ id }, 1);
expect((await getAgent({ id }))?.sdk_runtime).toEqual(binding);
});
test('should unset a linked prompt-group instructions selection absent from the restored version', async () => {
const agentId = `agent_${uuidv4()}`;
const authorId = new mongoose.Types.ObjectId();

View file

@ -2778,6 +2778,7 @@ export function createAgentMethods(
const unsetOnRestore: Record<string, 1> = {};
for (const field of [
'sdk_runtime',
'code_environment_id',
'code_workspace_id',
'code_environment_ids',

View file

@ -0,0 +1,28 @@
import mongoose from 'mongoose';
import agentSchema from './agent';
const Agent = mongoose.models.SdkBindingAgent ?? mongoose.model('SdkBindingAgent', agentSchema);
const base = {
id: 'agent_saved',
provider: 'openAI',
model: 'fixture',
author: new mongoose.Types.ObjectId(),
};
describe('SDK runtime binding storage', () => {
it('retains the binding without adding a nested identity', () => {
const binding = { id: 'advisor', protocolVersion: 1 };
const doc = new Agent({ ...base, sdk_runtime: binding });
expect(doc.validateSync()).toBeUndefined();
expect(doc.toObject().sdk_runtime).toEqual(binding);
});
it('rejects incomplete and incompatible bindings', () => {
for (const binding of [{ id: 'advisor' }, { id: 'advisor', protocolVersion: 2 }]) {
expect(new Agent({ ...base, sdk_runtime: binding }).validateSync()).toBeDefined();
}
});
it('preserves the native default and explicit removal', () => {
expect(new Agent(base).toObject().sdk_runtime).toBeUndefined();
expect(new Agent({ ...base, sdk_runtime: null }).toObject().sdk_runtime).toBeNull();
});
});

View file

@ -25,6 +25,16 @@ const agentSchema: Schema<IAgent> = new Schema<IAgent>(
type: String,
required: true,
},
sdk_runtime: {
type: new Schema(
{
id: { type: String, required: true },
protocolVersion: { type: Number, enum: [1], required: true },
},
{ _id: false },
),
default: undefined,
},
model: {
type: String,
required: true,

View file

@ -8,6 +8,7 @@ import type {
AgentSubagentsConfig,
AgentGitIdentity,
AgentInstructionsPrompt,
SdkRuntimeBinding,
} from 'librechat-data-provider';
export interface ISupportContact {
@ -25,6 +26,7 @@ export interface IAgent extends Omit<Document, 'model'> {
source: string;
};
provider: string;
sdk_runtime?: SdkRuntimeBinding | null;
model: string;
model_parameters?: Record<string, unknown>;
artifacts?: string;