Skip to content

fix #14249: Load agent subagents in Responses & OpenAI-compat APIs - #14250

Closed
houbie wants to merge 12 commits into
LibreChat-AI:mainfrom
houbie:fix/api-subagents
Closed

houbie wants to merge 12 commits into
LibreChat-AI:mainfrom
houbie:fix/api-subagents

Conversation

@houbie

@houbie houbie commented Jul 14, 2026

Copy link
Copy Markdown

Summary

Subagents (agent.subagents.agent_ids) were only resolved in the chat UI
initialization path. The Responses API (/v1/responses) and the
OpenAI-compatible API (/v1/chat/completions) only ran handoff-edge discovery,
so a primary agent invoked through those endpoints never had its subagent spawn
targets loaded — the model was unaware of the subagent and could not delegate to
it.

This PR extracts the subagent-resolution logic into a shared helper and wires it
into all three entry points so behavior is identical everywhere.

Fixes #

Changes

  • New packages/api/src/agents/subagents.ts — resolveSubagents() helper
    containing the logic previously inline in initialize.js: nested-tree BFS,
    MAX_SUBAGENT_DEPTH / MAX_SUBAGENT_GRAPH_NODES limits, id dedupe, self-cycle
    guard, pure-subagent pruning (kept in agentToolContexts via
    onAgentInitialized for ON_TOOL_EXECUTE), and capability-disabled stripping.
  • Wire resolveSubagents into responses.js and openai.js, using the same
    REMOTE_AGENT sharing boundary and remote permission check as the primary
    agent.
  • Refactor initialize.js (chat path) to use the shared helper — no behavior
    change (verified by the existing subagent suite).
  • Add subagentAgentConfigs to the InitializedAgent type and export the new
    module from packages/api/src/agents/index.ts.
  • Perf: only fetch getModelsConfig when handoff discovery or real subagent
    loading actually needs it, keeping the common single-agent request off that
    (potentially network-bound) path.
  • Hardening: call resolveSubagents unconditionally in the remote paths so that
    when the subagents capability is disabled, any persisted subagents are
    stripped and createRun can't expose self-spawn.
  • Tests: add unit tests for resolveSubagents; add the resolveSubagents mock
    to the Responses/OpenAI controller specs; update log-prefix assertions in
    initialize.spec.js.

Test plan

  • cd packages/api && npx jest subagents.spec.ts (6 passed)
  • cd api && npx jest server/services/Endpoints/agents/initialize.spec.js -t "subagent" (11 passed / 4 skipped)
  • cd api && npx jest server/controllers/agents/__tests__/responses.unit.spec.js server/controllers/agents/__tests__/openai.spec.js (26 passed)
  • npm run build:data-provider and packages/api build succeed
  • Manual: invoke a parent agent with a configured subagent via POST /v1/responses and confirm the subagent spawn tool is exposed and callable

Subagents (`agent.subagents.agent_ids`) were only resolved in the chat UI
initialization path. The Responses API (`/v1/responses`) and the
OpenAI-compatible API (`/v1/chat/completions`) only ran handoff-edge
discovery, so a primary agent invoked through those endpoints never had its
subagent spawn targets loaded — the model was unaware of the subagent and
could not delegate to it.

Extract the subagent-resolution logic from
`api/server/services/Endpoints/agents/initialize.js` into a shared
`resolveSubagents` helper in `packages/api/src/agents/subagents.ts` and wire
it into all three entry points so behavior is identical everywhere.

- Add `resolveSubagents` (nested-tree BFS, depth/graph-node limits, dedupe,
  cycle guard, pure-subagent pruning, per-agent tool-context callback).
- Wire it into the Responses and OpenAI-compat controllers using the same
  `REMOTE_AGENT` sharing boundary as the primary agent.
- Refactor the chat path to use the shared helper (no behavior change).
- Only fetch `getModelsConfig` when handoff discovery or real subagent
  loading needs it, keeping the common single-agent request off that path.
- Call `resolveSubagents` unconditionally in the remote paths so that when
  the `subagents` capability is disabled, persisted `subagents` are stripped
  and `createRun` can't expose self-spawn.
- Add unit tests for `resolveSubagents` and mocks for the controller specs.

Co-authored-by: Cursor <cursoragent@cursor.com>
@houbie houbie changed the title fix #1424: Load agent subagents in Responses & OpenAI-compat APIs fix #14249: Load agent subagents in Responses & OpenAI-compat APIs Jul 14, 2026
@houbie

houbie commented Jul 14, 2026

Copy link
Copy Markdown
Author

fixes #14249

@danny-avila

Copy link
Copy Markdown
Collaborator

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: f8bd3b7494

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila

Copy link
Copy Markdown
Collaborator

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: f8bd3b7494

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ivo and others added 11 commits July 15, 2026 09:10
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Adds a fork-only workflow that builds and pushes librechat-dev images to
public ghcr.io without requiring upstream Docker Hub secrets.

Co-authored-by: Cursor <cursoragent@cursor.com>
Fail fast with a clear message when repository workflow permissions
are read-only instead of read and write.

Co-authored-by: Cursor <cursoragent@cursor.com>
Fail fast with a clear message when repository workflow permissions
are read-only instead of read and write.

Co-authored-by: Cursor <cursoragent@cursor.com>
Job-level packages:write is sufficient even when the repository default
workflow token permission is read-only.

Co-authored-by: Cursor <cursoragent@cursor.com>
Avoid flaky arm64 npm ci failures under QEMU on GitHub-hosted runners.

Co-authored-by: Cursor <cursoragent@cursor.com>
Use repository_owner for registry login, link images to the source repo,
retry visibility updates, and avoid failing after a successful push.

Co-authored-by: Cursor <cursoragent@cursor.com>
# Conflicts:
#	.github/workflows/publish-fork-images.yml
# Conflicts:
#	api/server/services/Endpoints/agents/initialize.js
@houbie

houbie commented Sep 3, 2026

Copy link
Copy Markdown
Author

replaced by #15534

@houbie houbie closed this Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants