feat(sdk): add async subagent middleware for remote LangGraph servers by colifran · Pull Request #323 · langchain-ai/deepagentsjs

Colin Francis (colifran) · 2026-03-18T06:38:31Z

Summary

Adds AsyncSubAgentMiddleware for launching background jobs on remote LangGraph deployments via the LangGraph SDK. This is the JS port of the Python AsyncSubAgentMiddleware.

The middleware provides five tools:

start_async_task — creates a thread + run on a remote server, returns a job ID immediately
check_async_task — fetches run status and extracts the result on completion
update_async_task — sends follow-up instructions by creating a new run on the same thread (with multitaskStrategy: "interrupt")
cancel_async_task — cancels a running job
list_async_tasks — lists all tracked jobs with live statuses fetched in parallel

Job state is persisted in the asyncSubAgentJobs state channel via a ReducedValue reducer, so jobs survive context compaction and summarization.

Integrated into createDeepAgent via the asyncSubagents parameter.

Tests

77 unit tests covering:

State reducer merge logic and immutability
ClientCache — caching, key deduplication, default x-auth-scheme header injection
All 5 tools — happy paths, unknown job IDs, SDK errors, graceful degradation (e.g. threads.getState failure on success still returns a result)
buildCheckResult — message content extraction, non-object fallback, empty messages fallback, error status
buildListTool — status filtering, terminal status SDK call skipping, live status updates, parallel fetching
createAsyncSubAgentMiddleware — validation (empty list, duplicate names), tool wiring, system prompt injection, independent instances

changeset-bot · 2026-03-18T06:38:35Z

🦋 Changeset detected

Latest commit: e7e959d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
deepagents	Minor
deepagents-acp	Patch
@deepagents/evals	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-19T03:44:48Z

Open in StackBlitz

npm i https://pkg.pr.new/deepagents-acp@323

npm i https://pkg.pr.new/deepagents@323

npm i https://pkg.pr.new/@langchain/sandbox-standard-tests@323

commit: e7e959d

libs/deepagents/src/middleware/async_subagents.ts

Hunter Lovell (hntrl)

very nice!

… servers (#323)" This reverts commit 2bebf30.

…h servers (#323)" (#351) * Revert "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" This reverts commit 2bebf30. * regen lock

…LangGraph servers (#323)" (#351)" This reverts commit 367e43a.

… LangGraph servers (#323)" (#351)" (#354) * Revert "revert: "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" (#351)" This reverts commit 367e43a. * use any backend protocol

…#323) * add langgraph sdk dep * launch tool, check tool * update tool and cancel tool * update and cancel tool tests * list async subagent jobs tool * list subagent jobs tool and create middleware * wire in async subagents * create and use state schema, update message to messages * tests * AsyncSubagent -> AsyncSubAgent * regen lock * fix import * bug fixes * fix exports * fix tool names * fix check result bug * adjust tool names and tests * add createdAt, updatedAt, and checkAt fields * changeset * job->task * SubAgent->subagent in docstrings * update tool names * use tool runtime * update naming to match async task naming convention * remove extra custom middleware added during merge conflicts * launch_async_task->start_async_task * buildLaunchTool->buildStartTool

…h servers (#323)" (#351) * Revert "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" This reverts commit 2bebf30. * regen lock

… LangGraph servers (#323)" (#351)" (#354) * Revert "revert: "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" (#351)" This reverts commit 367e43a. * use any backend protocol

* Revert "revert: "feat(deepagents): support multimodal files for backends (#298)" (#352)" (#353) This reverts commit 03ea1c9. * revert: "revert: "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" (#351)" (#354) * Revert "revert: "feat(sdk): add async subagent middleware for remote LangGraph servers (#323)" (#351)" This reverts commit 367e43a. * use any backend protocol * Reapply "chore(deepagents): refactor backend method names - `lsInfo` -> `ls`, …" (#349) (#356) This reverts commit 573479d. * Reapply "chore(sdk): unify sync subagents and async subagents into a single pr…" (#348) (#355) This reverts commit 96dc34c. * chore: align alpha with main (#358) * fix(deepagents): remove orphaned ToolMessages for Gemini compatibility (#335) * fix(deepagents): remove orphaned ToolMessages for Gemini compatibility * Fix ToolMessages for Gemini compatibility --------- Co-authored-by: Christian Bromann <git@bromann.dev> * fix(deepagents): throw on built-in tool collision (#330) * add error * Create big-horses-fail.md * add config error class * cr --------- Co-authored-by: Christian Bromann <git@bromann.dev> * fix(deepagents): use `crypto.randomUUID()` instead of uuid (#336) * fix(deepagents): use crypto.randomUUID() instead of uuid * update pnpm-lock * Create grumpy-weeks-wave.md * Update libs/deepagents/src/middleware/fs.int.test.ts * feat(deepagent): add LangSmithSandbox (#324) * feat(deepagent): add LangSmithSandbox * Change deepagents version from patch to minor * format * fix tests * format * make it a patch * cr * cr * fix * cr * chore: version packages (#321) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * regen lockfile * fix langsmith tests so that they use backend protocol v2 methods * format --------- Co-authored-by: pawel-twardziak <pawel.twardziak.dev@gmail.com> Co-authored-by: Christian Bromann <git@bromann.dev> Co-authored-by: Maahir Sachdev <maahir.sachdev@langchain.dev> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * feat(deepagents): add completion notifier middleware for async subagents (#334) Port of langchain-ai/deepagents#2119 to TypeScript. Adds a createCompletionNotifierMiddleware that async subagents can use to proactively notify their supervisor when they complete or error, closing the gap where the supervisor only learns about completion when someone calls check_async_task. - New createCompletionNotifierMiddleware with afterAgent and wrapModelCall hooks - Uses @langchain/langgraph-sdk Client to send runs.create() to the supervisor's thread - Reads parent_thread_id from subagent state (injected by start_async_task) - Derives task_id from runtime.configurable.thread_id - Silently no-ops if parent context is missing - Guards against duplicate notifications - 22 unit tests covering all hooks, edge cases, and error paths fix(deepagents): make url required in completion notifier (no ASGI in JS) JS does not have ASGI transport like Python, so the url parameter must be provided explicitly. Removed all ASGI references from docs and the localhost fallback default. fix(deepagents): throw on built-in tool collision (#330) * add error * Create big-horses-fail.md * add config error class * cr --------- Co-authored-by: Christian Bromann <git@bromann.dev> fix(deepagents): use `crypto.randomUUID()` instead of uuid (#336) * fix(deepagents): use crypto.randomUUID() instead of uuid * update pnpm-lock * Create grumpy-weeks-wave.md * Update libs/deepagents/src/middleware/fs.int.test.ts feat(deepagent): add LangSmithSandbox (#324) * feat(deepagent): add LangSmithSandbox * Change deepagents version from patch to minor * format * fix tests * format * make it a patch * cr * cr * fix * cr regen lockfile linting linting add missing url property chore: version packages (#321) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> changeset regen lockfil * chore: enter alpha pre-release * chore: target alpha for releases * chore: version packages (alpha) (#359) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore(deepagents): extend supported backend file types (#363) * extend supported file types * Create strong-tigers-share.md --------- Co-authored-by: Hunter Lovell <40191806+hntrl@users.noreply.github.com> * chore(deepagents): implement async subagents + use stream example (#360) * async subagents + use stream example * fix lockfile * format * linting * readme and linting * format * proactively send responses when subagents complete * better examples * feat(deepagents): rename completion notifier to completion callback and align with Python (#361) * feat(deepagents): rename completion notifier to completion callback and align with Python PR - Rename completion_notifier.ts -> completion_callback.ts to match Python's completion_callback.py naming - Rename exports: createCompletionNotifierMiddleware -> createCompletionCallbackMiddleware, CompletionNotifierOptions -> CompletionCallbackOptions - Rename state key: parent_thread_id -> callbackThreadId, option: parentGraphId -> callbackGraphId - Make url optional (Python allows omitting for ASGI transport) - Match Python's strict error behavior: throw on empty messages, non-AIMessage types, and missing callbackThreadId - Add truncation suffix with task_id hint for long messages - Use generic error message in wrapModelCall (don't leak error details) - Remove duplicate notification guard (Python notifies on every error) - Add extractCallbackContext to async_subagents.ts: injects callbackThreadId into subagent input state when launching via start_async_task - Add tests for extractCallbackContext and callback context injection * cr * Rename completion notifier to completion callback Renamed completion notifier to completion callback for consistency with Python. * fix(sdk): `AsyncTask` `updatedAt` field doesn't update on task status changes (#400) * update updatedAt field to change on any task update * added changeset * chore: set up self hosted async subagent example (#399) * self hosted async subagent example * with postgres * formatting * eslint disable no console * fix dockerfile and readme * Update examples/async-subagent-server/server.ts Co-authored-by: Christian Bromann <git@bromann.dev> --------- Co-authored-by: Christian Bromann <git@bromann.dev> * chore(sdk): update async subagent middleware for agent protocol (#394) * update async subagent middleware for agent protocol * add changeset * Update libs/deepagents/src/middleware/async_subagents.ts Co-authored-by: Hunter Lovell <40191806+hntrl@users.noreply.github.com> * Update libs/deepagents/src/middleware/async_subagents.ts Co-authored-by: Hunter Lovell <40191806+hntrl@users.noreply.github.com> * Update libs/deepagents/src/middleware/async_subagents.ts Co-authored-by: Hunter Lovell <40191806+hntrl@users.noreply.github.com> * differentiate agent protocol --------- Co-authored-by: Hunter Lovell <40191806+hntrl@users.noreply.github.com> * chore(repo): migrate linting and formatting to oxc tooling (#391) * chore(repo): migrate linting and formatting to oxc tooling * cr * cr * chore(lint): clean up console disables for oxlint * cr * Apply suggestions from code review Co-authored-by: Christian Bromann <git@bromann.dev> --------- Co-authored-by: Christian Bromann <git@bromann.dev> * refactor(deepagents): clean up createDeepAgent middleware wiring (#392) * refactor(deepagents): clean up createDeepAgent middleware wiring * fix(deepagents): avoid duplicate HITL middleware on subagents * add comments, remove iife * Create ten-masks-flow.md * fix(deepagents): align prompt templates with runtime behavior (#393) * fix(deepagents): align prompt templates with runtime behavior * chore: add changeset for prompt alignment fixes * cr * cr * fix store backend and tests * lint * fix rests and resolveBackend * lint * fix failing tests * revert adapt resolve backend * fix resolve backend * better variable name * fix backend factory to return a maybe promise * mark resolve backend as internal * format --------- Co-authored-by: Colin Francis <131073567+colifran@users.noreply.github.com> Co-authored-by: pawel-twardziak <pawel.twardziak.dev@gmail.com> Co-authored-by: Christian Bromann <git@bromann.dev> Co-authored-by: Maahir Sachdev <maahir.sachdev@langchain.dev> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Colin Francis <colin.francis@langchain.dev>

Colin Francis (colifran) added 10 commits March 18, 2026 17:09

add langgraph sdk dep

515f358

launch tool, check tool

18d865d

update tool and cancel tool

6c53c8b

update and cancel tool tests

b55b5f8

list async subagent jobs tool

fcc5569

list subagent jobs tool and create middleware

b3e4031

wire in async subagents

2dd7703

create and use state schema, update message to messages

173532f

tests

3669c60

AsyncSubagent -> AsyncSubAgent

5108002

Colin Francis (colifran) force-pushed the colifran/async-subagents branch from d9d9a3e to 5108002 Compare March 19, 2026 00:11

Colin Francis (colifran) added 4 commits March 18, 2026 17:12

regen lock

bc2426b

fix import

26e2ded

bug fixes

756d557

fix exports

f818095

fix tool names

af91800

Colin Francis (colifran) marked this pull request as ready for review March 19, 2026 04:23

fix check result bug

9d10d4d

Christian Bromann (christian-bromann) reviewed Mar 19, 2026

View reviewed changes

libs/deepagents/src/middleware/async_subagents.ts Outdated Show resolved Hide resolved

Colin Francis (colifran) added 3 commits March 19, 2026 13:46

adjust tool names and tests

8c66cec

add createdAt, updatedAt, and checkAt fields

a743e50

changeset

8ea9ee4

Colin Francis (colifran) requested a review from Christian Bromann (christian-bromann) March 19, 2026 21:42

Colin Francis (colifran) added 2 commits March 19, 2026 15:07

job->task

c7ad428

SubAgent->subagent in docstrings

1b86bcf

Hunter Lovell (hntrl) mentioned this pull request Mar 20, 2026

docs(deepagents): add async subagents documentation langchain-ai/docs#3227

Merged

Colin Francis (colifran) added 2 commits March 20, 2026 10:04

update tool names

19353f6

use tool runtime

b4638b9

Hunter Lovell (hntrl) approved these changes Mar 20, 2026

View reviewed changes

Colin Francis (colifran) and others added 5 commits March 20, 2026 11:59

update naming to match async task naming convention

1722aa8

Merge branch 'main' into colifran/async-subagents

dc112ee

remove extra custom middleware added during merge conflicts

0959a12

launch_async_task->start_async_task

c73c712

buildLaunchTool->buildStartTool

e7e959d

Colin Francis (colifran) merged commit 2bebf30 into main Mar 20, 2026
15 checks passed

Colin Francis (colifran) deleted the colifran/async-subagents branch March 20, 2026 21:31

github-actions bot mentioned this pull request Mar 20, 2026

chore: version packages #321

Merged

Colin Francis (colifran) added a commit that referenced this pull request Mar 23, 2026

Revert "feat(sdk): add async subagent middleware for remote LangGraph…

2a25843

… servers (#323)" This reverts commit 2bebf30.

Colin Francis (colifran) added a commit that referenced this pull request Mar 23, 2026

Revert "revert: "feat(sdk): add async subagent middleware for remote …

23d51f8

…LangGraph servers (#323)" (#351)" This reverts commit 367e43a.

Hunter Lovell (hntrl) mentioned this pull request Apr 1, 2026

chore: merge alpha into main #404

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(sdk): add async subagent middleware for remote LangGraph servers #323

feat(sdk): add async subagent middleware for remote LangGraph servers #323
Colin Francis (colifran) merged 28 commits intomainfrom
colifran/async-subagents

Colin Francis (colifran) commented Mar 18, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 18, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Hunter Lovell (hntrl) left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Colin Francis (colifran) commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tests

Uh oh!

changeset-bot bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Hunter Lovell (hntrl) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Colin Francis (colifran) commented Mar 18, 2026 •

edited

Loading

changeset-bot bot commented Mar 18, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 19, 2026 •

edited

Loading