LibreChat/packages/api/src/agents/run.ts
lia-by-librechat[bot] d55dbc3bd8
🔱 feat: Simplify Steering Controls to Three Modes (#16759)
* 🔱 feat: Simplify Steering Controls to Three Modes

* Preserve Admitted Artifacts During Interrupts

* Preserve Result Admission Across Interrupts

* Gate Interrupt for Provider-Hosted Tools

* Match Interrupt Hints to Availability

---------

Co-authored-by: Lia <lia@librechat.ai>
2026-10-05 06:46:59 -04:00

3157 lines
123 KiB
TypeScript

import { randomUUID } from 'crypto';
import { logger } from '@librechat/data-schemas';
import { ensureHandler } from '@langchain/core/callbacks/manager';
import { Run, Providers, Constants, GraphEvents, HookRegistry } from '@librechat/agents';
import {
KnownEndpoints,
EModelEndpoint,
ReasoningEffort,
MAX_SUBAGENT_DEPTH,
MAX_SUBAGENT_RUN_CONFIGS,
extractEnvVariable,
providerEndpointMap,
normalizeEndpointName,
mapModelToAzureConfig,
resolveUseResponsesApi,
} from 'librechat-data-provider';
import type {
SummarizationConfig as AgentSummarizationConfig,
MultiAgentGraphConfig,
ContextPruningConfig,
CompactionSemanticIndex,
OpenAIClientOptions,
StandardGraphConfig,
StreamPreemption,
LCToolRegistry,
SubagentConfig,
SubagentResolveContext,
SubagentConfigEntry,
HookCallback,
AgentInputs,
FallbackConfig,
GenericTool,
RunConfig,
IState,
LCTool,
SubagentTaskConfig,
} from '@librechat/agents';
import type {
Agent,
ImageDetail,
TAzureConfig,
CodeApprovalMode,
TAgentsEndpoint,
AgentModelParameters,
AgentSubagentsConfig,
AgentSubagentGraph,
ReasoningResponseKey,
SummarizationConfig,
TurnFileConsumers,
} from 'librechat-data-provider';
import type { AppConfig, IAgentFadingTier, IUser } from '@librechat/data-schemas';
import type { CallbackHandlerMethods } from '@langchain/core/callbacks/base';
import type { ToolApprovalGrantStorage } from 'librechat-data-provider';
import type { BaseMessage } from '@librechat/agents/langchain/messages';
import type { Callbacks } from '@langchain/core/callbacks/manager';
import type { TerminalSteerHook, SteerPreemption } from '~/agents/steering/runtime';
import type { ModelBoundChatModelCallback } from '~/middleware/modelBoundContent';
import type { ScheduledMCPPolicyError } from '~/schedules/authorization/policy';
import type { ScheduleMCPExecution } from '~/schedules/authorization/execution';
import type { ModelErrorTrackerCallback } from '~/agents/failures/tracker';
import type { ToolInputValidationError } from '~/agents/toolValidation';
import type { ResolvedToolApprovalHook } from '~/agents/hitl/hooks';
import type { LangfuseTraceContext } from '~/langfuse/identity';
import type { ResolvedAlwaysApplySkill } from '~/agents/skills';
import type { CodeExecutionContext } from '~/agents/execution';
import type { SubagentCodeHostArgSpecs } from '~/code/targets';
import type { MCPToolAlias } from '~/tools/classification';
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 { RunFadingTiers } from './fading';
import type * as t from '~/types';
import {
assertAttachedCodeEnvironmentApprovalSupported,
collectNativeEditFileAgentIds,
collectAttachedCodeEnvironmentAgentIds,
collectAttachedCodeEnvironmentPolicySettings,
collectAttachedCodeApprovalPolicies,
createAttachedCodeEnvironmentPolicyHook,
resolveAttachedCodeApprovalMode,
} from '~/agents/hitl/byom';
import {
CHECK_BACKGROUND_TASK_NAME,
registerBackgroundTaskTool,
stripBackgroundFromToolRegistry,
stripBackgroundFromToolDefinitions,
} from '~/agents/background';
import {
createSubagentWakeupHandleHook,
agentUsesSubagentCompletionWakeups,
usesSubagentCompletionWakeups,
} from '~/agents/subagentDelivery';
import {
resolveStreamLimits,
resolveModelTransportTimeouts,
resolveSubagentMaxTurns,
resolveRecursionLimit,
} from '~/agents/config';
import {
isSteeringSupported,
isSteerPreemptSupported,
isSteerTerminalContinuationSupported,
} from '~/agents/steering/runtime';
import {
ASK_USER_QUESTION_TOOL_NAME,
createAskUserQuestionTool,
} from '~/agents/hitl/askUserQuestionTool';
import {
createRunFileTools,
eventOnlyRunFileTools,
isRunFileSharingSupported,
} from './files/runtime';
import { resolveToolApprovalPolicy, exemptAskUserQuestionFromApproval } from '~/agents/hitl/policy';
import { applyCustomHandoffPromptKeyCompatibility } from '~/agents/handoffPromptKeyCompatibility';
import { stripIntentFromToolRegistry, stripIntentFromToolDefinitions } from '~/agents/intent';
import { createAgentToolApprovalSession, bindRunToolApprovalSession } from './hitl/modes';
import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils/headers';
import { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools';
import { extractDefaultParams, resolveReasoningParams } from '~/endpoints/openai/llm';
import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';
import { createScheduledMCPRunPolicy } from '~/schedules/authorization/run';
import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from '~/agents/tools';
import { buildAgentInitialToolSessions } from '~/agents/codeFilesSession';
import { getDirectDispatcher, getProxyDispatcher } from '~/utils/proxy';
import { getAzureCredentials, constructAzureURL } from '~/utils/azure';
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 { buildToolApprovalHooks } from '~/agents/hitl/hooks';
import { getAgentCheckpointer } from '~/agents/checkpointer';
import { getPluginHookSource } from '~/agents/hooks/source';
import { getOpenAIConfig } from '~/endpoints/openai/config';
import { createStepBudgetHook } from '~/agents/stepBudget';
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 {
found?: number;
tools?: Array<{ name: string }>;
}
/**
* Parses tool names from JSON-formatted tool_search output.
* Format: { "found": N, "tools": [{ "name": "tool_name", ... }], ... }
*
* @param content - The JSON string content
* @param discoveredTools - Set to add discovered tool names to
* @returns true if parsing succeeded, false otherwise
*/
function parseToolSearchJson(content: string, discoveredTools: Set<string>): boolean {
try {
const parsed = JSON.parse(content) as ToolSearchJsonResult;
if (!parsed.tools || !Array.isArray(parsed.tools)) {
return false;
}
for (const tool of parsed.tools) {
if (tool.name && typeof tool.name === 'string') {
discoveredTools.add(tool.name);
}
}
return parsed.tools.length > 0;
} catch {
return false;
}
}
/**
* Parses tool names from legacy text-formatted tool_search output.
* Format: "- tool_name (score: X.XX)"
*
* @param content - The text content
* @param discoveredTools - Set to add discovered tool names to
*/
function parseToolSearchLegacy(content: string, discoveredTools: Set<string>): void {
const toolNameRegex = /^- ([^\s(]+)\s*\(score:/gm;
let match: RegExpExecArray | null;
while ((match = toolNameRegex.exec(content)) !== null) {
const toolName = match[1];
if (toolName) {
discoveredTools.add(toolName);
}
}
}
/**
* Extracts discovered tool names from message history by parsing tool_search results.
* When the LLM calls tool_search, the result contains tool names that were discovered.
* These tools should have defer_loading overridden to false on subsequent turns.
*
* Supports both:
* - New JSON format: { "tools": [{ "name": "tool_name" }] }
* - Legacy text format: "- tool_name (score: X.XX)"
*
* @param messages - The conversation message history
* @returns Set of tool names that were discovered via tool_search
*/
export function extractDiscoveredToolsFromHistory(messages: BaseMessage[]): Set<string> {
const discoveredTools = new Set<string>();
for (const message of messages) {
const msgType = message._getType?.() ?? message.constructor?.name ?? '';
if (msgType !== 'tool') {
continue;
}
const name = (message as { name?: string }).name;
if (name !== Constants.TOOL_SEARCH) {
continue;
}
const content = message.content;
if (typeof content !== 'string') {
continue;
}
/** Try JSON format first (new), fall back to regex (legacy) */
if (!parseToolSearchJson(content, discoveredTools)) {
parseToolSearchLegacy(content, discoveredTools);
}
}
return discoveredTools;
}
/** MCP key-spelling aliases each run knows, including those its lazy subagents reported. */
const runMCPToolAliases = new WeakMap<object, readonly MCPToolAlias[]>();
/** The run's live alias list, so a pause can be judged against the aliases the run used. */
export function getRunMCPToolAliases(run: object | null | undefined): readonly MCPToolAlias[] {
return run == null ? [] : (runMCPToolAliases.get(run) ?? []);
}
export interface RunDiscoverySnapshot {
getDiscoveredTools?: () => string[];
getRunMessages?: () => BaseMessage[] | undefined;
}
/** Reads canonical run discovery state, with best-effort history parsing for older releases. */
export function getRunDiscoveredTools(run: RunDiscoverySnapshot): string[] {
if (typeof run.getDiscoveredTools === 'function') {
const discoveredTools = run.getDiscoveredTools();
if (Array.isArray(discoveredTools)) {
return Array.from(new Set(discoveredTools));
}
}
if (typeof run.getRunMessages !== 'function') {
return [];
}
const messages = run.getRunMessages();
if (!Array.isArray(messages) || messages.length === 0) {
return [];
}
return Array.from(extractDiscoveredToolsFromHistory(messages));
}
/**
* Extracts skill names that were invoked in previous turns from raw message payload.
* Scans assistant messages for tool_call content parts where name === 'skill'.
* Works with TPayload (raw message objects) so it can run before formatAgentMessages.
*
* @param payload - The raw conversation message payload
* @returns Set of skill names that were previously invoked
*/
export function extractInvokedSkillsFromPayload(
payload: Array<Partial<{ role: string; content: unknown }>>,
): Set<string> {
const invokedSkills = new Set<string>();
for (const message of payload) {
if (message.role !== 'assistant') {
continue;
}
const content = message.content;
if (!Array.isArray(content)) {
continue;
}
for (const part of content) {
if (
part == null ||
typeof part !== 'object' ||
(part as { type?: string }).type !== 'tool_call'
) {
continue;
}
const toolCall = (part as { tool_call?: { name?: string; args?: unknown } }).tool_call;
if (toolCall?.name !== Constants.SKILL_TOOL) {
continue;
}
const rawArgs = toolCall.args;
const args =
typeof rawArgs === 'string'
? (() => {
try {
return JSON.parse(rawArgs) as Record<string, unknown>;
} catch {
return {};
}
})()
: (rawArgs as Record<string, unknown> | undefined);
const skillName = args?.skillName;
if (typeof skillName === 'string' && skillName.length > 0) {
invokedSkills.add(skillName);
}
}
}
return invokedSkills;
}
/**
* Overrides defer_loading to false for tools that were already discovered via tool_search.
* This prevents the LLM from having to re-discover tools on every turn.
*
* @param toolRegistry - The tool registry to modify (mutated in place)
* @param discoveredTools - Set of tool names that were previously discovered
* @returns Number of tools that had defer_loading overridden
*/
export function overrideDeferLoadingForDiscoveredTools(
toolRegistry: LCToolRegistry,
discoveredTools: Set<string>,
): number {
let overrideCount = 0;
for (const toolName of discoveredTools) {
const toolDef = toolRegistry.get(toolName);
if (toolDef && toolDef.defer_loading === true) {
toolDef.defer_loading = false;
overrideCount++;
}
}
return overrideCount;
}
const customProviders = new Set([
Providers.XAI,
Providers.DEEPSEEK,
Providers.MOONSHOT,
Providers.OPENROUTER,
KnownEndpoints.ollama,
]);
type AgentReasoningKey = 'reasoning_content' | 'reasoning';
function includesOpenRouter(value?: string | null): boolean {
return typeof value === 'string' && value.toLowerCase().includes(KnownEndpoints.openrouter);
}
export function getReasoningKey(
provider: Providers,
llmConfig: t.RunLLMConfig,
agentEndpoint?: string | null,
customReasoningKey?: ReasoningResponseKey,
): AgentReasoningKey {
if (customReasoningKey) {
return customReasoningKey as AgentReasoningKey;
}
let reasoningKey: AgentReasoningKey = 'reasoning_content';
if (provider === Providers.GOOGLE) {
reasoningKey = 'reasoning';
} else if (
includesOpenRouter(llmConfig.configuration?.baseURL) ||
includesOpenRouter(agentEndpoint)
) {
reasoningKey = 'reasoning';
} else if (
(llmConfig as OpenAIClientOptions).useResponsesApi === true &&
(provider === Providers.OPENAI || provider === Providers.AZURE)
) {
reasoningKey = 'reasoning';
}
return reasoningKey;
}
const DEEPSEEK_MODEL_PATTERN = /^deepseek(?:[-/]|$)/i;
const OPENROUTER_LATEST_ROUTING_PREFIX = /^~/;
function matchesDeepSeekModel(model?: string | null): boolean {
if (typeof model !== 'string' || model.length === 0) {
return false;
}
return DEEPSEEK_MODEL_PATTERN.test(model.replace(OPENROUTER_LATEST_ROUTING_PREFIX, ''));
}
/**
* Whether the (provider, model) pair targets DeepSeek's thinking-mode
* tool-calling contract, which requires `reasoning_content` to be replayed
* on every prior assistant message that emitted `tool_calls`.
* @see https://api-docs.deepseek.com/guides/thinking_mode#tool-calls
*/
export function isDeepSeekReasoningProvider(
provider: string | Providers | undefined | null,
model?: string | null,
): boolean {
if (typeof provider === 'string' && provider.length > 0) {
const normalized = provider.toLowerCase();
if (normalized === Providers.DEEPSEEK) {
return true;
}
if (normalized === Providers.OPENROUTER) {
return matchesDeepSeekModel(model);
}
}
return matchesDeepSeekModel(model);
}
/**
* Whether prior assistant tool-call messages should have `reasoning_content`
* reconstructed when reformatting persisted history (cross-turn replay): either
* DeepSeek thinking-mode (#13366) or a custom OpenAI-compatible endpoint that
* opted in via `customParams.includeReasoningHistory` (e.g. Xiaomi MiMo, Kimi).
*/
export function shouldReplayReasoningContent(
agent?: {
provider?: string | Providers | null;
model?: string | null;
model_parameters?: { model?: string | null } | null;
includeReasoningHistory?: boolean | null;
} | null,
): boolean {
if (agent == null) {
return false;
}
if (agent.includeReasoningHistory === true) {
return true;
}
return isDeepSeekReasoningProvider(agent.provider, agent.model_parameters?.model ?? agent.model);
}
type RunAgent = Omit<Agent, 'tools'> & {
provisionState?: ProvisionState;
fileConsumers?: TurnFileConsumers;
azureOptions?: t.AzureOptions;
tools?: GenericTool[];
maxContextTokens?: number;
/** Pre-ratio context budget from initializeAgent. */
baseContextTokens?: number;
useLegacyContent?: boolean;
imageDetail?: ImageDetail;
toolContextMap?: Record<string, unknown>;
dynamicToolContextMap?: Record<string, unknown>;
toolRegistry?: LCToolRegistry;
/** Serializable tool definitions for event-driven execution */
toolDefinitions?: LCTool[];
/** Precomputed flag indicating if any tools have defer_loading enabled */
hasDeferredTools?: boolean;
/** Both-direction identity aliases for MCP tools whose key spelling changed */
mcpToolAliases?: MCPToolAlias[];
/** Names of tools injected with the `run_in_background` param (excluded from eager execution). */
backgroundToolNames?: string[];
/** Names of tools with the host-injected `intent` param (stripped from self-spawn inputs). */
intentToolNames?: string[];
/** Marker-verified tool names whose intent labels are safe compaction guidance. */
semanticIntentToolNames?: string[];
/**
* Per-agent codeenv gate set by `initializeAgent`: admin-level
* `execute_code` capability AND the agent actually requested
* `execute_code` in its tools. Used here to enable
* `RunConfig.toolOutputReferences` only on runs where the bash tool
* is actually registered.
*/
codeEnvAvailable?: boolean;
/**
* Per-agent stateful-session gate set by `initializeAgent`: the admin
* `stateful_code_sessions` capability AND the agent's builder opt-in AND
* `codeEnvAvailable`. Carried into per-agent tool loading and prewarming.
*/
statefulCodeSessions?: boolean;
/** Per-agent stateful workspace sharing scope. */
statefulCodeEnvironment?: Agent['stateful_code_environment'];
/** Trusted partition for transient code session ids and file references. */
codeSessionKey?: string;
/** Trusted Code API route selected during initialization. */
codeExecutionContext?: CodeExecutionContext;
/** Whether this initialized agent can route skills/ writes to persistent skill storage. */
skillAuthoringAvailable?: boolean;
/** Optional per-agent summarization overrides */
summarization?: SummarizationConfig;
/** Response field to read model reasoning from for custom OpenAI-compatible endpoints. */
reasoningKey?: ReasoningResponseKey;
/** Whether to reconstruct `reasoning_content` from persisted history across turns. */
includeReasoningHistory?: boolean;
/**
* Maximum characters allowed in a single tool result before truncation.
* Overrides the default computed from maxContextTokens.
*/
maxToolResultChars?: number;
/** Initialized subagent configs (loaded by initialize.js from agent.subagents.agent_ids). */
subagentAgentConfigs?: RunAgent[];
/**
* Inert, VIEW-checked descriptors for explicit children that are initialized
* only after the SDK selects them. These resolvers are request-scoped: they
* may use the active request's authorization and tool-loading context.
*/
lazySubagentConfigs?: LazySubagentAgent[];
/** All-or-nothing saved-agent teams resolved by initialize.js. */
subagentGraphConfigs?: Array<{
definition: AgentSubagentGraph;
memberConfigs: RunAgent[];
}>;
/** Member-scoped always-apply skills resolved during agent initialization. */
alwaysApplySkillPrimes?: ResolvedAlwaysApplySkill[];
/** Source subagent spawning configuration (enabled / allowSelf / agent_ids). */
subagents?: AgentSubagentsConfig;
};
type LazySubagentAgent = Pick<
RunAgent,
| 'id'
| 'name'
| 'description'
| 'provider'
| 'model'
| 'model_parameters'
| 'recursion_limit'
| 'subagents'
| 'codeEnvAvailable'
| 'statefulCodeSessions'
| 'statefulCodeEnvironment'
| 'codeExecutionContext'
| 'codeSessionKey'
| 'skillAuthoringAvailable'
| 'includeReasoningHistory'
| 'mcpToolAliases'
> & {
configId: string;
/** Per-call machine choices declared on the child's subagent call. */
subagentHostArgs?: SubagentCodeHostArgSpecs;
/** The routes behind those choices, for run-wide gates and approval bindings. */
codeExecutionChoices?: CodeExecutionContext[];
subagentAgentConfigs?: RunAgent[];
lazySubagentConfigs?: LazySubagentAgent[];
/** Lightweight graph-member metadata used only by run-wide capability gates. */
subagentGraphMemberMetadata?: SubagentTreeNode[];
resolve: (context: SubagentResolveContext) => Promise<RunAgent>;
/**
* Wraps the whole selection, through the inputs handed to the SDK, so host state the
* call reserved is kept only when the child is actually exposed.
*/
settle?: <T>(context: SubagentResolveContext, resolveInputs: () => Promise<T>) => Promise<T>;
};
type SubagentTreeNode = Pick<
RunAgent,
| 'id'
| 'provider'
| 'model'
| 'model_parameters'
| 'codeEnvAvailable'
| 'statefulCodeSessions'
| 'statefulCodeEnvironment'
| 'codeExecutionContext'
| 'codeSessionKey'
| 'skillAuthoringAvailable'
| 'includeReasoningHistory'
| 'mcpToolAliases'
> & {
codeExecutionChoices?: CodeExecutionContext[];
subagentAgentConfigs?: SubagentTreeNode[];
lazySubagentConfigs?: SubagentTreeNode[];
subagentGraphMemberMetadata?: SubagentTreeNode[];
subagentGraphConfigs?: Array<{ memberConfigs: SubagentTreeNode[] }>;
};
function isNonEmptyString(value: unknown): value is string {
return typeof value === 'string' && value.trim().length > 0;
}
const UNRESOLVED_ENV_VAR_PLACEHOLDER = /\$\{[^}]+\}/;
function hasUnresolvedPlaceholder(value: string): boolean {
return UNRESOLVED_ENV_VAR_PLACEHOLDER.test(value);
}
function isPlainObject(value: unknown): value is Record<string, unknown> {
return value != null && typeof value === 'object' && !Array.isArray(value);
}
const nullableAgentModelParameterKeys = [
'temperature',
'maxContextTokens',
'max_context_tokens',
'max_output_tokens',
'top_p',
'frequency_penalty',
'presence_penalty',
] satisfies Array<keyof AgentModelParameters>;
function normalizeAgentModelParameters(
modelParameters: AgentModelParameters | undefined,
): Partial<AgentModelParameters> | undefined {
if (!modelParameters) {
return undefined;
}
const normalized: Partial<AgentModelParameters> = { ...modelParameters };
for (const key of nullableAgentModelParameterKeys) {
if (normalized[key] === null) {
delete normalized[key];
}
}
return normalized;
}
/**
* Merges user-supplied summarization parameters on top of endpoint-resolved
* overrides. User params win for top-level keys; `configuration` is
* deep-merged so user additions (e.g. `defaultQuery`) don't wipe out the
* resolved `baseURL`/`defaultHeaders`/`fetchOptions`. When transport resolution already
* consumed the user's URL, retain its normalized form instead of restoring the raw template.
*/
function mergeParameters(
overrides: SummarizationClientOverrides,
userParams: SummarizationConfig['parameters'],
resolvedTransport = false,
): Record<string, unknown> {
const merged: Record<string, unknown> = { ...overrides, ...(userParams ?? {}) };
const userConfiguration = (userParams as Record<string, unknown> | undefined)?.configuration;
if (isPlainObject(overrides.configuration) && isPlainObject(userConfiguration)) {
merged.configuration = {
...overrides.configuration,
...userConfiguration,
...(resolvedTransport ? { baseURL: overrides.configuration.baseURL } : {}),
defaultHeaders: mergeHeaders(
overrides.configuration.defaultHeaders as Record<string, string> | undefined,
userConfiguration.defaultHeaders as Record<string, string> | undefined,
),
defaultQuery: {
...(isPlainObject(overrides.configuration.defaultQuery)
? overrides.configuration.defaultQuery
: {}),
...(isPlainObject(userConfiguration.defaultQuery) ? userConfiguration.defaultQuery : {}),
},
};
}
return merged;
}
/** `model_parameters` is the agent's resolved `llmConfig`, whose kwargs the schema type omits. */
function agentModelKwargs(
modelParameters: AgentModelParameters | undefined,
): Record<string, unknown> | undefined {
if (modelParameters == null || !('modelKwargs' in modelParameters)) {
return undefined;
}
return isPlainObject(modelParameters.modelKwargs) ? modelParameters.modelKwargs : undefined;
}
/**
* `getOpenAILLMConfig` carries an Azure Astra deployment alias in
* `modelKwargs.model`, which langchain spreads after `model`. The SDK's
* same-provider summarizer copies the agent's client options and overrides only
* `model`, so a summarizer on another model would still reach the agent's
* deployment. Hand it the agent's kwargs without the alias.
*/
function summarizationModelKwargs(
agentKwargs: Record<string, unknown> | undefined,
agentModel: string | undefined,
summarizationModel: string | undefined,
): Record<string, unknown> | undefined {
if (agentKwargs == null || !('model' in agentKwargs)) {
return undefined;
}
if (!isNonEmptyString(summarizationModel) || summarizationModel === agentModel) {
return undefined;
}
const { model: _alias, ...kwargs } = agentKwargs;
return kwargs;
}
/**
* Mirrors `getOpenAIConfig`'s `llmConfig` shape (plus its `configOptions`
* assigned to `configuration`). Index signature covers fields that the
* helper emits dynamically per provider variant.
*/
interface SummarizationClientOverrides {
apiKey?: string;
streaming?: boolean;
configuration?: t.OpenAIConfiguration;
[key: string]: unknown;
}
/**
* A user-supplied base URL in `summarization.parameters` points the summarizer
* at a gateway whose contract is not the built-in provider's, so no built-in
* request shaping may be claimed for it.
*/
function hasBaseURLOverride(parameters: SummarizationConfig['parameters']): boolean {
if (!isPlainObject(parameters)) {
return false;
}
const params = parameters as Record<string, unknown>;
if (isNonEmptyString(params.baseURL)) {
return true;
}
return isPlainObject(params.configuration) && 'baseURL' in params.configuration;
}
/**
* The scalar `reasoning_effort` the yaml schema accepts, when it names a known
* effort. `getOpenAIConfig` reads the effort from `modelOptions` — the merged
* `parameters` reach it too late — so a summarizer that configures one has to
* hand it over for the same API routing the agent flow performs.
*/
function summarizationReasoningEffort(
parameters: SummarizationConfig['parameters'],
): ReasoningEffort | undefined {
if (!isPlainObject(parameters)) {
return undefined;
}
const effort = (parameters as Record<string, unknown>).reasoning_effort;
const known = Object.values(ReasoningEffort) as string[];
return typeof effort === 'string' && known.includes(effort)
? (effort as ReasoningEffort)
: undefined;
}
/**
* Builds the model-specific request shaping a built-in provider's client needs,
* for the cross-provider case where the SDK builds that client from these
* parameters alone.
*
* The custom-endpoint path below already runs `getOpenAIConfig`; built-in
* providers skipped it entirely, so a summarizer never learned which API its
* model takes or whether its endpoint is first-party — and the agents SDK
* defaults its model-specific constraints off without that declaration
* (LibreChat#15598).
*
* Credentials and base URLs are not returned: the SDK still resolves them as
* before. Cross-provider OpenAI-family clients do receive the Agent transport
* timeout policy, even when a URL override prevents built-in request shaping.
*/
function resolveBuiltInClientOverrides(
provider: string,
target: {
model?: string;
parameters?: SummarizationConfig['parameters'];
agentProvider?: string;
},
appConfig: AppConfig,
): SummarizationClientOverrides | undefined {
const { model, parameters } = target;
/**
* Mirrors the SDK's own condition: when the summarization provider matches the
* agent's, `buildSummarizationClientConfig` spreads the agent's resolved client
* options and these parameters layer on top. A custom-endpoint agent is
* normalized to the `openAI` provider while keeping its own endpoint name, so
* declaring built-in constraints here would claim OpenAI's contract for that
* gateway.
*/
if (provider === target.agentProvider) {
return undefined;
}
let transportOverrides: SummarizationClientOverrides | undefined;
if (provider === Providers.OPENAI || provider === Providers.AZURE) {
const timeouts = resolveModelTransportTimeouts(appConfig.endpoints?.agents);
transportOverrides = {
configuration: {
fetchOptions: {
dispatcher:
getProxyDispatcher(process.env.PROXY, timeouts) ?? getDirectDispatcher(timeouts),
},
},
};
}
const baseURL = getBuiltInBaseURL(provider);
/** URL overrides still get timeouts, but must not inherit first-party request shaping. */
if (!isNonEmptyString(model) || hasBaseURLOverride(parameters) || isUserProvided(baseURL)) {
return transportOverrides;
}
const { llmConfig } = getOpenAIConfig(
'',
{
modelOptions: { model, reasoning_effort: summarizationReasoningEffort(parameters) },
reverseProxyUrl: baseURL,
},
provider,
);
const {
apiKey: _apiKey,
model: _model,
modelName: _modelName,
streaming: _streaming,
...shaping
} = llmConfig;
return Object.keys(shaping).length > 0
? { ...shaping, ...transportOverrides }
: transportOverrides;
}
/**
* Memory bound for the warning deduplication below, not an operator setting: it only decides when a
* warning for one of more than this many distinct, concurrently recurring problems is logged again.
*/
const MAX_UNRESOLVED_SUMMARIZATION_WARNINGS = 256;
/** Reported summarization misconfigurations per tenant, least recently seen first. */
const unresolvedSummarizationWarnings = new Set<string>();
function warnUnresolvedSummarization(message: string, tenantId?: string): void {
const key = `${tenantId ?? ''}\n${message}`;
if (unresolvedSummarizationWarnings.delete(key)) {
unresolvedSummarizationWarnings.add(key);
return;
}
if (unresolvedSummarizationWarnings.size >= MAX_UNRESOLVED_SUMMARIZATION_WARNINGS) {
const [leastRecentlySeen] = unresolvedSummarizationWarnings;
unresolvedSummarizationWarnings.delete(leastRecentlySeen);
}
unresolvedSummarizationWarnings.add(key);
if (tenantId == null) {
logger.warn(`[createRun] ${message}`);
return;
}
logger.warn(`[createRun] ${message}`, { tenantId });
}
/** Azure base URL templates the client fills from its own options rather than the environment. */
const AZURE_URL_TEMPLATE = /(\$\{(?:INSTANCE_NAME|DEPLOYMENT_NAME)\})/;
/** The URL's segments around Azure's reserved templates, which sit at the odd indexes. */
function splitAzureURLTemplates(url: string): string[] {
return url.split(AZURE_URL_TEMPLATE);
}
/** Expands environment references in a URL, leaving Azure's reserved templates for an Azure client. */
function expandTransportURL(url: string, targetsAzure: boolean): string {
if (!targetsAzure) {
return extractEnvVariable(url);
}
return splitAzureURLTemplates(url)
.map((segment, index) => (index % 2 === 1 ? segment : extractEnvVariable(segment)))
.join('');
}
/**
* Admin-authored transport values may reference environment variables, as endpoint credentials
* do. Expanded once, before resolution and before the parameters are layered over the client.
*/
function expandSummarizationTransport(
parameters: SummarizationConfig['parameters'],
targetsAzure: boolean,
): SummarizationConfig['parameters'] {
if (!isPlainObject(parameters)) {
return parameters;
}
const params = parameters as Record<string, unknown>;
const expanded: Record<string, unknown> = { ...params };
if (typeof params.apiKey === 'string') {
expanded.apiKey = extractEnvVariable(params.apiKey);
}
if (typeof params.baseURL === 'string') {
expanded.baseURL = expandTransportURL(params.baseURL, targetsAzure);
}
if (isPlainObject(params.configuration) && typeof params.configuration.baseURL === 'string') {
expanded.configuration = {
...params.configuration,
baseURL: expandTransportURL(params.configuration.baseURL, targetsAzure),
};
}
return expanded as SummarizationConfig['parameters'];
}
/** The base URL and API key a summarization target's own parameters set, which replace the resolved ones. */
function summarizationTransportOverrides(parameters: SummarizationConfig['parameters']): {
baseURL?: string;
apiKey?: string;
} {
const configuration = (parameters as Record<string, unknown> | undefined)?.configuration;
const configurationBaseURL =
isPlainObject(configuration) && typeof configuration.baseURL === 'string'
? configuration.baseURL
: undefined;
return {
baseURL:
configurationBaseURL ??
(typeof parameters?.baseURL === 'string' ? parameters.baseURL : undefined),
apiKey: typeof parameters?.apiKey === 'string' ? parameters.apiKey : undefined,
};
}
/** Reject unusable transports while shaping the run, before a compaction client can fail it. */
function isSummarizationURLAvailable(baseURL: string | undefined, azure?: t.AzureOptions): boolean {
if (baseURL == null) {
return azure == null || isNonEmptyString(azure.azureOpenAIApiInstanceName);
}
try {
const url = new URL(constructAzureURL({ baseURL, azureOptions: azure }));
return (
(url.protocol === 'https:' || url.protocol === 'http:') && !hasUnresolvedPlaceholder(url.href)
);
} catch {
return false;
}
}
/**
* Azure Responses shares OpenAI's SDK provider, so switching endpoints must replace its transport.
* Returns `undefined` when the OpenAI credentials cannot be resolved without a per-user lookup.
*/
function resolveOpenAISummarization(
model: string,
appConfig: AppConfig | undefined,
parameters: SummarizationConfig['parameters'],
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined {
const overrides = summarizationTransportOverrides(parameters);
const baseURL = overrides.baseURL ?? getBuiltInBaseURL(EModelEndpoint.openAI);
const apiKey = overrides.apiKey ?? process.env.OPENAI_API_KEY;
if (
!apiKey ||
!isSummarizationURLAvailable(baseURL) ||
isUserProvided(baseURL) ||
isUserProvided(apiKey) ||
hasUnresolvedPlaceholder(apiKey) ||
(baseURL != null && hasUnresolvedPlaceholder(baseURL))
) {
warnUnresolvedSummarization(
`Summarization with OpenAI model "${model}" is disabled for Azure OpenAI agents: it needs a server-configured OpenAI API key and base URL.`,
headerContext.tenantId,
);
return undefined;
}
const headers = mergeHeaders(
appConfig?.endpoints?.all?.headers,
appConfig?.endpoints?.openAI?.headers,
);
const { llmConfig, configOptions } = getOpenAIConfig(
apiKey,
{
modelOptions: {
model,
reasoning_effort: summarizationReasoningEffort(parameters),
useResponsesApi:
typeof parameters?.useResponsesApi === 'boolean' ? parameters.useResponsesApi : undefined,
},
reverseProxyUrl: baseURL,
proxy: process.env.PROXY ?? undefined,
headers: resolveModelHeaders({
headers: headers ?? {},
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
}),
transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents),
},
EModelEndpoint.openAI,
);
return {
provider: Providers.OPENAI,
clientOverrides: {
...llmConfig,
apiKey,
useResponsesApi: llmConfig.useResponsesApi ?? false,
firstPartyEndpoint: llmConfig.firstPartyEndpoint ?? false,
reasoning: llmConfig.reasoning,
modelKwargs: llmConfig.modelKwargs ?? {},
configuration: configOptions,
},
};
}
type AzureSummarizationTarget = Omit<ReturnType<typeof mapModelToAzureConfig>, 'azureOptions'> & {
azureOptions: t.AzureOptions;
group?: TAzureConfig['groupMap'][string];
};
/**
* The summary model's Azure credentials, resolved the way `initializeOpenAI` resolves an agent's:
* the `azureOpenAI` configuration when present, otherwise the legacy environment credentials.
* Returns `undefined` (reported once) when the configuration does not define the model.
*/
function resolveAzureSummarizationTarget(
model: string,
azureConfig: TAzureConfig | undefined,
tenantId: string | undefined,
): AzureSummarizationTarget | undefined {
if (!azureConfig) {
return { azureOptions: getAzureCredentials() };
}
try {
const groupName = azureConfig.modelGroupMap[model]?.group;
return {
...mapModelToAzureConfig({
modelName: model,
modelGroupMap: azureConfig.modelGroupMap,
groupMap: azureConfig.groupMap,
}),
group: groupName ? azureConfig.groupMap[groupName] : undefined,
};
} catch (error) {
warnUnresolvedSummarization(
`Summarization with Azure OpenAI model "${model}" is disabled: ${(error as Error).message}`,
tenantId,
);
return undefined;
}
}
/** Reuse request-resolved credentials for self-summaries, including user-provided Azure keys. */
function azureSummarizationSource(agent: RunAgent): AzureSummarizationTarget {
const options = agent.model_parameters as Partial<t.OAIClientOptions> & t.AzureOptions;
const configuration = options.configuration;
const baseURL = configuration?.baseURL ?? options.azureOpenAIBasePath;
const deployment = agentModelKwargs(agent.model_parameters)?.model;
return {
serverless: agent.useLegacyContent === true,
baseURL: baseURL ?? undefined,
azureOptions: {
azureOpenAIApiKey:
options.azureOpenAIApiKey ??
(typeof options.apiKey === 'string' ? options.apiKey : undefined),
azureOpenAIApiInstanceName:
options.azureOpenAIApiInstanceName ?? agent.azureOptions?.azureOpenAIApiInstanceName,
azureOpenAIApiDeploymentName:
options.azureOpenAIApiDeploymentName ??
(typeof deployment === 'string' ? deployment : options.model),
azureOpenAIApiVersion:
options.azureOpenAIApiVersion ??
agent.azureOptions?.azureOpenAIApiVersion ??
configuration?.defaultQuery?.['api-version'] ??
undefined,
},
};
}
/**
* Resolve the summary model's deployment and transport before the SDK inherits agent options.
* A same-provider summarizer layers these over the agent's client options, so a summary group
* without a base path clears the agent's instead of sending its deployment to that resource.
* Returns `undefined` when the model cannot be resolved without a per-user lookup.
*/
function resolveAzureSummarization(
model: string,
appConfig: AppConfig | undefined,
parameters: SummarizationConfig['parameters'],
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
source?: RunAgent,
): { provider: string; clientOverrides: SummarizationClientOverrides } | undefined {
const sourceOptions = source?.model_parameters as Partial<t.OAIClientOptions> | undefined;
const target = source
? azureSummarizationSource(source)
: resolveAzureSummarizationTarget(
model,
appConfig?.endpoints?.[EModelEndpoint.azureOpenAI],
headerContext.tenantId,
);
if (!target) {
return undefined;
}
const { baseURL, headers, serverless, group } = target;
const overrides = summarizationTransportOverrides(parameters);
const azureOptions: t.AzureOptions = {
...target.azureOptions,
azureOpenAIApiKey: overrides.apiKey ?? target.azureOptions.azureOpenAIApiKey,
};
const resolvedBaseURL =
overrides.baseURL ?? baseURL ?? getBuiltInBaseURL(EModelEndpoint.azureOpenAI);
if (
!azureOptions.azureOpenAIApiKey ||
!isSummarizationURLAvailable(resolvedBaseURL, serverless ? undefined : azureOptions) ||
Object.values(azureOptions).some(
(value) =>
typeof value === 'string' && (isUserProvided(value) || hasUnresolvedPlaceholder(value)),
) ||
isUserProvided(resolvedBaseURL) ||
(resolvedBaseURL != null &&
splitAzureURLTemplates(resolvedBaseURL).some(
(segment, index) => index % 2 === 0 && hasUnresolvedPlaceholder(segment),
))
) {
warnUnresolvedSummarization(
`Summarization with Azure OpenAI model "${model}" is disabled: it needs a server-configured Azure OpenAI API key and base URL.`,
headerContext.tenantId,
);
return undefined;
}
const resolvedHeaders = sourceOptions
? (sourceOptions.configuration?.defaultHeaders as Record<string, string> | undefined)
: resolveModelHeaders({
headers: mergeHeaders(appConfig?.endpoints?.all?.headers, headers) ?? {},
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
});
const { llmConfig, configOptions } = getOpenAIConfig(
azureOptions.azureOpenAIApiKey,
{
azure: serverless ? undefined : azureOptions,
reverseProxyUrl: resolvedBaseURL,
proxy: process.env.PROXY ?? undefined,
headers:
serverless || sourceOptions != null
? { ...resolvedHeaders, 'api-key': azureOptions.azureOpenAIApiKey }
: resolvedHeaders,
defaultQuery:
serverless && azureOptions.azureOpenAIApiVersion
? { 'api-version': azureOptions.azureOpenAIApiVersion }
: undefined,
modelOptions: {
model: source?.model ?? model,
reasoning_effort: summarizationReasoningEffort(parameters),
useResponsesApi:
typeof parameters?.useResponsesApi === 'boolean'
? parameters.useResponsesApi
: sourceOptions?.useResponsesApi,
},
addParams: {
...group?.addParams,
...(typeof parameters?.useResponsesApi === 'boolean'
? { useResponsesApi: parameters.useResponsesApi }
: {}),
},
dropParams: group?.dropParams?.filter(
(key) => key !== 'useResponsesApi' || typeof parameters?.useResponsesApi !== 'boolean',
),
transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents),
},
EModelEndpoint.azureOpenAI,
);
const sourceKwargs = agentModelKwargs(source?.model_parameters);
const preservesApiMode = !!sourceOptions?.useResponsesApi === !!llmConfig.useResponsesApi;
const sourceTokenLimit = sourceKwargs?.max_output_tokens ?? sourceKwargs?.max_completion_tokens;
const inheritedTokenLimit =
typeof sourceTokenLimit === 'number'
? {
[llmConfig.useResponsesApi ? 'max_output_tokens' : 'max_completion_tokens']:
sourceTokenLimit,
}
: {};
return {
provider: !serverless && !llmConfig.useResponsesApi ? Providers.AZURE : Providers.OPENAI,
clientOverrides: {
...sourceOptions,
azureOpenAIBasePath: undefined,
azureOpenAIApiKey: undefined,
azureOpenAIApiInstanceName: undefined,
azureOpenAIApiDeploymentName: undefined,
azureOpenAIApiVersion: undefined,
...llmConfig,
apiKey: azureOptions.azureOpenAIApiKey,
useResponsesApi: llmConfig.useResponsesApi ?? false,
firstPartyEndpoint: llmConfig.firstPartyEndpoint ?? false,
reasoning: llmConfig.reasoning ?? (preservesApiMode ? sourceOptions?.reasoning : undefined),
modelKwargs: {
...(preservesApiMode ? sourceKwargs : undefined),
...inheritedTokenLimit,
...llmConfig.modelKwargs,
model: llmConfig.modelKwargs?.model ?? llmConfig.model,
},
configuration: sourceOptions
? { ...sourceOptions.configuration, ...configOptions }
: configOptions,
},
};
}
/**
* Resolves a summarization provider string (which may be a custom-endpoint name
* like "Ollama") into the SDK-recognized provider and any client-option
* overrides required to talk to that endpoint.
*
* Without this step, a `summarization.provider: "Ollama"` entry in
* `librechat.yaml` flows verbatim to the agents SDK, which only knows a fixed
* set of provider names and throws "Unsupported LLM provider: Ollama".
*/
function resolveSummarizationProvider(
rawProvider: string,
appConfig: AppConfig | undefined,
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
target: {
model?: string;
parameters?: SummarizationConfig['parameters'];
agentProvider?: string;
} = {},
): {
provider: string;
clientOverrides?: SummarizationClientOverrides;
} {
if (!appConfig || !isNonEmptyString(rawProvider)) {
return { provider: rawProvider };
}
try {
const { overrideProvider, customEndpointConfig } = getProviderConfig({
provider: rawProvider,
appConfig,
});
if (!customEndpointConfig) {
return {
provider: overrideProvider,
clientOverrides: resolveBuiltInClientOverrides(overrideProvider, target, appConfig),
};
}
const rawApiKey = customEndpointConfig.apiKey ?? '';
const rawBaseURL = customEndpointConfig.baseURL ?? '';
/**
* User-provided credentials require an async DB lookup and expiry checks
* that are out of scope here. Keep the raw provider so the SDK surfaces
* a clear "Unsupported LLM provider" error rather than silently
* remapping to `openAI` and routing summaries to the default backend.
* Callers wanting user-provided summarization against a non-agent
* endpoint must hit the same endpoint as the agent (handled upstream).
*/
if (isUserProvided(rawApiKey) || isUserProvided(rawBaseURL)) {
return { provider: rawProvider };
}
const apiKey = extractEnvVariable(rawApiKey);
const baseURL = extractEnvVariable(rawBaseURL);
/**
* `extractEnvVariable` leaves any unresolved `${VAR}` placeholder in place
* — including in the middle of a prefix/suffix string — when the env var
* is missing. If the value is still broken, keep the raw provider so the
* SDK errors out loudly instead of forwarding a malformed URL/key.
*/
if (
!apiKey ||
!baseURL ||
hasUnresolvedPlaceholder(apiKey) ||
hasUnresolvedPlaceholder(baseURL)
) {
return { provider: rawProvider };
}
/**
* Resolve templated header values (e.g. `${PORTKEY_API_KEY}`,
* `{{LIBRECHAT_BODY_PARENTMESSAGEID}}`) before handing them to
* `getOpenAIConfig`, matching the agent main flow where `resolveHeaders`
* runs on `llmConfig.configuration.defaultHeaders`.
*/
const resolvedHeaders =
customEndpointConfig.headers != null
? resolveModelHeaders({
headers: customEndpointConfig.headers as Record<string, string>,
user: createSafeUser(headerContext.user),
tenantId: headerContext.tenantId,
body: headerContext.requestBody,
})
: undefined;
/**
* Native Anthropic custom endpoints must build their config with the
* Anthropic client (`/v1/messages`), not `getOpenAIConfig` (which would emit
* OpenAI-shaped requests). The self-summarize case is handled earlier by
* `isSameEndpointAsAgent`; this covers summarizing against a *different*
* Anthropic-native custom endpoint.
*/
if (customEndpointConfig.provider === EModelEndpoint.anthropic) {
const { llmConfig } = getAnthropicLLMConfig(apiKey, {
modelOptions: {},
proxy: process.env.PROXY ?? undefined,
reverseProxyUrl: baseURL,
headers: resolvedHeaders,
addParams: customEndpointConfig.addParams,
dropParams: customEndpointConfig.dropParams,
defaultParams: extractDefaultParams(customEndpointConfig.customParams?.paramDefinitions),
});
const { apiKey: resolvedApiKey, ...llmConfigOverrides } = llmConfig as Record<
string,
unknown
>;
const clientOverrides: SummarizationClientOverrides = { ...llmConfigOverrides };
if (typeof resolvedApiKey === 'string') {
clientOverrides.apiKey = resolvedApiKey;
}
/** Strip the default model so the user-supplied `summarization.model` wins. */
delete clientOverrides.model;
delete clientOverrides.modelName;
return { provider: Providers.ANTHROPIC, clientOverrides };
}
/**
* Run the endpoint config through `getOpenAIConfig` so summarization
* inherits the same `headers`, `defaultQuery`, `addParams`/`dropParams`,
* and `customParams` transforms that `initializeCustom` applies for the
* main agent flow. Without this, summarization drops endpoint-specific
* behavior (e.g. Anthropic/Google param transforms, required headers)
* that the main agent relied on. `proxy` is forwarded so outbound proxy
* dispatchers (`PROXY` env var) apply to cross-endpoint summarization.
*/
const {
llmConfig,
configOptions,
provider: detectedProvider,
} = getOpenAIConfig(
apiKey,
{
reverseProxyUrl: baseURL,
proxy: process.env.PROXY ?? null,
headers: resolvedHeaders,
addParams: customEndpointConfig.addParams,
dropParams: customEndpointConfig.dropParams,
customParams: customEndpointConfig.customParams,
directEndpoint: customEndpointConfig.directEndpoint,
transportTimeouts: resolveModelTransportTimeouts(appConfig?.endpoints?.agents),
},
rawProvider,
);
const { apiKey: resolvedApiKey, ...llmConfigOverrides } = llmConfig;
const clientOverrides: SummarizationClientOverrides = { ...llmConfigOverrides };
if (typeof resolvedApiKey === 'string') {
clientOverrides.apiKey = resolvedApiKey;
}
if (configOptions) {
clientOverrides.configuration = configOptions;
}
/**
* `model`/`modelName` on `llmConfig` default to whatever `getOpenAIConfig`
* produces from empty modelOptions. Strip them so the user-supplied
* `summarization.model` wins.
*/
delete clientOverrides.model;
delete clientOverrides.modelName;
/**
* `getOpenAIConfig` detects OpenRouter from the resolved `baseURL`, which
* `getProviderConfig` cannot do for an endpoint whose config name isn't
* `openrouter` — it reports `openAI` for those. Prefer the detected
* provider so a cross-endpoint summarizer builds the same client the main
* agent flow builds for that endpoint (`initializeAgent` applies the same
* precedence).
*/
const provider = detectedProvider ?? overrideProvider;
/**
* On the agent's provider the SDK layers these over the agent's own client options, so this
* different endpoint replaces the agent's API mode, first-party declaration, reasoning and
* request kwargs (an Azure Astra agent's Responses routing, for one) instead of inheriting them.
*/
if (provider === target.agentProvider) {
clientOverrides.useResponsesApi ??= false;
clientOverrides.firstPartyEndpoint ??= false;
clientOverrides.modelKwargs ??= {};
clientOverrides.reasoning ??= undefined;
}
return { provider, clientOverrides };
} catch (error) {
logger.warn(
`[resolveSummarizationProvider] failed to resolve "${rawProvider}"; falling back to raw provider`,
error,
);
return { provider: rawProvider };
}
}
/** Shapes a SummarizationConfig into the format expected by AgentInputs. */
function shapeSummarizationConfig(
config: SummarizationConfig | undefined,
fallbackProvider: string,
fallbackModel: string | undefined,
appConfig: AppConfig | undefined,
agentEndpoint: string | undefined,
headerContext: { user?: IUser; tenantId?: string; requestBody?: t.RequestBody },
agent?: RunAgent,
) {
const rawProvider = config?.provider ?? fallbackProvider;
/**
* When the summarization provider resolves to the same custom endpoint as
* the main agent, skip client-option overrides. The SDK's self-summarize
* path will reuse `agentContext.clientOptions` as-is, preserving any
* request-resolved dynamic headers, fetch/proxy options, and other state
* that `getOpenAIConfig` produced from raw yaml config does not capture.
*/
const isSameEndpointAsAgent =
agentEndpoint != null &&
isNonEmptyString(rawProvider) &&
normalizeEndpointName(rawProvider) === normalizeEndpointName(agentEndpoint);
const model = config?.model ?? fallbackModel;
const targetsAzure =
rawProvider === EModelEndpoint.azureOpenAI ||
(agentEndpoint === EModelEndpoint.azureOpenAI && config?.provider == null);
const userParameters = expandSummarizationTransport(config?.parameters, targetsAzure);
const selfAzureModel =
agentEndpoint === EModelEndpoint.azureOpenAI &&
(model === fallbackModel || model === agent?.model);
const transportOverrides = summarizationTransportOverrides(userParameters);
const overridesAzureTransport =
transportOverrides.baseURL != null ||
transportOverrides.apiKey != null ||
typeof userParameters?.useResponsesApi === 'boolean';
const selectsAzureDeployment =
targetsAzure &&
isNonEmptyString(model) &&
config?.enabled !== false &&
(agentEndpoint !== EModelEndpoint.azureOpenAI ||
model !== fallbackModel ||
overridesAzureTransport);
const azureOverrides = selectsAzureDeployment
? resolveAzureSummarization(
model,
appConfig,
userParameters,
headerContext,
selfAzureModel ? agent : undefined,
)
: undefined;
const selectsOpenAIForAzureAgent =
agentEndpoint === EModelEndpoint.azureOpenAI &&
config?.provider === EModelEndpoint.openAI &&
config.enabled !== false &&
isNonEmptyString(model);
const openAIOverrides = selectsOpenAIForAzureAgent
? resolveOpenAISummarization(model, appConfig, userParameters, headerContext)
: undefined;
/**
* A target resolved here is not handed to another client when resolution fails. Azure Responses
* shares the `openAI` provider, so the SDK would summarize an OpenAI target through the agent's
* Azure resource, and would send an unmapped Azure model name where a deployment belongs.
*/
const targetUnavailable =
(selectsAzureDeployment && azureOverrides == null) ||
(selectsOpenAIForAzureAgent && openAIOverrides == null);
const { provider, clientOverrides } =
openAIOverrides ??
azureOverrides ??
(isSameEndpointAsAgent
? { provider: fallbackProvider, clientOverrides: undefined }
: resolveSummarizationProvider(rawProvider, appConfig, headerContext, {
model,
parameters: userParameters,
agentProvider: fallbackProvider,
}));
const trigger =
config?.trigger?.type && typeof config?.trigger?.value === 'number'
? { type: config.trigger.type, value: config.trigger.value }
: undefined;
/**
* Custom-endpoint overrides are merged into `parameters` so the SDK's
* `buildSummarizationClientConfig` spreads them onto the summarization
* client options. Azure self-summaries with explicit transport overrides also resolve here,
* using the initialized agent's identity and credentials instead of a new configuration lookup.
*
* Order matters: `clientOverrides` supplies endpoint defaults (baseURL,
* apiKey, headers, transforms), then explicit user `summarization.parameters`
* are spread on top so settings like `streaming: false` still win over
* `getOpenAIConfig`'s defaults. `configuration` is deep-merged so a user
* adding e.g. `configuration.defaultQuery` keeps the resolved `baseURL`
* and `defaultHeaders` rather than replacing the whole object.
*/
const mergedParameters =
clientOverrides != null
? mergeParameters(
clientOverrides,
userParameters,
azureOverrides != null || openAIOverrides != null,
)
: userParameters;
/** Placed first so an explicit user `modelKwargs` still replaces the agent's wholesale. */
const modelKwargs =
provider === fallbackProvider
? summarizationModelKwargs(agentModelKwargs(agent?.model_parameters), fallbackModel, model)
: undefined;
/**
* A scalar `reasoning_effort` — the only reasoning shape the yaml schema
* accepts — is inert as a client option and leaves the summarizer running at
* whatever effort the main agent resolved. Translate it the way the main
* flow's `getOpenAIConfig` would for the summarization target.
*/
let parameters = resolveReasoningParams({
provider,
model,
parameters: modelKwargs != null ? { modelKwargs, ...mergedParameters } : mergedParameters,
});
/** The SDK sets maxTokens for this cap, but LangChain spreads modelKwargs after it. */
const parameterTokenCap = userParameters?.maxSummaryTokens;
const summaryTokenCap =
typeof parameterTokenCap === 'number' && parameterTokenCap > 0
? parameterTokenCap
: config?.maxSummaryTokens;
const inheritedKwargs =
provider === fallbackProvider ? agentModelKwargs(agent?.model_parameters) : undefined;
const effectiveKwargs = isPlainObject(parameters?.modelKwargs)
? parameters.modelKwargs
: inheritedKwargs;
if (typeof summaryTokenCap === 'number' && effectiveKwargs != null) {
const {
max_tokens: _maxTokens,
max_completion_tokens: _maxCompletionTokens,
max_output_tokens: _maxOutputTokens,
...kwargs
} = effectiveKwargs;
parameters = { ...parameters, modelKwargs: kwargs };
}
return {
enabled:
!targetUnavailable &&
config?.enabled !== false &&
isNonEmptyString(provider) &&
isNonEmptyString(model),
config: {
trigger,
provider,
model,
parameters,
prompt: config?.prompt,
updatePrompt: config?.updatePrompt,
reserveRatio: config?.reserveRatio,
maxSummaryTokens: config?.maxSummaryTokens,
retainRecent: config?.retainRecent,
} satisfies AgentSummarizationConfig,
contextPruning: config?.contextPruning as ContextPruningConfig | undefined,
reserveRatio: config?.reserveRatio,
};
}
/**
* Below this context budget a summarization cycle cannot make progress: the
* summary allocation rounds down to a handful of tokens, the rewritten history
* still overflows, and the graph re-triggers summarization on every step until
* the recursion limit aborts the run. Dozens of wasted LLM calls surfaced to
* the user as an opaque LangGraph error. Falling back to plain pruning instead
* either fits the request or fails fast with the actionable `empty_messages`
* token-budget breakdown. Matches the floor `initializeAgent` applies when the
* user supplies no override.
*/
const MIN_SUMMARIZATION_CONTEXT_TOKENS = 1024;
/**
* Applies `reserveRatio` against the pre-ratio base context budget, falling
* back to the pre-computed `maxContextTokens` from initializeAgent.
*/
function computeEffectiveMaxContextTokens(
reserveRatio: number | undefined,
baseContextTokens: number | undefined,
maxContextTokens: number | undefined,
): number | undefined {
if (reserveRatio == null || reserveRatio <= 0 || reserveRatio >= 1 || baseContextTokens == null) {
return maxContextTokens;
}
const ratioComputed = Math.max(1024, Math.round(baseContextTokens * (1 - reserveRatio)));
return Math.min(maxContextTokens ?? ratioComputed, ratioComputed);
}
type CallbackClientOptions = {
callbacks?: Callbacks;
fallbacks?: FallbackConfig[];
};
type RunModelCallback = ModelBoundChatModelCallback | ModelErrorTrackerCallback;
/**
* Installs run-stable callbacks on the model client itself. Subagent child
* graphs intentionally replace invocation callbacks with their own event
* forwarders, while intrinsic client callbacks survive root, child, detached,
* and summarization calls.
*/
function withModelCallbacks<T extends object>(
options: T,
modelCallbacks: readonly RunModelCallback[] | undefined,
): T {
if (!modelCallbacks?.length) {
return options;
}
const callbackOptions = options as T & CallbackClientOptions;
const existingCallbacks = callbackOptions.callbacks;
/** The domain callback consumes only the model-bound message prefix of
* LangChain's callback arguments; the trailing run metadata is ignored. */
const modelHandlers = modelCallbacks as unknown as readonly CallbackHandlerMethods[];
let callbacks: CallbackClientOptions['callbacks'];
if (existingCallbacks == null || Array.isArray(existingCallbacks)) {
callbacks = [...(existingCallbacks ?? []), ...modelHandlers];
} else {
const manager = existingCallbacks.copy();
for (const callback of modelHandlers) {
manager.addHandler(ensureHandler(callback), true);
}
callbacks = manager;
}
const withCallbacks = {
...callbackOptions,
callbacks,
} as T & CallbackClientOptions;
if (Array.isArray(callbackOptions.fallbacks)) {
withCallbacks.fallbacks = callbackOptions.fallbacks.map((fallback) => ({
...fallback,
clientOptions: withModelCallbacks({ ...(fallback.clientOptions ?? {}) }, modelCallbacks),
}));
}
return withCallbacks;
}
/** Identifier for the self-spawn subagent (reuses parent's AgentInputs in an isolated child graph). */
const SELF_SUBAGENT_TYPE = 'self';
interface SubagentBuildState {
configCount: number;
rootAgentIds: string[];
}
function countSubagentConfig(state: SubagentBuildState): void {
state.configCount += 1;
if (state.configCount > MAX_SUBAGENT_RUN_CONFIGS) {
logger.warn('[createRun] Subagent run configuration limit exceeded', {
expandedConfigCount: state.configCount,
maxSubagentRunConfigs: MAX_SUBAGENT_RUN_CONFIGS,
rootAgentIds: state.rootAgentIds,
});
throw new Error(
`Subagent run configuration exceeds the maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries.`,
);
}
}
function assertSubagentDepth(depth: number, agentId: string): void {
if (depth > MAX_SUBAGENT_DEPTH) {
logger.warn('[createRun] Subagent graph depth limit exceeded', {
agentId,
depth,
maxSubagentDepth: MAX_SUBAGENT_DEPTH,
});
throw new Error(
`Subagent graph exceeds the maximum depth of ${MAX_SUBAGENT_DEPTH} at agent ${agentId}.`,
);
}
}
function createLazySubagentConfig(
child: LazySubagentAgent,
toInput: (child: RunAgent, opts?: { isSubagent?: boolean }) => AgentInputs,
agentsEConfig: Partial<TAgentsEndpoint> | undefined,
ancestors: Set<string>,
depth: number,
prebuiltGraphInputs?: ReadonlyMap<string, AgentInputs>,
onResolvedAgent?: (agent: RunAgent) => void,
): SubagentConfig {
const resolveInputs = async (context: SubagentResolveContext): Promise<AgentInputs> => {
if (context.signal.aborted) {
throw context.signal.reason ?? new Error('Subagent resolution was aborted.');
}
const resolvedChild = await child.resolve(context);
if (context.signal.aborted) {
throw context.signal.reason ?? new Error('Subagent resolution was aborted.');
}
onResolvedAgent?.(resolvedChild);
/** Graph members initialized with the child may run on its per-call machine. */
for (const graph of resolvedChild.subagentGraphConfigs ?? []) {
for (const member of graph.memberConfigs) {
onResolvedAgent?.(member);
}
}
const childInputs = buildIsolatedAgentInputs(resolvedChild, toInput);
const resolutionState: SubagentBuildState = {
configCount: 1,
rootAgentIds: [resolvedChild.id],
};
const grandchildConfigs = buildSubagentConfigs(
resolvedChild,
childInputs,
toInput,
resolutionState,
agentsEConfig,
ancestors,
depth,
prebuiltGraphInputs,
false,
onResolvedAgent,
);
if (grandchildConfigs.length > 0) {
childInputs.subagentConfigs = grandchildConfigs;
}
return childInputs;
};
const config: SubagentConfig = {
type: child.id,
name: child.name ?? child.id,
description:
child.description ??
`Delegate a subtask to the ${child.name ?? child.id} agent in an isolated context.`,
configId: child.configId,
allowNested: true,
maxTurns: resolveSubagentMaxTurns(agentsEConfig, child),
resolveAgentInputs: (context) =>
child.settle == null
? resolveInputs(context)
: child.settle(context, () => resolveInputs(context)),
};
/** Assigned rather than spread so the field typechecks against SDKs that predate it. */
return child.subagentHostArgs == null
? config
: Object.assign(config, { hostArgs: child.subagentHostArgs });
}
function enqueueSubagentChildren(
agent: SubagentTreeNode,
pending: Array<SubagentTreeNode | null | undefined>,
visited: ReadonlySet<string>,
includeLazyDescriptors = true,
includeCapabilityMetadata = true,
): void {
for (const child of agent.subagentAgentConfigs ?? []) {
if (child != null && !visited.has(child.id)) {
pending.push(child);
}
}
if (includeLazyDescriptors) {
for (const child of agent.lazySubagentConfigs ?? []) {
if (!visited.has(child.id)) {
pending.push(child);
}
}
}
if (includeCapabilityMetadata) {
for (const member of agent.subagentGraphMemberMetadata ?? []) {
if (!visited.has(member.id)) {
pending.push(member);
}
}
}
for (const graph of agent.subagentGraphConfigs ?? []) {
for (const member of graph.memberConfigs) {
if (member != null && !visited.has(member.id)) {
pending.push(member);
}
}
}
}
/**
* Collect MCP key-spelling aliases from every eagerly known agent in the run.
* Lazy descriptors are revisited when they resolve, because initializing MCP
* tools solely to discover aliases would defeat lazy loading.
*/
export function collectRunMCPToolAliases(
agents: Array<RunAgent | SubagentTreeNode | null | undefined>,
): MCPToolAlias[] {
const aliases: MCPToolAlias[] = [];
const seenAliases = new Set<string>();
const visited = new Set<string>();
const pending: Array<RunAgent | SubagentTreeNode | null | undefined> = [...agents];
for (let index = 0; index < pending.length; index++) {
const agent = pending[index];
if (agent == null) {
continue;
}
for (const alias of agent.mcpToolAliases ?? []) {
const key = `${alias.name}\u0000${alias.aliasName}`;
if (!seenAliases.has(key)) {
seenAliases.add(key);
aliases.push(alias);
}
}
if (visited.has(agent.id)) {
// The same saved agent can appear as both a lazy descriptor and a
// pre-initialized graph member. Keep traversing each representation so
// its unique children stay reachable, but avoid descending forever.
enqueueSubagentChildren(agent, pending, visited);
continue;
}
visited.add(agent.id);
enqueueSubagentChildren(agent, pending, visited);
}
return aliases;
}
/**
* Recursive any-true check across the agent tree: returns `true` if this
* agent or any subagent (transitively) has the per-agent codeenv gate
* enabled.
*
* The SDK's tool-output reference registry is shared across every
* `ToolNode` compiled from the run's graph (parent + every subagent
* alike), so a single subagent with `bash_tool` registered is enough to
* make `RunConfig.toolOutputReferences` worth activating for the whole
* run — without it, the subagent's `{{tool<idx>turn<turn>}}`
* placeholders would pass through to the shell unsubstituted.
*
* Cycle-safe via a `visited` set. The bash tool description itself is
* still gated per-agent in `initializeAgent`, so only agents that actually
* have bash registered learn the `{{…}}` syntax — broadening the run-level
* registry gate doesn't broaden the model-facing surface.
*/
function anyAgentHasCodeEnv(agents: RunAgent[]): boolean {
const visited = new Set<string>();
const pending: SubagentTreeNode[] = [...agents];
for (let index = 0; index < pending.length; index++) {
const agent = pending[index];
if (visited.has(agent.id)) {
continue;
}
visited.add(agent.id);
if (agent.codeEnvAvailable === true || (agent.codeExecutionChoices?.length ?? 0) > 0) {
return true;
}
enqueueSubagentChildren(agent, pending, visited);
}
return false;
}
/**
* Whether a single agent's tool surface includes the `ask_user_question` tool, in any
* of the three places a tool can live on a `RunAgent`: loaded instances (`tools`), the
* schema-only registry (`toolRegistry`), or serialized definitions (`toolDefinitions`).
* Checked against TOP-LEVEL agents only (not subagents — the tool is stripped from
* child configs in `buildAgentInput`, since a child graph executing outside the parent
* run's stream cannot pause the parent).
*
* Exported for AgentClient's pre-turn orphan-checkpoint prune gate: the prune must
* fire whenever THIS turn may attach a checkpointer, which since the ask tool is no
* longer coupled to `toolApproval.enabled` includes ask-capable runs.
*/
export function agentRequestsAskUserQuestion(agent: {
tools?: unknown[];
toolRegistry?: Map<string, unknown>;
toolDefinitions?: Array<{ name: string }>;
}): boolean {
return (
agent.tools?.some(
(tool) => (tool as { name?: string } | undefined)?.name === ASK_USER_QUESTION_TOOL_NAME,
) === true ||
agent.toolRegistry?.has(ASK_USER_QUESTION_TOOL_NAME) === true ||
agent.toolDefinitions?.some((def) => def.name === ASK_USER_QUESTION_TOOL_NAME) === true
);
}
/**
* Whether the admin tool filter (`includedTools` allowlist, else `filteredTools`
* exclude list — same precedence as `loadAndFormatTools`) disables
* `ask_user_question`. Enforced at RUN BUILD, not just in the tools-dialog listing:
* agents saved before an admin filtered the tool out would otherwise keep exposing
* it to the model, attaching checkpointers, and pausing runs — for a run-pausing
* tool the filter must be an actual kill switch.
*/
export function isAskUserQuestionAdminDisabled(appConfig?: AppConfig): boolean {
const included = appConfig?.includedTools;
if (included != null && included.length > 0) {
return !included.includes(ASK_USER_QUESTION_TOOL_NAME);
}
return appConfig?.filteredTools?.includes(ASK_USER_QUESTION_TOOL_NAME) === true;
}
/**
* Whether any agent reachable in the run — primary, handoff/parallel, or a
* nested subagent — opts into cross-turn `reasoning_content` reconstruction.
* Walks `subagentAgentConfigs` like {@link anyAgentHasCodeEnv}, since an
* opted-in custom endpoint may appear only as a (possibly pruned) subagent.
*/
export function anyAgentReplaysReasoningContent(
agents: Array<RunAgent | null | undefined>,
): boolean {
const visited = new Set<string>();
const pending: Array<SubagentTreeNode | null | undefined> = [...agents];
for (let index = 0; index < pending.length; index++) {
const agent = pending[index];
if (agent == null || visited.has(agent.id)) {
continue;
}
visited.add(agent.id);
if (shouldReplayReasoningContent(agent)) {
return true;
}
enqueueSubagentChildren(agent, pending, visited);
}
return false;
}
/**
* Builds SubagentConfig entries for an agent: optional self-spawn plus any
* explicit eager children and inert lazy descriptors. Returns an empty array
* when subagents are disabled or no spawn targets are available.
*/
function buildIsolatedAgentInputs(
child: RunAgent,
toInput: (agent: RunAgent, opts?: { isSubagent?: boolean }) => AgentInputs,
): AgentInputs {
const childInputs = toInput(child, { isSubagent: true });
const alwaysApplySkillPrimes = child.alwaysApplySkillPrimes;
if (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0) {
const skillInstructions = alwaysApplySkillPrimes
.map((prime) => `# Always-apply skill: ${prime.name}\n${prime.body}`)
.join('\n\n');
childInputs.additional_instructions = [childInputs.additional_instructions, skillInstructions]
.filter((value): value is string => typeof value === 'string' && value.length > 0)
.join('\n\n');
}
if ((child.backgroundToolNames?.length ?? 0) > 0) {
childInputs.toolDefinitions = stripBackgroundFromToolDefinitions(
childInputs.toolDefinitions,
child.backgroundToolNames,
);
childInputs.toolRegistry = stripBackgroundFromToolRegistry(
childInputs.toolRegistry,
child.backgroundToolNames,
);
}
if ((child.intentToolNames?.length ?? 0) > 0) {
childInputs.toolDefinitions = stripIntentFromToolDefinitions(
childInputs.toolDefinitions,
child.intentToolNames,
);
childInputs.toolRegistry = stripIntentFromToolRegistry(
childInputs.toolRegistry,
child.intentToolNames,
);
}
return childInputs;
}
function buildSubagentConfigs(
agent: RunAgent,
agentInput: AgentInputs,
toInput: (child: RunAgent, opts?: { isSubagent?: boolean }) => AgentInputs,
state: SubagentBuildState,
agentsEConfig: Partial<TAgentsEndpoint> | undefined,
ancestors: Set<string> = new Set(),
depth = 0,
prebuiltGraphInputs?: ReadonlyMap<string, AgentInputs>,
detachedTasksEnabled = false,
onResolvedAgent?: (agent: RunAgent) => void,
): SubagentConfigEntry[] {
if (!agent.subagents?.enabled) {
return [];
}
const configs: SubagentConfigEntry[] = [];
const allowSelf = agent.subagents.allowSelf !== false;
if (allowSelf) {
const selfName = agentInput.name ?? agent.name ?? 'self';
countSubagentConfig(state);
/**
* Self-spawn reuses the parent's AgentInputs. When the parent has
* background or host-injected intent tools, provide a sanitized copy so
* the isolated child — which runs the direct/child-graph path rather
* than the host interceptors — doesn't advertise `run_in_background` /
* `check_background_task` or an injected `intent` param its direct tool
* invocations would forward to tools that never declared it. The
* resolver keeps a provided `agentInputs` even with `self: true`.
*/
const hasBackground = detachedTasksEnabled || (agent.backgroundToolNames?.length ?? 0) > 0;
const hasInjectedIntent = (agent.intentToolNames?.length ?? 0) > 0;
const sanitizedToolRegistry = stripIntentFromToolRegistry(
stripBackgroundFromToolRegistry(agentInput.toolRegistry, agent.backgroundToolNames),
agent.intentToolNames,
);
configs.push({
self: true,
type: SELF_SUBAGENT_TYPE,
name: selfName,
description: `Spawn ${selfName} in an isolated context to handle a focused subtask. Verbose tool output stays in the child's context; only a summary returns.`,
/** Self-spawn reuses the parent's config, so mirror the parent's recursion limit. */
maxTurns: resolveSubagentMaxTurns(agentsEConfig, agent),
...(hasBackground || hasInjectedIntent
? {
agentInputs: {
...agentInput,
toolDefinitions: stripIntentFromToolDefinitions(
stripBackgroundFromToolDefinitions(
agentInput.toolDefinitions,
agent.backgroundToolNames,
),
agent.intentToolNames,
),
/** `registerBackgroundTaskTool` mutates the parent registry after
* configs are built. Detach its self-child snapshot so the host
* poll tool cannot appear there through that shared Map. */
toolRegistry:
detachedTasksEnabled && sanitizedToolRegistry != null
? new Map(sanitizedToolRegistry)
: sanitizedToolRegistry,
},
}
: {}),
});
}
/** Cycle-safety: include the current agent in `ancestors` before
* descending into children so a `A → B → A` configuration stops at
* the second encounter of A rather than recursing forever. Skip
* `A → A` too (already guarded) and anything that would re-enter
* an ancestor. */
const nextAncestors = new Set(ancestors);
nextAncestors.add(agent.id);
for (const child of agent.subagentAgentConfigs ?? []) {
if (!child?.id || child.id === agent.id) {
continue;
}
if (ancestors.has(child.id)) {
continue;
}
const childDepth = depth + 1;
assertSubagentDepth(childDepth, child.id);
countSubagentConfig(state);
const childInputs = buildIsolatedAgentInputs(child, toInput);
/**
* Recursively resolve the child's own spawn targets so multi-level
* delegation (A → B → C) works. Without this, a child whose own
* `subagents.enabled` is true loses every explicit target when
* invoked as a subagent — only the top-level loop attaches
* `subagentConfigs`, and that only runs for the outer agents in
* `agents[]`. Cycle-safe via `nextAncestors`.
*/
const grandchildConfigs = buildSubagentConfigs(
child,
childInputs,
toInput,
state,
agentsEConfig,
nextAncestors,
childDepth,
prebuiltGraphInputs,
detachedTasksEnabled,
onResolvedAgent,
);
if (grandchildConfigs.length > 0) {
childInputs.subagentConfigs = grandchildConfigs;
}
configs.push({
type: child.id,
name: child.name ?? child.id,
description:
child.description ??
`Delegate a subtask to the ${child.name ?? child.id} agent in an isolated context.`,
agentInputs: childInputs,
/** Preserve the child's resolved subagent configs when the SDK builds its isolated graph. */
allowNested: true,
/** Honor each child agent's own resolved recursion limit. */
maxTurns: resolveSubagentMaxTurns(agentsEConfig, child),
});
}
for (const child of agent.lazySubagentConfigs ?? []) {
if (!child.id || child.id === agent.id || ancestors.has(child.id)) {
continue;
}
const childDepth = depth + 1;
assertSubagentDepth(childDepth, child.id);
countSubagentConfig(state);
configs.push(
createLazySubagentConfig(
child,
toInput,
agentsEConfig,
nextAncestors,
childDepth,
prebuiltGraphInputs,
onResolvedAgent,
),
);
}
for (const { definition, memberConfigs } of agent.subagentGraphConfigs ?? []) {
if (memberConfigs.length === 0) {
continue;
}
countSubagentConfig(state);
const maxTurns = Math.min(
...memberConfigs.map((member) => resolveSubagentMaxTurns(agentsEConfig, member)),
);
configs.push({
kind: 'graph',
type: definition.type,
name: definition.name,
description: definition.description,
agents: memberConfigs.map(
(member) =>
prebuiltGraphInputs?.get(member.id) ?? buildIsolatedAgentInputs(member, toInput),
),
/**
* The persisted API accepts `excludeResults: false` as the explicit
* form of the default. The SDK reserves this field for prompted edges
* and rejects any defined value when no prompt exists, so erase the
* no-op false value at the host boundary.
*/
edges: definition.edges.map((edge) => {
if (edge.excludeResults !== false) {
return edge;
}
const { excludeResults: _excludeResults, ...normalizedEdge } = edge;
return normalizedEdge;
}),
entryAgentId: definition.entry_agent_id,
resultAgentId: definition.result_agent_id,
maxTurns,
});
}
return configs;
}
/**
* Creates a new Run instance with custom handlers and configuration.
*
* @param options - The options for creating the Run instance.
* @param options.agents - The agents for this run.
* @param options.signal - The signal for this run.
* @param options.runId - Optional run ID; otherwise, a new run ID will be generated.
* @param options.customHandlers - Custom event handlers.
* @param options.streaming - Whether to use streaming.
* @param options.streamUsage - Whether to stream usage information.
* @param options.messages - Optional message history to extract discovered tools from.
* When provided, tools that were previously discovered via tool_search will have
* their defer_loading overridden to false, preventing redundant re-discovery.
* @returns {Promise<Run<IState>>} A promise that resolves to a new Run instance.
*/
/** The caller's trace context over run-derived defaults for the fields it left unset. */
function resolveRunTraceContext({
agents,
conversationId,
requestBody,
traceContext,
}: {
agents: RunAgent[];
conversationId?: string;
requestBody?: t.RequestBody;
traceContext?: LangfuseTraceContext;
}): LangfuseTraceContext {
const primaryAgent = agents[0];
return {
...traceContext,
conversationId: traceContext?.conversationId ?? conversationId ?? requestBody?.conversationId,
provider: traceContext?.provider ?? primaryAgent?.provider,
model: traceContext?.model ?? primaryAgent?.model_parameters?.model ?? primaryAgent?.model,
};
}
export async function createRun({
runId,
signal,
conversationId,
agents,
messages,
discoveredToolNames,
requestBody,
codeApprovalMode: requestedCodeApprovalMode,
user,
tenantId,
centralTraceExportEnabled,
traceContext,
tokenCounter,
customHandlers,
indexTokenCountMap,
initialSessions,
summarizationConfig,
summarizeOnly = false,
compactionSemanticIndex,
initialSummary,
modelCallbacks,
clientToolNames,
calibrationRatio,
fadingTier,
fadingTiers,
appConfig,
subagentUsageSink,
subagentTasks,
runFiles,
steering,
activityLabel,
activityPhase,
eventActorCheckpointing = false,
hitlCapable = false,
resolvedToolApprovalHooks,
toolApprovalStorage,
reviewedToolApprovals,
scheduledMCPExecution,
recordScheduledMCPDenial,
toolApprovalAllows,
toolInputValidationErrors,
sessionStartSource,
streaming = true,
streamUsage = true,
}: {
agents: RunAgent[];
signal: AbortSignal;
runId?: string;
/** Conversation-stable identity, used by the e2e run hook to tell a resumed
* run apart from a fresh attempt (a resume carries no messages). */
conversationId?: string;
streaming?: boolean;
streamUsage?: boolean;
requestBody?: t.RequestBody;
codeApprovalMode?: CodeApprovalMode;
user?: IUser;
tenantId?: string;
/**
* Defaults to true. Set false to suppress central Langfuse export for this
* run. Tenant fanout can still export when tenant routing is available.
*/
centralTraceExportEnabled?: boolean;
/**
* Exact tool names the owner approved for the rest of this conversation, read from the
* stored conversation (never from the request body). Honored only when
* `toolApproval.allowAlways` is on; admin `deny`/`ask` rules and hooks still win.
*/
toolApprovalAllows?: readonly string[];
/**
* Request values the deployment may export as Langfuse trace metadata
* (`langfuse.trace.conversationMetadataFields`). The conversation id,
* provider, and model default from the run itself.
*/
traceContext?: LangfuseTraceContext;
/** Message history for extracting previously discovered tools */
messages?: BaseMessage[];
/**
* Pre-discovered deferred-tool names to force-load directly, bypassing message
* extraction. The HITL resume path rebuilds the graph with `messages: []` (state
* comes from the durable checkpoint), so the in-turn `tool_search` results that
* would normally mark a deferred tool discovered aren't present — without this the
* paused tool's schema would be absent from the rebuilt model binding. Captured at
* pause from canonical run state (with message parsing for older SDK releases) and
* replayed here. Merged with (not replacing) names extracted from `messages`.
*/
discoveredToolNames?: string[];
summarizationConfig?: SummarizationConfig;
/**
* Manual compaction: the primary agent summarizes the history outright and
* the run ends after the summary without a model call. Applies to the
* primary agent only; a chained or delegated agent never runs.
*/
summarizeOnly?: boolean;
/** Bounded, source-addressed navigation guidance derived with provider messages. */
compactionSemanticIndex?: CompactionSemanticIndex;
/** Cross-run summary from formatAgentMessages, forwarded to AgentContext */
initialSummary?: { text: string; tokenCount: number };
/** Model callbacks inherited by root, summary, fallback, and subagent clients. */
modelCallbacks?: readonly RunModelCallback[];
/** Caller-executed tools must never run eagerly before handoff is decided. */
clientToolNames?: ReadonlySet<string>;
/** Calibration ratio from previous run's contextMeta, seeds the pruner EMA */
calibrationRatio?: number;
/**
* Default agent's latched context-fading tier from the previous run's
* contextMeta. It seeds the pruner so the provider-only projection of
* historical tool results keeps the same bytes across runs; graph messages
* stay canonical. Legacy v1 tiers are not passed to the v2 SDK; it derives
* them afresh using the current-turn exchange width.
*/
fadingTier?: (IAgentFadingTier & { v: 2 }) | null;
/**
* Latched tiers keyed by agent ID from the previous run's contextMeta, so
* every agent of a multi-agent run restores its own tier. Same SDK
* availability as `fadingTier`.
*/
fadingTiers?: RunFadingTiers | null;
/**
* Resolved app config. Used to translate custom-endpoint provider names
* (e.g. "Ollama") in the summarization config to SDK-recognized providers.
*/
appConfig?: AppConfig;
/**
* Receives per-model-call usage from subagent child runs so hosts can bill
* them (child graphs execute outside the run's `streamEvents` loop, so
* their usage never reaches `customHandlers`). Typed structurally — not as
* `Pick<RunConfig, 'subagentUsageSink'>` — because the field ships in
* `@librechat/agents` > 3.2.33; older SDK versions ignore it at runtime.
* Switch to the `RunConfig` pick once the dependency is bumped.
*/
subagentUsageSink?: (event: SubagentUsageEvent) => void;
/** Host-owned detached-subagent task store and trusted parent-thread scope. */
subagentTasks?: SubagentTaskConfig;
/** Run-scoped file authorization and child context, supplied by the host. */
runFiles?: RunFileSession;
/**
* The run-scoped steer-drain hook (a `PostToolBatch` callback built via
* `createSteerDrainHook`). Registered on the run's hook registry independent
* of the tool-approval policy — steering needs neither HITL nor a
* checkpointer (injection merges via the messages reducer inside the tool
* node). Only the resumable agents controller passes this; the
* OpenAI-compatible and Responses controllers have no job/SSE surface.
*/
steering?: {
hook: HookCallback<'PostToolBatch'>;
/**
* The PreemptBoundary twin of `hook`, built via
* `createSteerPreemptBoundaryHook` from the same drain closures. Fires
* when the SDK seals a model stream mid-generation on a preempt request.
*/
preemptHook?: HookCallback<'PreemptBoundary'>;
/**
* Atomically claims queued steers at the SDK's terminal Stop boundary or
* seals admission so later messages become ordinary follow-up turns.
*/
terminalHook?: TerminalSteerHook;
/**
* Level-triggered O(1) poll over the job's armed preempt requests
* (`createSteerPreemptPoll`). Threaded into `RunConfig.preemption`, which
* also makes the SDK reserve recursion-limit headroom for its seals.
*/
preemption?: StreamPreemption & Partial<Pick<SteerPreemption, 'disable'>>;
};
/**
* Run-scoped tool-batch summary hook (PostToolBatch). Like steering, it
* registers independently of the approval policy and needs no checkpointer;
* the hook returns immediately and generates off the critical path.
*/
activityLabel?: { hook: HookCallback<'PostToolBatch'> };
/** Run-wide parent phase collector; registered after child batch labels. */
activityPhase?: { hook: HookCallback<'PostToolBatch'> };
/** Persist clean terminal checkpoints for an isolated bound-event invocation. */
eventActorCheckpointing?: boolean;
/**
* Whether the caller implements the HITL pause/resume lifecycle (inspects
* `run.getInterrupt()`, persists a pending action, exposes a resume route). Gates the
* approval pause and checkpointer: only AgentClient (chat + resume) sets this.
* All callers still enforce an enabled tool policy; without this flag the SDK
* blocks `ask` decisions rather than pausing a run with no resume surface.
*/
hitlCapable?: boolean;
/**
* Request-scoped approval hooks already resolved by the scheduled-run admission guard.
* Reuse them here so a context-aware factory is evaluated exactly once for the run.
*/
resolvedToolApprovalHooks?: readonly ResolvedToolApprovalHook[];
toolApprovalStorage?: ToolApprovalGrantStorage;
reviewedToolApprovals?: ReviewedToolApprovals;
scheduledMCPExecution?: ScheduleMCPExecution;
recordScheduledMCPDenial?: (error: ScheduledMCPPolicyError) => Promise<boolean>;
/** Plugin-hook SessionStart lifecycle source: 'startup' (default) or 'resume' on HITL-rebuild paths. */
sessionStartSource?: string;
/** Request-scoped tool input failures consumed by the completion handler. */
toolInputValidationErrors?: Map<string, ToolInputValidationError>;
} & Pick<
RunConfig,
'tokenCounter' | 'customHandlers' | 'indexTokenCountMap' | 'initialSessions'
>): Promise<Run<IState>> {
const resolvedRunId = runId ?? randomUUID();
const runFilesActive =
runFiles?.activate(
resolvedRunId,
conversationId ?? requestBody?.conversationId ?? '',
agents.map((agent) => agent.id),
signal,
) === true;
if (
appConfig?.endpoints?.agents?.fileSharing?.enabled === true &&
agents[0]?.subagents?.enabled === true &&
agents[0]?.subagents?.shareFiles === true &&
!runFilesActive
) {
throw new Error('Run file sharing is not supported by this endpoint: a file host is required.');
}
if (runFilesActive && !isRunFileSharingSupported()) {
throw new Error('Run file sharing requires an agents SDK with subagent context support.');
}
// Detached child threads resume in a new host request without this run's
// input snapshot or publication routing. Shared children stay foreground.
// Detached completion turns cannot yet restore enrolled schedule authority.
const activeSubagentTasks =
runFilesActive || scheduledMCPExecution?.enrolled === true ? undefined : subagentTasks;
/**
* Only extract discovered tools if:
* 1. We have message history to parse
* 2. At least one agent has deferred tools (using precomputed flag)
*
* This optimization avoids iterating through messages in the ~95% of cases
* where no agent uses deferred tool loading.
*/
const hasAnyDeferredTools = agents.some((agent) => agent.hasDeferredTools === true);
const discoveredTools = new Set<string>();
if (hasAnyDeferredTools) {
// Normal path: extract from this run's message history (tool_search results).
if (messages?.length) {
for (const name of extractDiscoveredToolsFromHistory(messages)) {
discoveredTools.add(name);
}
}
// Resume path: replay names captured at pause, since `messages` is empty (the
// paused run's tool_search results live only in the checkpoint, not here).
if (discoveredToolNames?.length) {
for (const name of discoveredToolNames) {
discoveredTools.add(name);
}
}
}
/** Admin kill switch for the ask tool — see {@link isAskUserQuestionAdminDisabled}. */
const askToolAdminDisabled = isAskUserQuestionAdminDisabled(appConfig);
// Independently initialized agents must reserve the same live paths before advertising uploads.
const codeFileAgents = new Map<string, RunAgent>();
const visitedCodeFileAgents = new Set<string>();
const pendingCodeFileAgents: Array<RunAgent | null | undefined> = [...agents];
for (let index = 0; index < pendingCodeFileAgents.length; index++) {
const agent = pendingCodeFileAgents[index];
if (!agent?.id || codeFileAgents.has(agent.id)) continue;
codeFileAgents.set(agent.id, agent);
visitedCodeFileAgents.add(agent.id);
enqueueSubagentChildren(agent, pendingCodeFileAgents, visitedCodeFileAgents, false, false);
}
for (const agent of codeFileAgents.values()) {
prepareQueuedCodeFileContext(agent, codeFileAgents.values(), user?.id);
}
const preparedCodeFileAgents = new WeakSet(codeFileAgents.values());
const buildAgentInput = (agent: RunAgent, opts: { isSubagent?: boolean } = {}): AgentInputs => {
if (!preparedCodeFileAgents.has(agent)) {
if (agent.provisionState) agent.provisionState.codeEnvDestinations = undefined;
codeFileAgents.set(agent.id, agent);
prepareQueuedCodeFileContext(agent, codeFileAgents.values(), user?.id, true);
preparedCodeFileAgents.add(agent);
}
const isSubagent = opts.isSubagent === true;
if (runFilesActive) {
for (const { memberConfigs } of agent.subagentGraphConfigs ?? []) {
const deliveryTargets = new Set(
memberConfigs.map((member) =>
JSON.stringify([
member.provider,
member.endpoint ?? member.provider,
member.model_parameters?.model ?? member.model,
resolveUseResponsesApi(member.model_parameters?.useResponsesApi) === true,
// Unset detail inherits the request value, which may differ from explicit auto.
member.imageDetail ?? null,
]),
),
);
if (deliveryTargets.size > 1) {
throw new Error(
'Shared-file subagent teams must use the same provider, endpoint, model, API mode, and image-detail setting for every member.',
);
}
}
}
const provider =
(providerEndpointMap[
agent.provider as keyof typeof providerEndpointMap
] as unknown as Providers) ?? agent.provider;
const selfModel = agent.model_parameters?.model ?? (agent.model as string | undefined);
/**
* Resolve request-based headers across provider-specific header locations
* (OpenAI `configuration.defaultHeaders`, Anthropic `clientOptions.defaultHeaders`,
* Google `customHeaders`). Done at this step because the request body may
* contain dynamic values (e.g. conversationId) that are only known after
* agent initialization. Resolve before a self-summary snapshots this configuration.
*/
resolveConfigHeaders({
llmConfig: agent.model_parameters as Partial<t.RunLLMConfig>,
user: createSafeUser(user),
tenantId,
body: requestBody,
});
const modelParameters = normalizeAgentModelParameters(agent.model_parameters);
const shapedSummarization = shapeSummarizationConfig(
agent.summarization ?? summarizationConfig,
provider as string,
selfModel,
appConfig,
agent.endpoint ?? undefined,
{ user, tenantId, requestBody },
agent,
);
const summarization = modelCallbacks?.length
? {
...shapedSummarization,
config: {
...shapedSummarization.config,
parameters: withModelCallbacks(
{ ...(shapedSummarization.config.parameters ?? {}) },
modelCallbacks,
),
},
}
: shapedSummarization;
const hasExplicitStreamUsage = Object.prototype.hasOwnProperty.call(
modelParameters ?? {},
'streamUsage',
);
const llmConfig = withModelCallbacks(
Object.assign(
{
provider,
streaming,
streamUsage,
},
modelParameters,
) as t.RunLLMConfig,
modelCallbacks,
);
const joinInstructionMap = (map?: Record<string, unknown>) =>
Object.values(map ?? {})
.filter((value): value is string => typeof value === 'string' && value !== '')
.join('\n')
.trim();
const toolInstructions = joinInstructionMap(agent.toolContextMap);
const dynamicToolInstructions = joinInstructionMap(agent.dynamicToolContextMap);
const systemContent = [toolInstructions, agent.instructions ?? ''].join('\n').trim();
const additionalInstructions = [dynamicToolInstructions, agent.additional_instructions ?? '']
.join('\n')
.trim();
/** Resolves issues with new OpenAI usage field */
if (
customProviders.has(agent.provider) ||
(agent.provider === Providers.OPENAI && agent.endpoint !== agent.provider)
) {
if (!hasExplicitStreamUsage) {
llmConfig.streamUsage = false;
}
llmConfig.usage = true;
}
/**
* Override defer_loading for tools that were discovered in previous
* turns. This prevents the LLM from having to re-discover tools via
* tool_search. Also add the discovered tools' definitions so the
* LLM has their schemas.
*
* Skipped for subagent children (`isSubagent`) — they run in an
* isolated context by contract, so inheriting the parent's
* tool-search state leaks unrelated history and pre-loads tools the
* child shouldn't care about. Mutations on `agent.toolRegistry`
* and additions to `toolDefinitions` both happen here, so the flag
* has to gate the whole block (clearing fields post-return can't
* undo registry writes).
*/
let toolDefinitions = agent.toolDefinitions ?? [];
let toolRegistry = agent.toolRegistry;
if (!isSubagent && discoveredTools.size > 0 && agent.toolRegistry) {
overrideDeferLoadingForDiscoveredTools(agent.toolRegistry, discoveredTools);
/** Add discovered tools' definitions so the LLM can see their schemas */
const existingToolNames = new Set(toolDefinitions.map((d) => d.name));
for (const toolName of discoveredTools) {
if (existingToolNames.has(toolName)) {
continue;
}
const toolDef = agent.toolRegistry.get(toolName);
if (toolDef) {
toolDefinitions = [...toolDefinitions, toolDef];
}
}
} else if (isSubagent && agent.toolRegistry) {
/**
* Subagent children: hand the child a deep-enough clone of the
* registry so later parent-graph builds (e.g. when the same
* agent also appears as a handoff target in the outer loop)
* can't mutate `defer_loading` on tool definitions the child
* already holds a reference to. Clone the `Map` *and* each
* `LCTool` — `overrideDeferLoadingForDiscoveredTools` writes
* through to the tool object itself, so a shallow Map copy
* alone wouldn't isolate the flag.
*/
toolRegistry = new Map();
for (const [name, tool] of agent.toolRegistry.entries()) {
toolRegistry.set(name, { ...tool });
}
/** Child's own `toolDefinitions` list gets the same shallow-
* copied view so any later parent mutation of shared definitions
* is contained to the parent-graph path. */
toolDefinitions = toolDefinitions.map((def) => ({ ...def }));
}
/**
* `ask_user_question` pauses via a LangGraph `interrupt()` raised from its own
* tool body, so it must execute IN-PROCESS inside the graph's ToolNode — the
* event-dispatched path runs tool bodies in the host handler outside the Pregel
* task frame, where `interrupt()` throws and becomes an error ToolMessage. The
* tool therefore never rides the schema-only `toolDefinitions`/`toolRegistry`
* surfaces: on every path it is REMOVED from them (clone-before-mutate,
* matching the registry-clone discipline above), and on the one path where it
* can actually work — an HITL-capable caller's top-level agent, with the admin
* filter allowing it — a real instance is supplied via `graphTools`, the SDK's
* in-graph direct-tool seam (bound to the model, executed inside the task
* frame; requires `@librechat/agents` > 3.2.57, older versions ignore the
* field). Everywhere else (OpenAI-compatible + Responses controllers with no
* resume surface, subagent child graphs that compile without a checkpointer,
* admin-disabled) it is stripped fail-closed with no replacement.
*/
let tools = agent.tools;
let graphTools: GenericTool[] | undefined;
if (agentRequestsAskUserQuestion(agent)) {
tools = tools?.filter(
(tool) => (tool as { name?: string } | undefined)?.name !== ASK_USER_QUESTION_TOOL_NAME,
);
toolDefinitions = toolDefinitions.filter((def) => def.name !== ASK_USER_QUESTION_TOOL_NAME);
if (toolRegistry?.has(ASK_USER_QUESTION_TOOL_NAME)) {
toolRegistry = new Map(toolRegistry);
toolRegistry.delete(ASK_USER_QUESTION_TOOL_NAME);
}
if (hitlCapable && !isSubagent && !askToolAdminDisabled) {
graphTools = [
createAskUserQuestionTool(toolInputValidationErrors) as unknown as GenericTool,
];
}
}
if (runFilesActive) {
tools = eventOnlyRunFileTools(tools, toolDefinitions);
}
const effectiveMaxContextTokens = computeEffectiveMaxContextTokens(
summarization.reserveRatio,
agent.baseContextTokens,
agent.maxContextTokens,
);
const summarizationViable =
effectiveMaxContextTokens == null ||
effectiveMaxContextTokens >= MIN_SUMMARIZATION_CONTEXT_TOKENS;
if (summarization.enabled && !summarizationViable) {
logger.warn(
'[createRun] Summarization disabled for this run: context budget below viable minimum',
{
agentId: agent.id,
effectiveMaxContextTokens,
minimum: MIN_SUMMARIZATION_CONTEXT_TOKENS,
},
);
}
const reasoningKey = getReasoningKey(provider, llmConfig, agent.endpoint, agent.reasoningKey);
const agentInput: AgentInputs = {
provider,
endpoint: agent.endpoint ?? provider,
reasoningKey,
toolDefinitions,
agentId: agent.id,
tools,
clientOptions: llmConfig,
instructions: systemContent,
additional_instructions: additionalInstructions || undefined,
name: agent.name ?? undefined,
toolRegistry,
maxContextTokens: effectiveMaxContextTokens,
useLegacyContent: agent.useLegacyContent ?? false,
discoveredTools:
!isSubagent && discoveredTools.size > 0 ? Array.from(discoveredTools) : undefined,
summarizationEnabled: summarization.enabled && summarizationViable,
summarizationConfig: summarization.config,
...(!isSubagent && compactionSemanticIndex != null ? { compactionSemanticIndex } : {}),
initialSummary: isSubagent ? undefined : initialSummary,
contextPruningConfig: summarization.contextPruning,
maxToolResultChars: agent.maxToolResultChars,
initialSessions: buildAgentInitialToolSessions(agent, initialSessions),
codeSessionKey: agent.codeSessionKey,
};
if (runFilesActive && runFiles != null && (isSubagent || agent.subagents?.enabled === true)) {
graphTools = [...(graphTools ?? []), ...createRunFileTools(runFiles, agent.id, signal)];
}
if (graphTools) {
/**
* Typed structurally — not as `AgentInputs['graphTools']` — because the
* field ships in `@librechat/agents` > 3.2.57 (agents#289); older SDK
* versions ignore it at runtime (the tool is then simply absent, never
* broken). Inline the field in the literal once the dependency is bumped.
*/
(agentInput as AgentInputs & { graphTools?: GenericTool[] }).graphTools = graphTools;
}
return agentInput;
};
const agentsEndpointConfig = appConfig?.endpoints?.[EModelEndpoint.agents];
const attachedCodeEnvironmentAgentIds = collectAttachedCodeEnvironmentAgentIds(agents);
const attachedCodeEnvironmentSettings = collectAttachedCodeEnvironmentPolicySettings(agents);
const codeApprovalMode = resolveAttachedCodeApprovalMode(
requestedCodeApprovalMode,
collectAttachedCodeApprovalPolicies(agents),
agentsEndpointConfig?.toolApproval?.enabled !== false,
);
assertAttachedCodeEnvironmentApprovalSupported({
hasAttachedCodeEnvironment: attachedCodeEnvironmentAgentIds.size > 0,
hitlCapable,
approvalExplicitlyDisabled: agentsEndpointConfig?.toolApproval?.enabled === false,
});
// Assigned after the run-wide HITL registry is built. Lazy descriptors
// capture this indirection now and report their aliases when they resolve.
let registerResolvedMCPToolAliases: (agent: RunAgent) => void = () => undefined;
const agentInputs: AgentInputs[] = [];
const subagentBuildState: SubagentBuildState = {
configCount: 0,
rootAgentIds: agents.map((agent) => agent.id),
};
const prebuiltGraphInputs = new Map<string, AgentInputs>();
const visitedConfigIds = new Set<string>();
const pendingConfigs: Array<RunAgent | null | undefined> = [...agents];
for (let index = 0; index < pendingConfigs.length; index++) {
const config = pendingConfigs[index];
if (!config?.id || visitedConfigIds.has(config.id)) {
continue;
}
visitedConfigIds.add(config.id);
if (!prebuiltGraphInputs.has(config.id)) {
prebuiltGraphInputs.set(config.id, buildIsolatedAgentInputs(config, buildAgentInput));
}
for (const graph of config.subagentGraphConfigs ?? []) {
for (const member of graph.memberConfigs) {
if (!prebuiltGraphInputs.has(member.id)) {
prebuiltGraphInputs.set(member.id, buildIsolatedAgentInputs(member, buildAgentInput));
}
}
}
enqueueSubagentChildren(config, pendingConfigs, visitedConfigIds, false, false);
}
for (const agent of agents) {
const agentInput = buildAgentInput(agent);
if (summarizeOnly && agent === agents[0]) {
agentInput.summarizeOnly = true;
}
const subagentConfigs = buildSubagentConfigs(
agent,
agentInput,
buildAgentInput,
subagentBuildState,
agentsEndpointConfig,
undefined,
0,
prebuiltGraphInputs,
activeSubagentTasks != null,
(resolvedAgent) => registerResolvedMCPToolAliases(resolvedAgent),
);
if (subagentConfigs.length > 0) {
agentInput.subagentConfigs = subagentConfigs;
/** Seed the SDK countdown that bounds nested delegation across isolated child graphs. */
agentInput.maxSubagentDepth = MAX_SUBAGENT_DEPTH;
}
if (activeSubagentTasks != null) {
agentInput.toolDefinitions = registerBackgroundTaskTool({
toolRegistry: agentInput.toolRegistry,
toolDefinitions: agentInput.toolDefinitions,
subagentCompletionWakeups: agentUsesSubagentCompletionWakeups(
activeSubagentTasks,
agent.id,
),
}).toolDefinitions;
}
agentInputs.push(agentInput);
}
const graphConfig: RunConfig['graphConfig'] = {
signal,
agents: agentInputs,
edges: agents[0].edges ?? [],
};
if (agentInputs.length > 1 || ((graphConfig as MultiAgentGraphConfig).edges?.length ?? 0) > 0) {
(graphConfig as unknown as MultiAgentGraphConfig).type = 'multi-agent';
} else {
(graphConfig as StandardGraphConfig).type = 'standard';
}
/**
* Enable tool-output references when the bash tool is actually
* present anywhere in this run — top-level agent OR any subagent
* (transitively). `codeEnvAvailable` on each `RunAgent` is the
* per-agent gate (admin `execute_code` capability AND the agent's
* own `tools` listing `execute_code`), so the feature follows the
* same activation as the bash-tool registration in
* `initializeAgent`. The walk into `subagentAgentConfigs` is
* load-bearing: a parent without `execute_code` can spawn a
* subagent that has it, and the SDK's shared registry serves
* every `ToolNode` compiled from this run's graph — so missing
* subagents in this gate would leave the child's
* `{{tool<idx>turn<turn>}}` placeholders unsubstituted. SDK
* defaults (~400 KB per output, 5 MB total) keep substituted
* payloads inside typical shell ARG_MAX limits, so no overrides
* are needed for the experimental rollout.
*/
const enableToolOutputReferences = anyAgentHasCodeEnv(agents);
/**
* Endpoint tool approval is off by default. An enabled policy installs the
* `PreToolUse` hooks for every run. Only callers with a resume surface also
* enable real HITL interrupts and a durable checkpointer; on headless runs
* the SDK blocks both `deny` and `ask` before executing the tool.
*/
// Resolve the effective policy through the single seam so BYOM defaults and
// future persisted per-agent / per-skill sources do not leak into this call site.
const toolApprovalPolicy = resolveToolApprovalPolicy({
endpoint: agentsEndpointConfig?.toolApproval,
attachedCodeEnvironment: attachedCodeEnvironmentAgentIds.size > 0,
});
// Every caller needs the policy hooks, including API-key ingresses. Only
// AgentClient supports pause/resume; the SDK blocks `ask` without HITL enabled.
// Keep the checkpointer and humanInTheLoop switch exclusive to those callers.
/** Both-direction key-spelling aliases collected from every eagerly known
* agent, including explicit and graph subagents. Lazy subagents report
* theirs through `registerResolvedMCPToolAliases` below. */
const mcpToolAliases = collectRunMCPToolAliases(agents);
const mcpToolAliasKeys = new Set(
mcpToolAliases.map(({ name, aliasName }) => `${name}\u0000${aliasName}`),
);
const effectiveToolApprovalPolicy = () =>
exemptAskUserQuestionFromApproval(
buildEffectiveToolApprovalPolicy(toolApprovalPolicy, mcpToolAliases, toolApprovalAllows),
ASK_USER_QUESTION_TOOL_NAME,
);
const nativeEditFileAgentIds = collectNativeEditFileAgentIds(agents);
const agentApprovalSession = createAgentToolApprovalSession({
agents: [...codeFileAgents.values()],
storage: toolApprovalPolicy?.agentModes === true ? toolApprovalStorage : undefined,
authorizationStorage: toolApprovalStorage,
reviewed: reviewedToolApprovals,
policy: effectiveToolApprovalPolicy,
lookupTimeoutMs: toolApprovalPolicy?.grantLookupTimeoutMs,
scope:
user?.id && (conversationId ?? requestBody?.conversationId)
? {
userId: user.id,
tenantId: tenantId ?? user.tenantId,
conversationId: (conversationId ?? requestBody?.conversationId)!,
}
: undefined,
});
const approvalWiring = buildHITLRunWiring(
// The ask tool is exempt from the approval prompt (unless explicitly
// listed by the admin) — approving the right to ask a question is a
// pure double-pause; the tool has no side effects to gate. Pattern
// lists are healed against the tools' other key spellings first, so
// admin globs written for pre-strip upstream names keep applying (a
// non-matching deny would fail OPEN), and rules written against
// current catalog names reach legacy-named instances.
effectiveToolApprovalPolicy(),
{
userId: user?.id,
conversationId: requestBody?.conversationId,
tenantId: tenantId ?? user?.tenantId,
appConfig,
},
mcpToolAliases,
[
{ hook: agentApprovalSession.hook },
...(resolvedToolApprovalHooks ??
buildToolApprovalHooks({
userId: user?.id,
conversationId: requestBody?.conversationId,
tenantId: tenantId ?? user?.tenantId,
appConfig,
})),
...(attachedCodeEnvironmentAgentIds.size > 0
? [
{
hook: createAttachedCodeEnvironmentPolicyHook(
attachedCodeEnvironmentAgentIds,
attachedCodeEnvironmentSettings,
codeApprovalMode,
),
},
]
: []),
],
nativeEditFileAgentIds,
);
approvalWiring?.hooks.register('PostToolUse', { hooks: [agentApprovalSession.rememberHook] });
approvalWiring?.hooks.register('PostToolBatch', {
hooks: [agentApprovalSession.settleBatchHook],
});
const hitl = hitlCapable ? approvalWiring : undefined;
const scheduledPolicy = scheduledMCPExecution
? createScheduledMCPRunPolicy(
scheduledMCPExecution,
agents,
agents[0].edges ?? [],
recordScheduledMCPDenial,
)
: undefined;
registerResolvedMCPToolAliases = (resolvedAgent) => {
agentApprovalSession.addAgent(resolvedAgent);
scheduledPolicy?.registerAgent(resolvedAgent);
for (const agentId of collectNativeEditFileAgentIds([resolvedAgent])) {
nativeEditFileAgentIds.add(agentId);
}
if (resolvedAgent.codeExecutionContext?.environmentType === 'attached') {
// The admission hook closes over these collections. A lazily resolved agent
// therefore receives its own current machine policy before its first tool call;
// a mode that machine does not permit safely falls back to ask/deny there.
attachedCodeEnvironmentAgentIds.add(resolvedAgent.id);
attachedCodeEnvironmentSettings.set(resolvedAgent.id, {
configSchema: resolvedAgent.codeExecutionContext.codeEnvironmentConfigSchema,
settings: resolvedAgent.codeExecutionContext.codeEnvironmentSettings,
skillAuthoringAvailable: resolvedAgent.skillAuthoringAvailable === true,
});
} else {
/** A routable child counted as attached before its call chose a route; it resolved
* off attached machines, and runs on that one route for the whole request. */
attachedCodeEnvironmentAgentIds.delete(resolvedAgent.id);
attachedCodeEnvironmentSettings.delete(resolvedAgent.id);
}
const discoveredAliases = collectRunMCPToolAliases([resolvedAgent]).filter(
({ name, aliasName }) => {
const key = `${name}\u0000${aliasName}`;
if (mcpToolAliasKeys.has(key)) {
return false;
}
mcpToolAliasKeys.add(key);
return true;
},
);
if (discoveredAliases.length === 0) {
return;
}
mcpToolAliases.push(...discoveredAliases);
approvalWiring?.addMCPToolAliases(discoveredAliases, effectiveToolApprovalPolicy());
};
/**
* The `ask_user_question` tool pauses via LangGraph `interrupt()` from inside its own
* body, which needs only a durable checkpointer — NOT the tool-approval policy
* (`humanInTheLoop`/hooks stay off unless approval is separately enabled; verified
* end-to-end in `api/.../agents/__tests__/askUserQuestion.e2e.spec.js`). Top-level
* check only: subagent copies of the tool are stripped in `buildAgentInput`. Gated on
* `hitlCapable` like approval, and the tool itself was stripped from non-HITL callers
* above, so a checkpointer here always has a resume surface. The LazyMongoSaver only
* persists when a run actually pauses, so attaching it is near-zero overhead.
*/
const asksUserQuestions =
hitlCapable && !askToolAdminDisabled && agents.some(agentRequestsAskUserQuestion);
if (hitl || asksUserQuestions || eventActorCheckpointing) {
const checkpointer = await getAgentCheckpointer(agentsEndpointConfig?.checkpointer);
graphConfig.compileOptions = { ...graphConfig.compileOptions, checkpointer };
}
/**
* The run's hook registry: tool policy hooks (when approval is enabled)
* plus the steer-drain PostToolBatch hook. Steering registers independently
* of the approval policy and requires no checkpointer, but is hard-gated on
* SDK support — draining on an SDK that ignores `injectedMessages` would
* silently drop the user's words (the steer controller 501s in that case;
* this guard is defense in depth).
*/
let hooks = approvalWiring?.hooks;
if (scheduledPolicy) {
hooks ??= new HookRegistry();
hooks.register('PreToolUse', { hooks: [scheduledPolicy.hook, scheduledPolicy.receipt] });
}
if (usesSubagentCompletionWakeups(activeSubagentTasks)) {
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolUse', {
pattern: String(Constants.SUBAGENT),
hooks: [
createSubagentWakeupHandleHook((agentId) =>
agentUsesSubagentCompletionWakeups(activeSubagentTasks, agentId),
),
],
internal: true,
});
}
/** Activity labels register BEFORE the steer drain: the label must claim
* its slot while the batch's tool parts are still the content tail. If a
* steer drained first, its injected part would flush the tool block in
* sequential rendering and orphan the label outside its group. With the
* label claimed first, parts order as [tools…, label, steer] — the label
* terminates the group and the steer renders after it. */
if (activityLabel != null) {
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', { hooks: [activityLabel.hook] });
}
if (activityPhase != null) {
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', { hooks: [activityPhase.hook] });
}
if (steering != null && isSteeringSupported()) {
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', { hooks: [steering.hook] });
if (steering.preemptHook != null && isSteerPreemptSupported()) {
hooks.register('PreemptBoundary', { hooks: [steering.preemptHook] });
}
if (steering.terminalHook != null && isSteerTerminalContinuationSupported()) {
const stopFinalizeRegistry = hooks as unknown as {
register: (event: 'StopFinalize', matcher: { hooks: TerminalSteerHook[] }) => () => void;
};
stopFinalizeRegistry.register('StopFinalize', { hooks: [steering.terminalHook] });
}
}
/**
* Step-budget awareness. Registered unconditionally (no config, no checkpointer,
* no SDK capability gate, since `additionalContext` has been part of `BaseHookOutput`
* since hooks shipped) because running out of steps mid-turn is a failure mode on
* every ingress, and a model that knows its budget is running low usually avoids
* it. Registered after the label/steer hooks so their content-slot ordering is
* untouched; `additionalContexts` accumulate independently of injected messages.
*/
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', {
hooks: [
createStepBudgetHook({
recursionLimit: resolveRecursionLimit(agentsEndpointConfig, agents[0]),
}),
],
internal: true,
});
/**
* Deployment-plugin hooks (Agent Plugins `ai.librechat/hooks/hooks.json`)
* register last so internal policy hooks (HITL, labels, steering) keep
* their ordering. The source is wired at startup by the plugins package
* (see `setPluginHookSource` in api/server/index.js) and stays empty
* unless the operator installed plugins with hook documents AND opted in
* via DEPLOYMENT_PLUGIN_HOOKS. The conversation id doubles as the plugin
* "session", giving SessionStart its once-per-conversation scope.
*/
const pluginHookSource = getPluginHookSource();
if (pluginHookSource?.hasHooks() === true) {
hooks = hooks ?? new HookRegistry();
const primaryAgent = agents[0];
pluginHookSource.register({
registry: hooks,
context: {
sessionId: requestBody?.conversationId,
userId: user?.id,
sessionStartSource,
model: primaryAgent?.model_parameters?.model ?? primaryAgent?.model ?? undefined,
agentType: primaryAgent?.id,
},
// `ask` needs the checkpointer + resume surface; without HITL wiring the
// source tightens plugin `ask` decisions to `deny` rather than stranding
// the run on an un-resumable interrupt.
askDecisionSupported: hitl != null,
});
}
const streamLimits = resolveStreamLimits(agentsEndpointConfig);
/**
* Built as a variable (not an inline literal) so the extra
* `subagentUsageSink` field passes assignability against SDK versions
* whose `RunConfig` predates it (<= 3.2.33, where it is ignored at
* runtime) — excess-property checks only apply to fresh literals. Inline
* the field at the call site once the dependency is bumped.
*/
let preemption = steering?.preemption;
if (preemption != null && !supportsRunInterruption(agentInputs)) {
await preemption.disable?.();
preemption = undefined;
}
const toolHandler = customHandlers?.[GraphEvents.ON_TOOL_EXECUTE];
const runHandlers =
toolHandler != null && preemption != null && isSteerPreemptSupported()
? {
...customHandlers,
[GraphEvents.ON_TOOL_EXECUTE]: interruptToolHandler(toolHandler, preemption),
}
: customHandlers;
const runConfig = {
runId: resolvedRunId,
graphConfig,
tokenCounter,
customHandlers: runHandlers,
initialSessions,
calibrationRatio,
fadingTier,
fadingTiers,
indexTokenCountMap,
subagentUsageSink,
subagentTasks: activeSubagentTasks,
...(runFilesActive &&
runFiles != null && {
subagentContext: { prepare: runFiles.prepare, complete: runFiles.complete },
}),
// Exclude side-effecting / large-free-form-arg tools from eager execution.
// Eager speculatively runs a tool mid-stream; for a big streamed arg (a
// file body, a bash heredoc, a code block) the accumulated args can diverge
// from the final tool call and trip the SDK's "changed after eager
// execution" guard, and a speculative write/exec can land before the turn
// commits. create_file/edit_file write files; execute_code/bash_tool run
// code with large `code`/`command` args. `excludeToolNames` requires
// @librechat/agents with the eager-exclusion support (agents#281); older
// versions ignore the field. ask_user_question raises a LangGraph
// `interrupt()` from its tool body, which must run inside the Pregel task
// frame — a speculative eager execution could never pause the run.
eagerEventToolExecution: {
enabled: true,
excludeToolNames: [
CREATE_FILE_TOOL_NAME,
EDIT_FILE_TOOL_NAME,
Constants.EXECUTE_CODE,
Constants.BASH_TOOL,
ASK_USER_QUESTION_TOOL_NAME,
/**
* Background-capable tools: eager execution could launch the detached
* task with speculative/partial args before the final tool call, and a
* background side effect (unlike a foreground eager mismatch) can't be
* canceled once dispatched. The poll tool is excluded for the same
* reason: collecting a task's artifact is a one-shot claim that must
* not fire from a speculative snapshot the SDK may later discard.
*/
CHECK_BACKGROUND_TASK_NAME,
...agents.flatMap((agent) => agent.backgroundToolNames ?? []),
...(clientToolNames ?? []),
],
},
// Let host file tools share the code-execution sandbox session so a file
// created with create_file/edit_file is visible to later
// execute_code/bash_tool calls (and vice versa). The SDK folds these tools'
// returned exec session/files into the shared code session and injects the
// existing session into their requests. Membership here also stamps the
// stateful `runtimeSessionHint` and excludes the tool from eager execution
// — read_file needs both, or its sandbox `cat` runs hintless on the Code
// API's per-user default runtime session and cannot see files bash_tool
// just wrote in the conversation's session. Requires @librechat/agents
// with codeSessionToolNames support (agents#283); older versions ignore it.
// `check_background_task` participates so a backgrounded code call's exec
// session/files (returned as the poll result's artifact when claimed) fold
// into the shared code session, keeping same-run continuity for later
// foreground code calls. Poll results carry an artifact only for code
// tasks, so non-code polls never touch the session.
codeSessionToolNames: [
CREATE_FILE_TOOL_NAME,
EDIT_FILE_TOOL_NAME,
Constants.READ_FILE,
CHECK_BACKGROUND_TASK_NAME,
],
// Derive the Langfuse trace id deterministically from runId so message
// feedback can be scored against the trace without a lookup (see the
// feedback route in api/server/routes/messages.js). No-op unless Langfuse
// tracing is enabled. Requires @librechat/agents >= 3.2.21.
langfuse: buildLangfuseConfig({
appConfig,
runId: resolvedRunId,
tenantId: tenantId ?? user?.tenantId,
centralTraceExportEnabled,
user,
traceContext: resolveRunTraceContext({ agents, conversationId, requestBody, traceContext }),
}),
...(enableToolOutputReferences && {
toolOutputReferences: { enabled: true },
}),
// Only resumable callers enable real approval interrupts. The PreToolUse policy
// hook stays in `hooks` for headless callers, where `ask` fails closed.
// The steer-drain hook rides the same registry but independently of the approval
// policy: a PostToolBatch-only registry keeps the SDK's eager execution fast paths
// (it gates on result-altering hooks, not registry presence).
...(hitl && { humanInTheLoop: hitl.humanInTheLoop }),
...(hooks && { hooks }),
// Preemption is observation-only like the boundary hooks: the poll never
// mutates and the SDK refuses to seal unless a PreemptBoundary matcher is
// live, so gating both on the same capability keeps them in lockstep.
...(preemption != null && isSteerPreemptSupported() && { preemption }),
// Stream circuit breakers (librechat.yaml endpoints.agents.maxToolCallArgBytes /
// maxDeltaEventsPerTurn). Omitted when unset so the SDK defaults apply: a runaway
// streamed tool-call argument aborts the run at 64 KiB, the per-turn delta event
// cap stays off. Requires @librechat/agents with streamLimits support (agents#381);
// older versions ignore the field.
...(streamLimits && { streamLimits }),
};
const run = await Run.create(runConfig);
if (approvalWiring != null) bindRunToolApprovalSession(run, agentApprovalSession);
runMCPToolAliases.set(run, mcpToolAliases);
applyCustomHandoffPromptKeyCompatibility(run, runConfig.graphConfig);
applyTestRunHook(run, {
messages,
agents,
modelCallbacks,
conversationId: conversationId ?? requestBody?.conversationId ?? undefined,
});
return run;
}