Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🚞 fix: Route Accepted Tool Calls Through the Live Agents API (#16401)

lia-by-librechat[bot]19e01607e876
diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js
index 96e9b463bd..097da840e3 100644
--- a/api/server/controllers/agents/__tests__/openai.spec.js
+++ b/api/server/controllers/agents/__tests__/openai.spec.js
@@ -219,13 +219,7 @@ jest.mock('@librechat/api', () => ({
buildAgentContextAttachmentsByAgentId: (...args) =>
mockBuildAgentContextAttachmentsByAgentId(...args),
createChunk: jest.fn().mockReturnValue({}),
- /** Not stubbed: the outward tool-call index this allocates is the behavior the
- * controller is responsible for wiring, so the spec runs the real projection. */
- createOpenAIToolCallStream: (...args) =>
- jest.requireActual('@librechat/api').createOpenAIToolCallStream(...args),
completeOpenAIToolCalls: jest.requireActual('@librechat/api').completeOpenAIToolCalls,
- OpenAIRunStepHandler: jest.requireActual('@librechat/api').OpenAIRunStepHandler,
- OpenAIRunStepDeltaHandler: jest.requireActual('@librechat/api').OpenAIRunStepDeltaHandler,
buildRunToolSet: jest.fn().mockReturnValue(new Set()),
buildInitialToolSessions: jest.fn().mockReturnValue(mockInitialSessions),
AgentRunEnvelopeError: MockAgentRunEnvelopeError,
@@ -520,7 +514,7 @@ describe('OpenAIChatCompletionController', () => {
});
it.each([true, false])(
- 'projects interleaved calls and preserves the final stop (stream=%s)',
+ 'keeps SDK- and provider-executed calls out of the mounted endpoint (stream=%s)',
async (streaming) => {
const api = require('@librechat/api');
const actual = jest.requireActual('@librechat/api');
@@ -532,66 +526,29 @@ describe('OpenAIChatCompletionController', () => {
'createOpenAIStreamTracker',
'createOpenAIContentAggregator',
];
- const original = names.map((name) => [name, api[name].getMockImplementation()]);
+ const originals = names.map((name) => [name, api[name].getMockImplementation()]);
for (const name of names) api[name].mockImplementation(actual[name]);
req.body.stream = streaming;
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
- const { customHandlers: h } = api.createRun.mock.calls.at(-1)[0];
- const meta = { langgraph_node: 'agent=test', langgraph_step: 1 };
- for (const [step, id, index] of [
- ['s1', 'a', 0],
- ['s2', 'b', 1],
- ]) {
- await h.on_run_step.handle(
- 'on_run_step',
- {
- id: step,
- stepDetails: {
- type: 'tool_calls',
- tool_calls: [{ id, name: 'get_time' }],
- },
- },
- meta,
- );
- await h.on_run_step_delta.handle(
- 'on_run_step_delta',
- {
- id: step,
- delta: {
- type: 'tool_calls',
- tool_calls: [{ id, name: 'get_time', index }],
- },
- },
- meta,
- );
- }
- for (const [index, city] of [
- [0, 'Madrid'],
- [1, 'Paris'],
- ]) {
- await h.on_run_step_delta.handle(
- 'on_run_step_delta',
- {
- id: 's2',
- delta: {
- type: 'tool_calls',
- tool_calls: [{ index, args: JSON.stringify({ city }) }],
- },
- },
- meta,
- );
- }
- await h.on_message_delta.handle(
- 'on_message_delta',
- {
- id: 'answer',
- delta: {
- content: [{ type: 'text', text: 'Both tools completed.' }],
- },
- },
- { ...meta, langgraph_step: 3 },
- );
+ const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
+ expect(handlers.on_run_step).toBeUndefined();
+ expect(handlers.on_run_step_delta).toBeUndefined();
+ expect(handlers.on_run_step_completed).toBeUndefined();
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'accepted-internal',
+ agentId: 'agent-123',
+ toolCalls: [
+ { id: 'internal', name: 'get_time', args: { city: 'Madrid' } },
+ { id: 'provider', name: 'web_search', args: { query: 'weather' } },
+ ],
+ toolCallDispositions: ['sdk', 'provider'],
+ invalidToolCalls: [],
+ });
+ await handlers.on_message_delta.handle('on_message_delta', {
+ delta: { content: [{ type: 'text', text: 'Both tools completed.' }] },
+ });
});
try {
await OpenAIChatCompletionController(req, res);
@@ -600,54 +557,27 @@ describe('OpenAIChatCompletionController', () => {
.map(([frame]) => frame)
.filter((frame) => frame !== 'data: [DONE]\n\n')
.map((frame) => JSON.parse(frame.slice(6)));
- expect(frames.at(-1).choices[0].finish_reason).toBe('stop');
+ expect(frames.flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])).toEqual([]);
expect(
- frames
- .flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
- .filter((call) => call.function?.arguments),
- ).toEqual([
- { index: 0, function: { arguments: '{"city":"Madrid"}' } },
- { index: 1, function: { arguments: '{"city":"Paris"}' } },
- ]);
+ frames.some((frame) => frame.choices[0].delta.content === 'Both tools completed.'),
+ ).toBe(true);
+ expect(frames.at(-1).choices[0].finish_reason).toBe('stop');
} else {
- expect(res.json).toHaveBeenCalledWith(
- expect.objectContaining({
- choices: [
- expect.objectContaining({
- finish_reason: 'stop',
- message: expect.objectContaining({
- content: 'Both tools completed.',
- tool_calls: [
- {
- id: 'a',
- type: 'function',
- function: { name: 'get_time', arguments: '{"city":"Madrid"}' },
- },
- {
- id: 'b',
- type: 'function',
- function: { name: 'get_time', arguments: '{"city":"Paris"}' },
- },
- ],
- }),
- }),
- ],
- }),
- );
+ const choice = res.json.mock.calls[0][0].choices[0];
+ expect(choice.message.content).toBe('Both tools completed.');
+ expect(choice.message.tool_calls).toBeUndefined();
+ expect(choice.finish_reason).toBe('stop');
}
} finally {
- for (const [name, implementation] of original) api[name].mockImplementation(implementation);
+ for (const [name, implementation] of originals)
+ api[name].mockImplementation(implementation);
}
},
);
- it.each(
- [true, false].flatMap((stream) =>
- ['native-string', 'wire-object', 'split', 'idless'].map((shape) => [stream, shape]),
- ),
- )(
- 'publishes complete identity and arguments before terminal output (stream=%s, shape=%s)',
- async (streaming, shape) => {
+ it.each([true, false])(
+ 'publishes only the accepted client call after a model claim (stream=%s)',
+ async (streaming) => {
const api = require('@librechat/api');
const actual = jest.requireActual('@librechat/api');
const names = [
@@ -663,34 +593,32 @@ describe('OpenAIChatCompletionController', () => {
req.body.stream = streaming;
api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
- const { customHandlers: h } = api.createRun.mock.calls.at(-1)[0];
- await h.on_run_step.handle('on_run_step', {
- id: 'complete',
- stepDetails: {
- type: 'tool_calls',
- tool_calls: [
- (() => {
- if (shape === 'native-string')
- return { id: 'a', name: 'get_time', args: '{"city":"Madrid"}' };
- if (shape === 'wire-object')
- return { id: 'a', function: { name: 'get_time', arguments: { city: 'Madrid' } } };
- if (shape === 'idless') return { name: 'get_time', args: { city: 'Madrid' } };
- return { id: 'a', name: 'get_', args: {} };
- })(),
- ],
- },
+ const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'discarded',
+ agentId: 'agent-123',
+ messageId: 'claimed-message',
+ toolCalls: [{ id: 'stale', name: 'stale_tool', args: { secret: 'DO_NOT_SEND' } }],
+ toolCallDispositions: ['client'],
+ invalidToolCalls: [],
+ });
+ await handlers.on_model_tools_claimed.handle('on_model_tools_claimed', {
+ type: 'model_tools_claimed',
+ agentId: 'agent-123',
+ messageId: 'claimed-message',
+ });
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'accepted-client',
+ agentId: 'agent-123',
+ toolCalls: [
+ { id: 'a', name: 'get_time', args: { city: 'Madrid' } },
+ { id: 'a', name: 'get_time', args: { city: 'Paris' } },
+ ],
+ toolCallDispositions: ['client', 'client'],
+ invalidToolCalls: [],
});
- if (shape === 'split') {
- for (const fragment of [
- { id: 'a', name: 'get_', index: 0, args: '{"city":"Madrid"}' },
- { index: 0, name: 'time' },
- ]) {
- await h.on_run_step_delta.handle('on_run_step_delta', {
- id: 'complete',
- delta: { type: 'tool_calls', tool_calls: [fragment] },
- });
- }
- }
});
try {
await OpenAIChatCompletionController(req, res);
@@ -699,23 +627,37 @@ describe('OpenAIChatCompletionController', () => {
.map(([frame]) => frame)
.filter((frame) => frame !== 'data: [DONE]\n\n')
.map((frame) => JSON.parse(frame.slice(6)));
- expect(
- frames
- .flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
- .map((call) => call.function?.arguments ?? '')
- .join(''),
- ).toBe('{"city":"Madrid"}');
- expect(
- frames
- .flatMap((frame) => frame.choices[0].delta.tool_calls ?? [])
- .find((call) => call.id).function.name,
- ).toBe('get_time');
+ const calls = frames.flatMap((frame) => frame.choices[0].delta.tool_calls ?? []);
+ expect(calls).toEqual([
+ { index: 0, id: 'a', type: 'function', function: { name: 'get_time', arguments: '' } },
+ { index: 0, function: { arguments: '{"city":"Madrid"}' } },
+ {
+ index: 1,
+ id: 'call_0',
+ type: 'function',
+ function: { name: 'get_time', arguments: '' },
+ },
+ { index: 1, function: { arguments: '{"city":"Paris"}' } },
+ ]);
expect(frames.at(-1).choices[0].finish_reason).toBe('tool_calls');
} else {
- expect(
- res.json.mock.calls[0][0].choices[0].message.tool_calls[0].function.arguments,
- ).toBe('{"city":"Madrid"}');
+ const choice = res.json.mock.calls[0][0].choices[0];
+ expect(choice.message.tool_calls).toEqual([
+ {
+ id: 'a',
+ type: 'function',
+ function: { name: 'get_time', arguments: '{"city":"Madrid"}' },
+ },
+ {
+ id: 'call_0',
+ type: 'function',
+ function: { name: 'get_time', arguments: '{"city":"Paris"}' },
+ },
+ ]);
+ expect(choice.finish_reason).toBe('tool_calls');
}
+ expect(JSON.stringify(res.write.mock.calls)).not.toContain('DO_NOT_SEND');
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('DO_NOT_SEND');
} finally {
for (const [name, implementation] of originals)
api[name].mockImplementation(implementation);
@@ -723,21 +665,56 @@ describe('OpenAIChatCompletionController', () => {
},
);
- it('records completed model usage even when terminal snapshot validation fails', async () => {
+ it('discards client delegation on failure and ignores late accepted responses', async () => {
+ const api = require('@librechat/api');
+ api.validateRequest.mockReturnValueOnce({ request: req.body });
mockProcessStream.mockImplementationOnce(async () => {
- const h = require('@librechat/api').createRun.mock.calls.at(-1)[0].customHandlers;
- await h.on_run_step.handle('on_run_step', {
- id: 'bad',
- stepDetails: {
- type: 'tool_calls',
- tool_calls: [{ id: 'a', function: { name: 'get_time', arguments: 'NOT-JSON' } }],
- },
+ const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'before-failure',
+ agentId: 'agent-123',
+ toolCalls: [{ id: 'a', name: 'get_time', args: { secret: 'DO_NOT_SEND' } }],
+ toolCallDispositions: ['client'],
+ invalidToolCalls: [],
+ });
+ throw new Error('provider failed');
+ });
+ await OpenAIChatCompletionController(req, res);
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('DO_NOT_SEND');
+ expect(api.buildNonStreamingResponse).not.toHaveBeenCalled();
+ const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'too-late',
+ agentId: 'agent-123',
+ toolCalls: [{ id: 'late', name: 'get_time', args: { city: 'Late' } }],
+ toolCallDispositions: ['client'],
+ invalidToolCalls: [],
+ });
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('Late');
+ });
+
+ it('fails closed on an invalid accepted client call without returning its arguments', async () => {
+ const api = require('@librechat/api');
+ api.validateRequest.mockReturnValueOnce({ request: req.body });
+ mockProcessStream.mockImplementationOnce(async () => {
+ const { customHandlers: handlers } = api.createRun.mock.calls.at(-1)[0];
+ await handlers.on_model_response.handle('on_model_response', {
+ type: 'model_response',
+ id: 'invalid-client',
+ agentId: 'agent-123',
+ toolCalls: [{ id: 'a', name: '', args: { secret: 'PRIVATE_ARGUMENTS' } }],
+ toolCallDispositions: ['client'],
+ invalidToolCalls: [],
});
});
await OpenAIChatCompletionController(req, res);
- expect(mockRecordCollectedUsage).toHaveBeenCalledTimes(1);
- expect(require('@librechat/api').buildNonStreamingResponse).not.toHaveBeenCalled();
- expect(JSON.stringify(res.json.mock.calls)).not.toContain('NOT-JSON');
+ expect(mockExecution.settle).toHaveBeenCalledWith(
+ expect.objectContaining({ message: 'Accepted tool call is missing its name' }),
+ );
+ expect(api.buildNonStreamingResponse).not.toHaveBeenCalled();
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('PRIVATE_ARGUMENTS');
});
it('enrolls, starts, and settles the remote execution lifecycle', async () => {
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 0aa760bcc4..1910cab8ef 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -1,6 +1,9 @@
const { nanoid } = require('nanoid');
const { logger } = require('@librechat/data-schemas');
const { Callback, formatAgentMessages } = require('@librechat/agents');
+const {
+ createOpenAIToolCallStream: createAcceptedToolCallStream,
+} = require('@librechat/agents/openai');
const {
EModelEndpoint,
ResourceType,
@@ -60,9 +63,6 @@ const {
createToolExecuteHandler,
createOwnedToolEndHandler,
buildNonStreamingResponse,
- OpenAIRunStepHandler,
- OpenAIRunStepDeltaHandler,
- createOpenAIToolCallStream,
completeOpenAIToolCalls,
createOpenAIStreamTracker,
resolveAgentScopedSkillIds,
@@ -981,12 +981,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
};
- /**
- * Shared by both run-step events, because the outward index a client keys
- * tool-call fragments by is allocated per call and belongs to neither
- * event alone.
- */
- const toolCallStream = createOpenAIToolCallStream({
+ const toolCallStream = createAcceptedToolCallStream({
signal: execution.signal,
toolCalls: isStreaming ? tracker.toolCalls : aggregator.toolCalls,
...(isStreaming && {
@@ -996,6 +991,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
// Event handlers for OpenAI-compatible streaming
const handlers = {
+ ...toolCallStream.handlers,
// Text content streaming
on_message_delta: createHandler((data) => {
const content = data?.delta?.content;
@@ -1021,12 +1017,6 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
}),
- // Tool call initiation - declares id and name (from on_run_step)
- on_run_step: new OpenAIRunStepHandler(toolCallStream),
-
- // Tool call argument streaming (from on_run_step_delta)
- on_run_step_delta: new OpenAIRunStepDeltaHandler(toolCallStream),
-
// Usage tracking
on_chat_model_end: {
handle: (_event, data, metadata, graph) => {
@@ -1038,7 +1028,6 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
}
},
},
- on_run_step_completed: new OpenAIRunStepHandler(toolCallStream),
// Use proper ToolEndHandler for processing artifacts (images, file citations, code output)
on_tool_end: createOwnedToolEndHandler(toolEndCallback, logger),
on_chain_stream: createHandler(),
diff --git a/packages/api/src/agents/openai/README.md b/packages/api/src/agents/openai/README.md
index f259fe42d6..a2bbc24899 100644
--- a/packages/api/src/agents/openai/README.md
+++ b/packages/api/src/agents/openai/README.md
@@ -1,22 +1,26 @@
# Agents API response projection
-This module projects an **agent run**, which can include several model invocations and server-executed tools, onto an OpenAI-compatible response. It is not a transparent proxy for a single model completion. Changing tool execution ownership or terminal-turn selection is a separate protocol decision.
+This module projects an **agent run**, which can include several model invocations and server-executed tools, onto an OpenAI-compatible response. It is not a transparent proxy for a single model completion. Only explicitly client-owned calls in graph-accepted model responses may become outward `tool_calls`; SDK- and provider-executed calls stay inside the run. Binding caller-supplied tool schemas and client execution remains a separate feature.
## Owners and boundaries
```text
-provider adapter -> agents graph -> run-step declarations / argument deltas
+provider adapter -> agents graph -> accepted model response + tool ownership
|
- tool-call projection
+ SDK accepted-result projector
/ \
SSE chunks JSON accumulator
\ /
successful response completion
```
-The Express controller and packaged `createAgentChatCompletion` service both use the same tool-call projection in streaming and non-streaming mode. The service's content handlers also share text, reasoning and usage handling between modes. The controller retains its existing run lifecycle, usage recording, artifact writes and authorization boundaries.
+The mounted `/api/agents/v1/chat/completions` Express controller and packaged `createAgentChatCompletion` service both register the SDK's `on_model_response` and `on_model_tools_claimed` handlers for tool projection in streaming and non-streaming mode. Text, reasoning, usage, host-tool execution, billing, artifact writes and authorization retain their respective host handlers. Both hosts call the SDK projection's `finish` after successful execution and `abort` on failure.
-## Identity
+## Legacy run-step projector (compatibility export only)
+
+`createOpenAIToolCallStream`, `OpenAIRunStepHandler` and `OpenAIRunStepDeltaHandler` remain exported for existing consumers and their contract tests. Neither in-repo Chat Completions host registers them. The following identity, fragment and terminal rules describe **only** this legacy projector.
+
+### Identity
- A declaring run step owns call identity. Optional provider IDs are aliases, not a prerequisite. Declaration slots keep id-less calls distinct and make snapshot replay idempotent. Provider IDs can repeat in later steps and are not completion-wide identities.
- Outward indexes are allocated once per call across the response. Raw ID substrings are assembled by provider index; shared prefixes such as `call_` are never cross-call aliases. Calls without IDs receive `call_<index>`; collisions receive a suffix. Internal tool execution IDs are not rewritten.
@@ -24,7 +28,7 @@ The Express controller and packaged `createAgentChatCompletion` service both use
- Callers without the graph object use metadata scope; callers without that metadata are isolated by step. This fallback cannot reconstruct a missing retry/segment identity.
- Explicit and identified provider indexes take precedence over positional fallback. Positions are used only for multi-call declarations. An unbound singleton may adopt its first provider index; it does not absorb arbitrary later indexes.
-## Argument representations
+### Argument representations
A run-step declaration can contain a **snapshot**: native `args` or OpenAI-shaped `function.arguments`. A run-step delta carries an **append-only fragment**. They must never be concatenated as though they were the same representation.
@@ -38,7 +42,7 @@ Consequently, **tool-call chunks are published only at successful response compl
Name/ID/argument fragments are append-only and take precedence over the corresponding declaration snapshot. Snapshot replay is idempotent; raw fragments are not deduplicated because identical adjacent fragments can be legitimate and the events carry no sequence token. Split IDs require a provider index for unambiguous correlation. Exactly-once raw dispatch remains an upstream requirement.
-## Terminal behavior
+### Terminal behavior
`completeOpenAIToolCalls` wraps execution and owns the success/failure boundary. The controller schedules completed-run usage recording before final validation.
@@ -53,13 +57,15 @@ Name/ID/argument fragments are append-only and take precedence over the correspo
Missing names, missing arguments, malformed JSON or unattributable argument data fail terminal projection with bounded errors that omit provider content. A snapshot never repairs a truncated raw stream. Projection bookkeeping is response-local and released on finish/abort; only successfully validated calls are materialized for the response builder. Publication seals before calling the transport, so a transport error or reentrant finish cannot duplicate calls. Already transmitted frames cannot be retracted.
-The existing finish-reason policy is preserved: a response with final text after server-executed tools remains `stop`. Historical tool calls are still exposed by this API. This patch does not make it safe to interpret every advertised call as a new instruction for the caller to execute.
+## Accepted-result terminal behavior
+
+The SDK projector accepts only client-disposition calls from graph-accepted responses. A newer accepted text/internal result or a model-tool claim discards superseded calls for that agent. Calls are validated, given unique outward IDs and emitted at successful response completion; failed or aborted runs never publish buffered calls. Internal tools followed by a text answer finish with `stop` and no outward calls. The shared response builders use `tool_calls` as the finish reason when client calls exist without text.
## Verification and limits
- `toolCalls.contract.spec.ts`: shared field types, strings/objects, partial names and IDs, optional IDs, declaration order and transport reentrancy.
- `toolCalls.spec.ts`: identity, representations, ordering, replay, malformed input, failure and abort.
-- `toolCalls.graph.spec.ts`: real SDK interleaving, complete-only chunks and stream segments.
-- `service.spec.ts` and the Express controller spec: both response modes, actual serializers, fallback flush and failure/usage ordering.
+- `toolCalls.graph.spec.ts`: real SDK run with an internally executed tool, plus legacy interleaving and segments.
+- `service.spec.ts` and the Express controller spec: both response modes, actual serializers, internal-call suppression, accepted client calls, claim discard and failure behavior.
-These tests do not run a live provider, real tool side effects, a distributed multi-agent deployment or a persisted resume. There is no new database, cache, authorization policy or migration. Code and built packages must deploy together. No cross-version event identity is invented when the upstream source omits it.
+These tests do not run a live provider, a distributed multi-agent deployment or a persisted resume. The graph test executes a local tool but does not exercise the mounted HTTP server. There is no new database, cache, authorization policy or migration. Code and built packages must deploy together.