feat(sdk): add completion notifier middleware for async subagents by hntrl · Pull Request #2119 · langchain-ai/deepagents

Hunter Lovell (hntrl) · 2026-03-20T21:48:39Z

Summary

Adds a pre-bundled CompletionNotifierMiddleware 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.

Why

The async subagent protocol is fire-and-forget: the supervisor launches a task and only discovers its outcome when it (or the user) polls via check_async_task. This means the supervisor can't proactively relay results -- the user has to ask. The completion notifier solves this by having the subagent push a notification to the supervisor's thread when it finishes.

This is an opt-in middleware added to the subagent's stack, not the supervisor's. If the subagent doesn't use it, the extra input keys are silently ignored by LangGraph (verified against both in-process invoke() and langgraph dev via SDK).

Architecture

Supervisor                    Subagent
    |                            |
    |--- start_async_task -----> |
    |<-- task_id (immediately) - |
    |                            |  (working...)
    |                            |  (done!)
    |                            |
    |<-- runs.create(            |
    |      supervisor_thread,    |
    |      "completed: ...")     |
    |                            |
    |  (wakes up, sees result)   |

Parent context propagation: The supervisor's start_async_task tool now includes parent_thread_id, parent_assistant_id, and task_id in the subagent's input state. The notifier reads these from state (not config), which means they survive thread interrupts and update_async_task calls. If the subagent doesn't have the middleware, these keys are silently dropped.

Notification format: Includes task_id so the supervisor can correlate notifications back to specific tracked jobs when multiple tasks of the same subagent type run concurrently:

[task_id=thread_abc][subagent=researcher] Completed. Result: <summary>
[task_id=thread_abc][subagent=researcher] Error: <error message>

Changes

New: `CompletionNotifierMiddleware` (`deepagents/middleware/completion_notifier.py`)

aafter_agent hook sends a completion notification with result summary (truncated to 500 chars)
awrap_model_call hook catches errors and sends an error notification before re-raising
CompletionNotifierState adds parent_thread_id, parent_assistant_id, and task_id to the subagent's state schema
Notifies only once per run (guards against duplicates)
Silently no-ops if parent context is missing (subagent launched without a supervisor)
Uses get_client() with no URL (ASGI transport for same-deployment)

Modified: `async_subagents.py`

Added _extract_parent_context() to read supervisor's thread_id and assistant_id from tool runtime config
start_async_task (sync + async) now includes task_id, parent_thread_id, parent_assistant_id in the subagent's input

Modified: `pyproject.toml`

Added langgraph-sdk>=0.1.51 as a required dependency (was already imported unconditionally)

Exports

CompletionNotifierMiddleware exported from deepagents.middleware and top-level deepagents

Open questions

assistant_id availability: Need to validate that config.metadata.assistant_id is always present in deployed contexts. If there are cases where it's missing, the notifier silently no-ops (safe), but the notification won't fire.
Divergence from JS: The JS reference implementation passes parent IDs as constructor args at graph factory time (from config). The Python implementation reads them from state, which is a deliberate improvement (survives interrupts, no dynamic factory needed) but a divergence.

How to review

The core middleware is in completion_notifier.py -- start there. The async_subagents.py changes are mechanical (extract parent context, spread into input). Tests cover all the hooks, edge cases, and the parent context propagation.

Note

This PR was developed with assistance from an AI coding agent.

…structor arg, derive task_id from config

…te supervisors

codspeed-hq · 2026-03-20T22:20:04Z

Merging this PR will not alter performance

✅ 32 untouched benchmarks

_{Comparing hunter/notifier-middleware (6eec715) with main (e3443e7)}

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

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

…nts (#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

* 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>

feat(sdk): add completion notifier middleware for async subagents

15be32f

github-actions bot added deepagents Related to the `deepagents` SDK / agent harness dependencies Pull requests that update a dependency file feature New feature/enhancement or request for one internal User is a member of the `langchain-ai` GitHub organization size: L 500-999 LOC labels Mar 20, 2026

Hunter Lovell (hntrl) added 3 commits March 20, 2026 14:58

refactor(sdk): mark notifier as experimental, use parent_graph_id con…

1ee674f

…structor arg, derive task_id from config

refactor(sdk): remove subagent_name from completion notifier

653f768

feat(sdk): add url and headers params to completion notifier for remo…

9e5bddd

…te supervisors

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

feat(deepagents): add completion notifier middleware for async subagents langchain-ai/deepagentsjs#334

Merged

Eugene Yurtsev (eyurtsev) added 15 commits March 23, 2026 10:16

Merge branch 'main' into hunter/notifier-middleware

02d551a

x

6397990

x

ba2a4f9

x

1877b68

x

305d3b5

x

711364e

x

1a0e2a6

x

71fa7cd

x

780db8a

x

5666871

x

6b2a57c

x

cd25387

x

054190a

Merge branch 'main' into hunter/notifier-middleware

f1c614b

x

6eec715

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

feat(deepagents): rename completion notifier to completion callback and align with Python langchain-ai/deepagentsjs#361

Merged

Hunter Lovell (hntrl) marked this pull request as ready for review March 27, 2026 14:59

Hunter Lovell (hntrl) requested a review from Mason Daugherty (mdrxy) as a code owner March 27, 2026 14:59

This comment was marked as spam.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(sdk): add completion notifier middleware for async subagents#2119

feat(sdk): add completion notifier middleware for async subagents#2119
Hunter Lovell (hntrl) wants to merge 19 commits intomainfrom
hunter/notifier-middleware

Hunter Lovell (hntrl) commented Mar 20, 2026

Uh oh!

codspeed-hq bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

This comment was marked as spam.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Hunter Lovell (hntrl) commented Mar 20, 2026

Summary

Why

Architecture

Changes

New: CompletionNotifierMiddleware (deepagents/middleware/completion_notifier.py)

Modified: async_subagents.py

Modified: pyproject.toml

Exports

Open questions

How to review

Uh oh!

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

Uh oh!

Merging this PR will not alter performance

Uh oh!

This comment was marked as spam.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

New: `CompletionNotifierMiddleware` (`deepagents/middleware/completion_notifier.py`)

Modified: `async_subagents.py`

Modified: `pyproject.toml`

codspeed-hq bot commented Mar 20, 2026 •

edited

Loading