🪪 feat: Forward the Active Agent Id in Request Header Placeholders

A gateway in front of LibreChat sees the user, the conversation and the
message, but not which agent is running — so it cannot attribute spend per
agent, apply per-agent limits, or tell agent traffic from plain chat. Adds
`{{LIBRECHAT_AGENT_ID}}` as its own namespace beside the user / body / OpenID
ones, resolving wherever the existing request placeholders already work.

The value is the primary agent's, derived once per run, so subagent steps and
auxiliary calls (summarization, titles, activity labels, memory extraction)
forward the id of the turn they belong to rather than their own. Only
persisted agents resolve: ephemeral ids embed user-authored preset text that
is unsafe in a header value, so ephemeral runs and non-agent requests resolve
to an empty value rather than forwarding literal template text.

No behaviour change unless the placeholder is configured. The MCP surface
(#14303) is not covered — its connection classification derives from
`ALLOWED_BODY_FIELDS`, so a new namespace needs a follow-up.
This commit is contained in:
Jiří Krejčí 2026-08-20 16:17:36 +02:00
parent e1dfc10449
commit 8a3f1016f0
11 changed files with 582 additions and 23 deletions

View file

@ -11,6 +11,7 @@ const {
sanitizeTitle,
payloadParser,
createSafeUser,
createSafeAgent,
initializeAgent,
resolveConfigHeaders,
resolveRequestTenantId,
@ -3478,6 +3479,7 @@ class AgentClient extends BaseClient {
req: this.options.req,
res: this.options.res,
user: createSafeUser(this.options.req.user),
primaryAgent: createSafeAgent(this.options.agent),
tenantId: resolveRequestTenantId(this.options.req),
});
@ -6293,6 +6295,7 @@ class AgentClient extends BaseClient {
conversationId: this.conversationId,
parentMessageId: this.parentMessageId,
},
agent: createSafeAgent(this.options.agent),
});
try {

View file

@ -999,11 +999,12 @@ endpoints:
# (optional) Custom request headers for the built-in OpenAI / Google endpoints.
# Forwarded on every request to the provider (or an AI gateway / reverse proxy
# in front of it) while keeping provider-native request shaping intact. Values
# support env vars (${VAR}), user fields ({{LIBRECHAT_USER_*}}), and request-body
# fields ({{LIBRECHAT_BODY_CONVERSATIONID}}). Set the same `headers:` block under
# `endpoints.all` to apply globally across endpoints (endpoint values win on key
# collisions). NOTE: send metadata headers like these only behind a gateway that
# consumes them — native provider APIs ignore unknown headers.
# support env vars (${VAR}), user fields ({{LIBRECHAT_USER_*}}), request-body
# fields ({{LIBRECHAT_BODY_CONVERSATIONID}}), and the active agent id
# ({{LIBRECHAT_AGENT_ID}}). Set the same `headers:` block under `endpoints.all`
# to apply globally across endpoints (endpoint values win on key collisions).
# NOTE: send metadata headers like these only behind a gateway that consumes
# them — native provider APIs ignore unknown headers.
# openAI:
# headers:
# cf-aig-metadata: '{"user_email":"{{LIBRECHAT_USER_EMAIL}}","app":"librechat"}'

View file

@ -0,0 +1,160 @@
import { createRun } from '~/agents/run';
/**
* Guards `{{LIBRECHAT_AGENT_ID}}` resolution in `createRun`. The id must be the
* root agent's on every built input, subagents included, so a forwarded header
* matches the id persisted on the response message by
* `BaseClient.getResponseModel` — a gateway attributing spend per agent would
* otherwise bill a delegated step to a different agent than the database records.
* Ephemeral runs must resolve to nothing rather than leaking preset text.
*/
jest.mock('winston', () => ({
createLogger: jest.fn(() => ({
debug: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
info: jest.fn(),
})),
format: Object.assign(
jest.fn((fn) => () => ({ transform: fn })),
{
combine: jest.fn(),
colorize: jest.fn(),
simple: jest.fn(),
label: jest.fn(),
timestamp: jest.fn(),
printf: jest.fn(),
errors: jest.fn(),
splat: jest.fn(),
json: jest.fn(),
},
),
addColors: jest.fn(),
transports: { Console: jest.fn(), DailyRotateFile: jest.fn(), File: jest.fn() },
}));
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
logger: { debug: jest.fn(), warn: jest.fn(), error: jest.fn(), info: jest.fn() },
}));
jest.mock('@librechat/agents', () => {
const actual = jest.requireActual('@librechat/agents');
return {
...actual,
Run: {
create: jest.fn().mockResolvedValue({
processStream: jest.fn().mockResolvedValue(undefined),
}),
},
};
});
jest.mock('~/agents/checkpointer', () => ({
getAgentCheckpointer: jest.fn().mockResolvedValue({}),
}));
import { Run } from '@librechat/agents';
const AGENT_ID_HEADER = 'X-Agent-Id';
/**
* Each agent gets its OWN `configuration.defaultHeaders` object. Sharing one
* reference would let the idempotency `WeakSet` in `resolveConfigHeaders` skip
* the second resolution and return the first agent's already-resolved map,
* which would pass the subagent assertion without ever resolving its headers.
*/
function makeAgent(overrides?: Record<string, unknown>) {
return {
id: 'agent_root',
provider: 'openAI',
endpoint: 'openAI',
model: 'gpt-4o',
tools: [],
model_parameters: {
model: 'gpt-4o',
configuration: {
defaultHeaders: { [AGENT_ID_HEADER]: '{{LIBRECHAT_AGENT_ID}}' },
},
},
maxContextTokens: 100_000,
toolContextMap: {},
...overrides,
};
}
type CapturedInput = Record<string, unknown> & {
agentId?: string;
clientOptions?: { configuration?: { defaultHeaders?: Record<string, string> } };
subagentConfigs?: Array<{ type?: string; agentInputs?: CapturedInput }>;
};
async function captureAgentInputs(
agents: Array<Record<string, unknown>>,
): Promise<CapturedInput[]> {
await createRun({
agents: agents as never,
signal: new AbortController().signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
expect(createMock).toHaveBeenCalledTimes(1);
const callArgs = createMock.mock.calls[0][0] as {
graphConfig: { agents: CapturedInput[] };
};
return callArgs.graphConfig.agents;
}
function headerOf(input: CapturedInput | undefined): string | undefined {
return input?.clientOptions?.configuration?.defaultHeaders?.[AGENT_ID_HEADER];
}
describe('createRun agent-id header resolution', () => {
beforeEach(() => jest.clearAllMocks());
it('resolves the placeholder to the running agent id', async () => {
const [rootInput] = await captureAgentInputs([makeAgent()]);
expect(headerOf(rootInput)).toBe('agent_root');
});
it('resolves a subagent step to the ROOT agent id, not the subagent own id', async () => {
const child = makeAgent({ id: 'agent_child', name: 'Child' });
const root = makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
});
const [rootInput] = await captureAgentInputs([root]);
const childInput = rootInput.subagentConfigs?.find(
(config) => config.type === 'agent_child',
)?.agentInputs;
/** The subagent really is a different agent... */
expect(childInput?.agentId).toBe('agent_child');
/** ...yet the forwarded header carries the id the turn is attributed to. */
expect(headerOf(childInput)).toBe('agent_root');
expect(headerOf(rootInput)).toBe('agent_root');
});
it('resolves to an empty value for an ephemeral (plain-chat) run', async () => {
const [rootInput] = await captureAgentInputs([makeAgent({ id: 'openAI__gpt-4o___My Preset' })]);
expect(headerOf(rootInput)).toBe('');
});
it('leaves headers without the placeholder untouched', async () => {
const [rootInput] = await captureAgentInputs([
makeAgent({
model_parameters: {
model: 'gpt-4o',
configuration: { defaultHeaders: { 'X-Static': 'value' } },
},
}),
]);
expect(rootInput.clientOptions?.configuration?.defaultHeaders).toEqual({ 'X-Static': 'value' });
});
});

View file

@ -1683,6 +1683,56 @@ describe('Azure deployment alias', () => {
expect(azure.headers.get('api-key')).toBe('expanded-azure-key');
});
it('forwards the primary agent id on OpenAI and Azure summarizer headers', async () => {
jest.replaceProperty(process, 'env', { ...process.env, OPENAI_API_KEY: 'openai-summary-key' });
const appConfig = makeAppConfig([]);
appConfig.endpoints!.all = { headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' } };
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'gpt-4.1-mini'],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
};
const compact = async (summarizationConfig: SummarizationConfig) => {
(Run.create as jest.Mock).mockClear();
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig,
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
return requests[0];
};
const openAI = await compact({
provider: EModelEndpoint.openAI,
model: 'gpt-4.1-mini',
parameters: { streaming: false },
});
expect(openAI.url.origin).toBe('https://api.openai.com');
expect(openAI.headers.get('X-Agent-Id')).toBe('agent_1');
const azure = await compact({ model: 'gpt-4.1-mini', parameters: { streaming: false } });
expect(azure.url.origin).toBe('https://summary-instance.openai.azure.com');
expect(azure.headers.get('X-Agent-Id')).toBe('agent_1');
});
it("leaves Azure's reserved URL templates to the summary deployment", async () => {
jest.replaceProperty(process, 'env', {
...process.env,
@ -2387,6 +2437,28 @@ describe('custom-endpoint provider resolution', () => {
expect(configuration.defaultHeaders).toEqual({ 'X-Tenant-ID': 'request-tenant' });
});
it('forwards the primary agent id in custom-endpoint summarization headers', async () => {
const appConfig = makeAppConfig([
{
name: 'Agent Gateway',
baseURL: 'https://gateway.example.com/v1',
apiKey: 'gateway-key',
headers: { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' },
},
]);
const agents = await callAndCapture({
agents: [makeAgent({ id: 'agent_gateway' })],
summarizationConfig: { provider: 'Agent Gateway', model: 'summary-model' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
const configuration = parameters.configuration as Record<string, unknown>;
expect(configuration.defaultHeaders).toEqual({ 'X-Agent-Id': 'agent_gateway' });
});
it('forwards PROXY env var into summarization client configuration', async () => {
const originalProxy = process.env.PROXY;
process.env.PROXY = 'http://proxy.internal:3128';

View file

@ -7,10 +7,10 @@ import type { ClientOptions } from '@librechat/agents';
import type { EndpointDbMethods, OpenAIConfiguration, ServerRequest } from '~/types';
import type { ActivityLabelLLM } from './runtime';
import { getProviderConfig } from '~/endpoints/config/providers';
import { createSafeUser, createSafeAgent } from '~/utils/env';
import { resolveRequestTenantId } from '~/middleware/tenant';
import { resolveConfigHeaders } from '~/utils/headers';
import { omitTitleOptions } from '~/agents/client';
import { createSafeUser } from '~/utils/env';
/** Additive label fields may precede the rebuilt data-provider artifact in a
* package-local typecheck, so keep the endpoint view structural here. */
@ -111,6 +111,7 @@ export function mapCollectedMetadataToUsage(
/** The agent fields the label model resolution needs. */
export interface ActivityLabelAgent {
id?: string;
endpoint?: string;
provider?: string;
model?: string;
@ -485,6 +486,7 @@ export async function resolveActivityLabelModel({
user: createSafeUser(req.user as IUser | undefined),
tenantId: resolveRequestTenantId(req),
body: ids,
agent: createSafeAgent(agent),
});
return {
provider,

View file

@ -31,7 +31,7 @@ import type {
IUser,
FormattedMemoriesResult,
} from '@librechat/data-schemas';
import type { TAttachment, FiltersConfig, MemoryArtifact } from 'librechat-data-provider';
import type { Agent, TAttachment, FiltersConfig, MemoryArtifact } from 'librechat-data-provider';
import type { BaseMessage, ToolMessage } from '@librechat/agents/langchain/messages';
import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import type { Response as ServerResponse } from 'express';
@ -777,6 +777,7 @@ export async function processMemory({
streamId = null,
jobCreatedAt,
user,
primaryAgent,
tenantId,
}: {
res: ServerResponse;
@ -785,6 +786,7 @@ export async function processMemory({
userId: string | ObjectId;
/** Agent partition; omit for the shared personal pool */
agentId?: string;
primaryAgent?: Partial<Agent>;
memory: string;
messageId: string;
conversationId: string;
@ -936,6 +938,7 @@ ${memory ?? 'No existing memories'}`;
user: user ? createSafeUser(user) : undefined,
tenantId,
body: { conversationId, messageId },
agent: primaryAgent,
});
const artifactPromises: Promise<TAttachment | null>[] = [];
@ -1050,6 +1053,7 @@ export async function createMemoryProcessor({
streamId = null,
jobCreatedAt,
user,
primaryAgent,
tenantId,
}: {
res: ServerResponse;
@ -1058,6 +1062,8 @@ export async function createMemoryProcessor({
userId: string | ObjectId;
/** Agent partition; omit for the shared personal pool */
agentId?: string;
/** The primary agent whose turn triggered extraction — see {@link processMemory}. */
primaryAgent?: Partial<Agent>;
memoryMethods: RequiredMemoryMethods;
/** Reuses the request-scoped formatted snapshot for the chat context. */
req?: object;
@ -1139,6 +1145,7 @@ export async function createMemoryProcessor({
setMemory: memoryMethods.setMemory,
deleteMemory: memoryMethods.deleteMemory,
user,
primaryAgent,
tenantId,
});
} catch (error) {

View file

@ -128,6 +128,7 @@ import { buildEffectiveToolApprovalPolicy } from '~/agents/hitl/allow';
import { prepareQueuedCodeFileContext } from '~/files/code/queued';
import { getBuiltInBaseURL } from '~/endpoints/openai/initialize';
import { getProviderConfig } from '~/endpoints/config/providers';
import { createSafeUser, createSafeAgent } from '~/utils/env';
import { buildToolApprovalHooks } from '~/agents/hitl/hooks';
import { getAgentCheckpointer } from '~/agents/checkpointer';
import { getPluginHookSource } from '~/agents/hooks/source';
@ -137,7 +138,6 @@ import { buildHITLRunWiring } from '~/agents/hitl/runtime';
import { buildLangfuseConfig } from '~/langfuse/config';
import { applyTestRunHook } from '~/agents/testHook';
import { isUserProvided } from '~/utils/common';
import { createSafeUser } from '~/utils/env';
/** Expected shape of JSON tool search results */
interface ToolSearchJsonResult {
@ -908,7 +908,12 @@ function resolveOpenAISummarization(
model: string,
appConfig: AppConfig | undefined,
parameters: SummarizationConfig['parameters'],
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
headerContext: {
user?: IUser;
tenantId?: string;
requestBody?: t.RequestBody;
agent?: Partial<Agent>;
},
): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined {
const overrides = summarizationTransportOverrides(parameters);
const baseURL = overrides.baseURL ?? getBuiltInBaseURL(EModelEndpoint.openAI);
@ -947,6 +952,7 @@ function resolveOpenAISummarization(
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
agent: headerContext.agent,
}),
transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents),
},
@ -1040,7 +1046,12 @@ function resolveAzureSummarization(
model: string,
appConfig: AppConfig | undefined,
parameters: SummarizationConfig['parameters'],
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
headerContext: {
user?: IUser;
tenantId?: string;
requestBody?: t.RequestBody;
agent?: Partial<Agent>;
},
source?: RunAgent,
): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined {
const sourceOptions = source?.model_parameters as Partial<t.OAIClientOptions> | undefined;
@ -1088,6 +1099,7 @@ function resolveAzureSummarization(
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
agent: headerContext.agent,
});
const { llmConfig, configOptions } = getOpenAIConfig(
azureOptions.azureOpenAIApiKey,
@ -1173,7 +1185,12 @@ function resolveAzureSummarization(
function resolveSummarizationProvider(
rawProvider: string,
appConfig: AppConfig | undefined,
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
headerContext: {
user?: IUser;
tenantId?: string;
requestBody?: t.RequestBody;
agent?: Partial<Agent>;
},
target: {
model?: string;
parameters?: SummarizationConfig['parameters'];
@ -1239,6 +1256,7 @@ function resolveSummarizationProvider(
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
agent: headerContext.agent,
})
: undefined;
/**
@ -1351,7 +1369,12 @@ function shapeSummarizationConfig(
fallbackModel: string | undefined,
appConfig: AppConfig | undefined,
agentEndpoint: string | undefined,
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
headerContext: {
user?: IUser;
tenantId?: string;
requestBody?: t.RequestBody;
agent?: Partial<Agent>;
},
agent?: RunAgent,
) {
const rawProvider = config?.provider ?? fallbackProvider;
@ -2379,6 +2402,9 @@ export async function createRun({
/** Admin kill switch for the ask tool — see {@link isAskUserQuestionAdminDisabled}. */
const askToolAdminDisabled = isAskUserQuestionAdminDisabled(appConfig);
/** Resolves `{{LIBRECHAT_AGENT_ID}}`; derived once so subagent steps share the turn's id. */
const safePrimaryAgent = createSafeAgent(agents[0]);
// Independently initialized agents must reserve the same live paths before advertising uploads.
const codeFileAgents = new Map<string, RunAgent>();
const visitedCodeFileAgents = new Set<string>();
@ -2442,6 +2468,7 @@ export async function createRun({
user: createSafeUser(user),
tenantId,
body: requestBody,
agent: safePrimaryAgent,
});
const modelParameters = normalizeAgentModelParameters(agent.model_parameters);
@ -2451,7 +2478,7 @@ export async function createRun({
selfModel,
appConfig,
agent.endpoint ?? undefined,
{ user, tenantId, requestBody },
{ user, tenantId, requestBody, agent: safePrimaryAgent },
agent,
);
const summarization = modelCallbacks?.length

View file

@ -1,9 +1,10 @@
import { Types } from 'mongoose';
import { TokenExchangeMethodEnum } from 'librechat-data-provider';
import type { MCPOptions } from 'librechat-data-provider';
import type { Agent, MCPOptions } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import {
createSafeUser,
createSafeAgent,
resolveHeaders,
resolveNestedObject,
processMCPEnv,
@ -2656,3 +2657,161 @@ describe('processMCPEnv OpenID re-authentication signalling', () => {
}
});
});
describe('createSafeAgent', () => {
it('returns an empty object for null/undefined agents', () => {
expect(createSafeAgent(null)).toEqual({});
expect(createSafeAgent(undefined)).toEqual({});
});
it('projects only allowlisted fields, dropping everything else', () => {
const safeAgent = createSafeAgent({
id: 'agent_HTbJ5rDW0kOOK1a5MPBSt',
name: 'Support Bot',
instructions: 'internal system prompt',
author: 'user-123',
} as Partial<Agent>);
expect(safeAgent).toEqual({ id: 'agent_HTbJ5rDW0kOOK1a5MPBSt' });
});
it('omits an absent or null id rather than emitting a null value', () => {
expect(createSafeAgent({})).toEqual({});
expect(createSafeAgent({ id: null })).toEqual({});
});
it('passes an ephemeral id through — the gate belongs to resolution, not projection', () => {
expect(createSafeAgent({ id: 'openAI__gpt-4o___My Preset' })).toEqual({
id: 'openAI__gpt-4o___My Preset',
});
});
});
describe('resolveHeaders agent placeholders', () => {
const agentHeaders = { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' };
const persistedAgent = { id: 'agent_HTbJ5rDW0kOOK1a5MPBSt' };
it('resolves the agent id for a persisted agent', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
agent: persistedAgent,
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('agent_HTbJ5rDW0kOOK1a5MPBSt');
});
it('resolves alongside user and body placeholders without interfering', () => {
const result = resolveHeaders({
headers: {
'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}',
'X-User-Id': '{{LIBRECHAT_USER_ID}}',
'X-Convo': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
'Content-Type': 'application/json',
},
user: { id: 'user-123' },
body: { conversationId: 'convo-abc' },
agent: persistedAgent,
stripUnresolved: true,
});
expect(result).toEqual({
'X-Agent-Id': 'agent_HTbJ5rDW0kOOK1a5MPBSt',
'X-User-Id': 'user-123',
'X-Convo': 'convo-abc',
'Content-Type': 'application/json',
});
});
it('replaces every occurrence within a composite value', () => {
const result = resolveHeaders({
headers: { 'X-Meta': 'agent={{LIBRECHAT_AGENT_ID}};ref={{LIBRECHAT_AGENT_ID}}' },
agent: persistedAgent,
stripUnresolved: true,
});
expect(result['X-Meta']).toBe(
'agent=agent_HTbJ5rDW0kOOK1a5MPBSt;ref=agent_HTbJ5rDW0kOOK1a5MPBSt',
);
});
it('strips the placeholder when no agent context is available', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
user: { id: 'user-123' },
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('');
});
it('strips the placeholder for an ephemeral agent id', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
agent: { id: 'openAI__gpt-4o___My Preset' },
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('');
});
it('never forwards user-authored preset text from an ephemeral id', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
agent: { id: 'openAI__gpt-4o___Marić\r\nX-Injected: 1' },
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('');
});
it('strips the placeholder when the agent id is empty', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
agent: { id: '' },
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('');
});
it('preserves the placeholder by default so staged flows can resolve later', () => {
const result = resolveHeaders({ headers: { ...agentHeaders } });
expect(result['X-Agent-Id']).toBe('{{LIBRECHAT_AGENT_ID}}');
});
it('leaves headers without the placeholder untouched', () => {
const result = resolveHeaders({
headers: { 'Content-Type': 'application/json', 'X-Static': 'value' },
agent: persistedAgent,
stripUnresolved: true,
});
expect(result).toEqual({ 'Content-Type': 'application/json', 'X-Static': 'value' });
});
it('resolves from a full agent projected through createSafeAgent', () => {
const result = resolveHeaders({
headers: { ...agentHeaders },
agent: createSafeAgent({
id: 'agent_HTbJ5rDW0kOOK1a5MPBSt',
name: 'Support Bot',
instructions: 'internal system prompt',
} as Partial<Agent>),
stripUnresolved: true,
});
expect(result['X-Agent-Id']).toBe('agent_HTbJ5rDW0kOOK1a5MPBSt');
});
it('does not resolve an unknown agent field', () => {
const result = resolveHeaders({
headers: { 'X-Agent-Name': '{{LIBRECHAT_AGENT_NAME}}' },
agent: persistedAgent,
stripUnresolved: true,
});
expect(result['X-Agent-Name']).toBe('{{LIBRECHAT_AGENT_NAME}}');
});
});

View file

@ -1,6 +1,6 @@
import { logger } from '@librechat/data-schemas';
import { extractEnvVariable } from 'librechat-data-provider';
import type { MCPOptions } from 'librechat-data-provider';
import { extractEnvVariable, isEphemeralAgentId } from 'librechat-data-provider';
import type { Agent, MCPOptions } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { RequestBody } from '~/types';
import {
@ -150,19 +150,62 @@ export function createSafeUser(
*/
export const ALLOWED_BODY_FIELDS = ['conversationId', 'parentMessageId', 'messageId'] as const;
/**
* List of allowed agent fields that can be used in header placeholders. Kept to
* identifiers the agent owns rather than user-authored content.
*/
const ALLOWED_AGENT_FIELDS = ['id'] as const;
type AllowedAgentField = (typeof ALLOWED_AGENT_FIELDS)[number];
type SafeAgent = Pick<Agent, AllowedAgentField>;
/**
* Any object carrying agent identity fields, so the projection below accepts a
* full `Agent`, a run-shaped agent, or the narrower agent objects the auxiliary
* generation paths pass around, without those callers coupling to `Agent` itself.
*/
type AgentLike = { [K in AllowedAgentField]?: Agent[K] | null };
/**
* Creates a safe agent object containing only allowed fields, mirroring
* `createSafeUser` — call sites project at the boundary rather than hand-building
* a literal, so the allowlist stays the one place that decides what an agent may
* contribute to a header.
*
* @param agent - The agent object to extract safe fields from
* @returns A new object containing only allowed fields
*/
export function createSafeAgent(agent?: AgentLike | null): Partial<SafeAgent> {
if (!agent) {
return {};
}
const safeAgent: Partial<SafeAgent> = {};
for (const field of ALLOWED_AGENT_FIELDS) {
const value = agent[field];
if (value != null) {
Object.assign(safeAgent, { [field]: value });
}
}
return safeAgent;
}
const OPENID_PLACEHOLDER_NAMES = `LIBRECHAT_OPENID_(?:${OPENID_TOKEN_FIELDS.join('|')}|TOKEN)`;
/**
* Matches every placeholder this module knows how to resolve: the enumerated
* `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, and `{{LIBRECHAT_OPENID_*}}`
* names. Deliberately excludes unknown names (a typo'd placeholder staying
* literal is diagnosable) and `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}`, which is
* resolved asynchronously via the OBO flow outside this pipeline.
* `{{LIBRECHAT_USER_*}}`, `{{LIBRECHAT_BODY_*}}`, `{{LIBRECHAT_AGENT_*}}`, and
* `{{LIBRECHAT_OPENID_*}}` names. Deliberately excludes unknown names (a typo'd
* placeholder staying literal is diagnosable) and
* `{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}`, which is resolved asynchronously via the
* OBO flow outside this pipeline.
*/
const RESOLVABLE_PLACEHOLDER_PATTERN = new RegExp(
[
`LIBRECHAT_USER_(?:${ALLOWED_USER_FIELDS.map((field) => field.toUpperCase()).join('|')})`,
`LIBRECHAT_BODY_(?:${ALLOWED_BODY_FIELDS.map((field) => field.toUpperCase()).join('|')})`,
`LIBRECHAT_AGENT_(?:${ALLOWED_AGENT_FIELDS.map((field) => field.toUpperCase()).join('|')})`,
OPENID_PLACEHOLDER_NAMES,
]
.map((names) => `\\{\\{(?:${names})\\}\\}`)
@ -286,6 +329,34 @@ function processBodyPlaceholders(value: string, body: RequestBody): string {
return value;
}
/**
* Replaces agent field placeholders within a string.
* Recognized placeholders: `{{LIBRECHAT_AGENT_<FIELD>}}` where `<FIELD>` ∈ ALLOWED_AGENT_FIELDS.
* Only persisted agents resolve; ephemeral ids are left for a final pass to strip.
*
* @param value - The string value to process
* @param agent - The agent serving the request
* @returns The processed string with placeholders replaced
*/
function processAgentPlaceholders(value: string, agent: Partial<Agent>): string {
if (typeof value !== 'string' || !agent.id || isEphemeralAgentId(agent.id)) {
return value;
}
for (const field of ALLOWED_AGENT_FIELDS) {
const placeholder = `{{LIBRECHAT_AGENT_${field.toUpperCase()}}}`;
if (!value.includes(placeholder)) {
continue;
}
const fieldValue = agent[field];
const replacementValue = fieldValue == null ? '' : String(fieldValue);
value = value.replace(new RegExp(placeholder, 'g'), replacementValue);
}
return value;
}
/**
* Processes a single string value by replacing various types of placeholders
*
@ -293,6 +364,7 @@ function processBodyPlaceholders(value: string, body: RequestBody): string {
* @param customUserVars - Optional custom user variables to replace placeholders
* @param user - Optional user object for replacing user field placeholders
* @param body - Optional request body object for replacing body field placeholders
* @param agent - Optional agent object for replacing agent field placeholders
* @param isHeader - Whether this value will be used in an HTTP header (enables encoding)
* @returns The processed string with all placeholders replaced
*/
@ -301,6 +373,7 @@ function processSingleValue({
customUserVars,
user,
body = undefined,
agent = undefined,
isHeader = false,
dbSourced = false,
beforeCredentialResolution,
@ -309,6 +382,7 @@ function processSingleValue({
customUserVars?: Record<string, string>;
user?: Partial<IUser>;
body?: RequestBody;
agent?: Partial<Agent>;
isHeader?: boolean;
/** When true, only resolve customUserVars — skip env vars, user/OpenID/body placeholders */
dbSourced?: boolean;
@ -373,6 +447,10 @@ function processSingleValue({
value = processBodyPlaceholders(value, body);
}
if (agent) {
value = processAgentPlaceholders(value, agent);
}
return value;
}
@ -632,6 +710,8 @@ export function resolveNestedObject<T = unknown>(options?: {
* @param options.headers - The headers object to process
* @param options.user - Optional user object for replacing user field placeholders (can be partial with just id)
* @param options.body - Optional request body object for replacing body field placeholders
* @param options.agent - Optional agent serving the request, for replacing agent field
* placeholders. Only persisted agents resolve; see `processAgentPlaceholders`.
* @param options.customUserVars - Optional custom user variables to replace placeholders
* @param options.stripUnresolved - When true (final resolution passes only), replaces any
* remaining resolvable placeholders with an empty string so internal template syntax is
@ -643,10 +723,11 @@ export function resolveHeaders(options?: {
headers: Record<string, string> | undefined;
user?: Partial<IUser> | { id: string };
body?: RequestBody;
agent?: Partial<Agent>;
customUserVars?: Record<string, string>;
stripUnresolved?: boolean;
}): Record<string, string> {
const { headers, user, body, customUserVars, stripUnresolved = false } = options ?? {};
const { headers, user, body, agent, customUserVars, stripUnresolved = false } = options ?? {};
const inputHeaders = headers ?? {};
const resolvedHeaders: Record<string, string> = { ...inputHeaders };
@ -658,6 +739,7 @@ export function resolveHeaders(options?: {
customUserVars,
user: user as IUser,
body,
agent,
isHeader: true, // Important: Enable header encoding
});
if (!stripUnresolved) {

View file

@ -1,5 +1,10 @@
import type { RunLLMConfig } from '~/types';
import { mediaTypeEssence, mergeHeaders, resolveConfigHeaders } from './headers';
import {
mergeHeaders,
mediaTypeEssence,
resolveModelHeaders,
resolveConfigHeaders,
} from './headers';
describe('mediaTypeEssence', () => {
it('returns the bare type for a header with no parameters', () => {
@ -211,6 +216,26 @@ describe('resolveConfigHeaders', () => {
expect(llmConfig.configuration?.defaultHeaders).toEqual({ 'X-Tenant-ID': '' });
});
it('resolves the agent id alongside the tenant in one model header', () => {
const llmConfig = {
configuration: {
defaultHeaders: { 'X-Attribution': '{{LIBRECHAT_USER_TENANT_ID}}/{{LIBRECHAT_AGENT_ID}}' },
},
} as unknown as RunLLMConfig;
resolveConfigHeaders({
llmConfig,
user,
tenantId: 'request-tenant',
body,
agent: { id: 'agent_abc' },
});
expect(llmConfig.configuration?.defaultHeaders).toEqual({
'X-Attribution': 'request-tenant/agent_abc',
});
});
it('leaves configs without header maps untouched', () => {
const llmConfig = { model: 'gpt-4o', configuration: {} } as unknown as RunLLMConfig;
expect(() => resolveConfigHeaders({ llmConfig, user, body })).not.toThrow();
@ -249,3 +274,18 @@ describe('resolveConfigHeaders', () => {
expect(llmConfig.configuration?.defaultHeaders).toEqual({ 'X-LibreChat-User': '' });
});
});
describe('resolveModelHeaders', () => {
it('resolves the agent id in a standalone header map without mutating it', () => {
const headers = { 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' };
const resolved = resolveModelHeaders({
headers,
user: { id: 'user-123' },
agent: { id: 'agent_abc' },
});
expect(resolved).toEqual({ 'X-Agent-Id': 'agent_abc' });
expect(headers).toEqual({ 'X-Agent-Id': '{{LIBRECHAT_AGENT_ID}}' });
});
});

View file

@ -1,4 +1,5 @@
import type { AnthropicClientOptions } from '@librechat/agents';
import type { Agent } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { RequestBody, RunLLMConfig } from '~/types';
import { resolveHeaders } from './env';
@ -111,18 +112,21 @@ export function resolveModelHeaders({
user,
tenantId,
body,
agent,
customUserVars,
}: {
headers: Record<string, string> | undefined;
user?: Partial<IUser> | { id: string };
tenantId?: string;
body?: RequestBody;
agent?: Partial<Agent>;
customUserVars?: Record<string, string>;
}): Record<string, string> {
const resolved = resolveHeaders({
headers,
user,
body,
agent,
customUserVars,
stripUnresolved: true,
});
@ -165,6 +169,7 @@ export function resolveConfigHeaders({
user,
tenantId,
body,
agent,
customUserVars,
}: {
/** Partial: this only reads the three provider header carriers, so
@ -176,6 +181,7 @@ export function resolveConfigHeaders({
/** Authoritative request tenant used only for model-header templates. */
tenantId?: string;
body?: RequestBody;
agent?: Partial<Agent>;
customUserVars?: Record<string, string>;
}): void {
if (llmConfig == null) {
@ -186,7 +192,7 @@ export function resolveConfigHeaders({
if (resolvedHeaderMaps.has(headers)) {
return headers;
}
const resolved = resolveModelHeaders({ headers, user, tenantId, body, customUserVars });
const resolved = resolveModelHeaders({ headers, user, tenantId, body, agent, customUserVars });
resolvedHeaderMaps.add(resolved);
return resolved;
};