feat(sdk): add async subagent middleware for remote LangGraph servers by hwchase17 · Pull Request #1758 · langchain-ai/deepagents

Harrison Chase (hwchase17) · 2026-03-10T04:20:32Z

Adds AsyncSubAgentMiddleware to the SDK, enabling agents to launch background jobs on remote LangGraph deployments via the LangGraph SDK. Unlike synchronous subagents that block until completion, async subagents return a job ID immediately — the main agent can continue working, check progress on demand, send follow-up instructions, or cancel jobs.

The CLI reads async subagent definitions from [async_subagents] in ~/.deepagents/config.toml and wires them in automatically.

Changes

Add AsyncSubAgentMiddleware in deepagents/middleware/async_subagents.py with five tools: launch_async_subagent, check_async_subagent, update_async_subagent, cancel_async_subagent, and list_async_subagent_jobs — each with sync + async implementations that return Command objects to persist job state
Track jobs via AsyncSubAgentState with a _jobs_reducer that merges updates into a dict[str, AsyncSubAgentJob], surviving context compaction
Cache LangGraph SDK clients per (url, headers) tuple in _ClientCache to avoid reconnecting on every tool call
Add async_subagents parameter to create_deep_agent in graph.py — when provided, appends AsyncSubAgentMiddleware to the middleware stack
Add load_async_subagents() in the CLI to parse config.toml and pass specs through to create_cli_agent in both interactive and server modes
Wire HITL interrupt config for launch_async_subagent, update_async_subagent, and cancel_async_subagent in the CLI's approval system
Export AsyncSubAgent, AsyncSubAgentJob, and AsyncSubAgentMiddleware from deepagents and deepagents.middleware

libs/cli/deepagents_cli/agent.py

William FH (hinthornw) · 2026-03-12T04:38:41Z

libs/deepagents/deepagents/middleware/async_subagents.py

+        if name not in self._async:
+            spec = self._agents[name]
+            self._async[name] = get_client(
+                url=spec["url"],


Should this default to None? In most cases we want to use the asgi transport, right?

url is now NotRequired in AsyncSubAgent and both get_sync and get_async use spec.get("url"), so omitting it falls through to ASGI transport. Does that make sense? Can you confirm?

libs/deepagents/deepagents/middleware/async_subagents.py

William FH (hinthornw) · 2026-03-12T04:40:48Z

libs/deepagents/deepagents/middleware/async_subagents.py

+            return error
+        spec = agent_map[subagent_type]
+        client = clients.sync(subagent_type)
+        thread = client.threads.create()


ooc: why do we need sync methods? Can we use the single async client and avoid the ssl cache hit and avoid the fact that sync client doesn't support asgi transport?

Do you think we can just remove them?

libs/deepagents/deepagents/middleware/async_subagents.py

libs/cli/deepagents_cli/main.py

William FH (hinthornw) · 2026-03-12T04:47:01Z

libs/cli/deepagents_cli/main.py


+        from deepagents_cli.agent import load_async_subagents
+
+        async_subagents = load_async_subagents() or None


ooc can we load from the server?

libs/deepagents/deepagents/middleware/async_subagents.py

open-swe · 2026-03-12T20:09:56Z

Reading this PR to understand the changes and architecture.

Introduces AsyncSubAgentMiddleware that uses the LangGraph SDK to launch, monitor, and update background runs on remote LangGraph deployments. Wired into create_deep_agent via a new async_subagents parameter.

…tically

The LangGraph Platform server requires the x-auth-scheme header to know which auth flow to use. Without it, requests fail with "Missing agent builder trigger auth scheme, and passthrough headers." Now included by default on all SDK client connections.

Adds load_async_subagents() to read [async_subagents] from config.toml and passes them through create_cli_agent to create_deep_agent. Wired into interactive mode, non-interactive mode, and model hot-swap paths.

The JSON job_id format caused JSONDecodeError when LLMs decomposed the structured data instead of passing it verbatim. Switched to an opaque thread_id::run_id format that LLMs treat as an atomic string. The parser is robust and accepts the canonical format, full launch output, and legacy JSON for backwards compatibility.

The update tool was using update_state which only appended a message without triggering a new run. After the original run finished, checking the job would show "success" with the update message as the result. Now update creates a new run on the same thread so the subagent processes the follow-up with full conversation history. Returns a new job_id for tracking. Also encodes agent name in job_id for correct client routing with multiple agent types.

When update_async_subagent is called while a run is still active, the default "reject" strategy would reject the new run. Now uses "interrupt" so the current run is stopped and the follow-up is processed immediately.

Adds launch_async_subagent and update_async_subagent to the CLI's interrupt_on map, matching the existing behavior for the sync task tool. check_async_subagent is read-only and doesn't require approval.

…returns Tools now accept ToolRuntime and return Command(update={...}) to write AsyncSubAgentJob records to the async_subagent_jobs state field, ensuring job metadata survives context compaction.

…bs from state

…ansport

ccurme (ccurme) · 2026-03-16T20:01:37Z

libs/deepagents/deepagents/middleware/async_subagents.py

+        key = self._cache_key(spec)
+        if key not in self._async:
+            self._async[key] = get_client(
+                url=spec.get("url"),


in what circumstances does this work when url is None? if we deploy both the deepagent and a dedicated async subagent through langgraph.json, would this work?

PR #1758 landed CLI code that passes `async_subagents` to `create_deep_agent()`, but the CLI still pins SDK 0.4.x which doesn't accept that kwarg — meaning even `async_subagents=None` raises `TypeError` at runtime. This switches to a conditional `**kwargs` pattern so the kwarg is only passed when async subagents are actually configured, keeping the CLI compatible with the pinned SDK until 0.5.0 ships.

…langchain-ai#1758) Adds `AsyncSubAgentMiddleware` to the SDK, enabling agents to launch background jobs on remote LangGraph deployments via the LangGraph SDK. Unlike synchronous subagents that block until completion, async subagents return a job ID immediately — the main agent can continue working, check progress on demand, send follow-up instructions, or cancel jobs. The CLI reads async subagent definitions from `[async_subagents]` in `~/.deepagents/config.toml` and wires them in automatically. ## Changes - Add `AsyncSubAgentMiddleware` in `deepagents/middleware/async_subagents.py` with five tools: `launch_async_subagent`, `check_async_subagent`, `update_async_subagent`, `cancel_async_subagent`, and `list_async_subagent_jobs` — each with sync + async implementations that return `Command` objects to persist job state - Track jobs via `AsyncSubAgentState` with a `_jobs_reducer` that merges updates into a `dict[str, AsyncSubAgentJob]`, surviving context compaction - Cache LangGraph SDK clients per `(url, headers)` tuple in `_ClientCache` to avoid reconnecting on every tool call - Add `async_subagents` parameter to `create_deep_agent` in `graph.py` — when provided, appends `AsyncSubAgentMiddleware` to the middleware stack - Add `load_async_subagents()` in the CLI to parse `config.toml` and pass specs through to `create_cli_agent` in both interactive and server modes - Wire HITL interrupt config for `launch_async_subagent`, `update_async_subagent`, and `cancel_async_subagent` in the CLI's approval system - Export `AsyncSubAgent`, `AsyncSubAgentJob`, and `AsyncSubAgentMiddleware` from `deepagents` and `deepagents.middleware` --------- Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com> Co-authored-by: Colin Francis <colin.francis@langchain.dev> Co-authored-by: Colin Francis <colinfrancis53@gmail.com> Co-authored-by: Mason Daugherty <github@mdrxy.com> Co-authored-by: Mason Daugherty <mason@langchain.dev>

…chain-ai#1931) PR langchain-ai#1758 landed CLI code that passes `async_subagents` to `create_deep_agent()`, but the CLI still pins SDK 0.4.x which doesn't accept that kwarg — meaning even `async_subagents=None` raises `TypeError` at runtime. This switches to a conditional `**kwargs` pattern so the kwarg is only passed when async subagents are actually configured, keeping the CLI compatible with the pinned SDK until 0.5.0 ships.

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

William FH (hinthornw) approved these changes Mar 12, 2026

View reviewed changes

Colin Francis (colifran) reviewed Mar 12, 2026

View reviewed changes

libs/deepagents/deepagents/middleware/async_subagents.py Outdated Show resolved Hide resolved

github-actions bot added size: XL 1000+ LOC and removed size: L 500-999 LOC labels Mar 12, 2026

Colin Francis (colifran) force-pushed the open-swe/598550c7-9d68-8519-3f24-5a92b98bea26 branch 4 times, most recently from 0e3c580 to ba35fd7 Compare March 16, 2026 18:56

Open SWE (open-swe) and others added 16 commits March 16, 2026 11:58

feat(sdk): add async subagents via remote langgraph servers

63ab36f

Introduces AsyncSubAgentMiddleware that uses the LangGraph SDK to launch, monitor, and update background runs on remote LangGraph deployments. Wired into create_deep_agent via a new async_subagents parameter.

remove api_key from AsyncSubAgent — SDK reads it from env vars automa…

c82bf8b

…tically

feat(cli): wire async subagents config from config.toml into CLI

8414b71

Adds load_async_subagents() to read [async_subagents] from config.toml and passes them through create_cli_agent to create_deep_agent. Wired into interactive mode, non-interactive mode, and model hot-swap paths.

fix(sdk): use interrupt multitask strategy for update tool

27b9ead

When update_async_subagent is called while a run is still active, the default "reject" strategy would reject the new run. Now uses "interrupt" so the current run is stopped and the follow-up is processed immediately.

feat(cli): gate async subagent launch/update behind HITL approval

314a33a

Adds launch_async_subagent and update_async_subagent to the CLI's interrupt_on map, matching the existing behavior for the sync task tool. check_async_subagent is read-only and doesn't require approval.

feat(sdk): persist async subagent job IDs in agent state via Command …

b134f7b

…returns Tools now accept ToolRuntime and return Command(update={...}) to write AsyncSubAgentJob records to the async_subagent_jobs state field, ensuring job metadata survives context compaction.

feat(sdk): add list_async_subagent_jobs tool for recalling tracked jo…

41c915c

…bs from state

fix imports and make url optional in AsyncSubAgent to support asgi tr…

fdfe118

…ansport

clean up async subagent naming, annotations, and error handling

0e88377

use threads.get() instead of get_state() in check tool

0daef4b

key client cache on (url, headers) to share clients across agents

2ef82e8

fix tool return types

dea42e4

throw error for missing url in sync invocation

e69a7e9

Colin Francis (colifran) and others added 12 commits March 16, 2026 11:58

prompt tuning

f794378

lint fixes

212b96a

cr

5c4fc3a

cr

3f7a093

cr

376c926

.

9e29e20

clean up job id to just be thread id

49ba857

terminal statuses should include success and error

f28592b

code clean up and latency optimization for listing

b327219

linting issues

5d29217

add status filter to list jobs for better UX

12a2a28

fix linting issues

acc9437

Colin Francis (colifran) force-pushed the open-swe/598550c7-9d68-8519-3f24-5a92b98bea26 branch from d2652ec to acc9437 Compare March 16, 2026 18:58

Mason Daugherty (mdrxy) and others added 2 commits March 16, 2026 15:18

Merge branch 'main' into open-swe/598550c7-9d68-8519-3f24-5a92b98bea26

0f96027

cr

4d7a2dd

Mason Daugherty (mdrxy) changed the title ~~feat(sdk): add async subagents via remote langgraph servers~~ feat(sdk): add async subagent middleware for remote LangGraph servers Mar 16, 2026

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

Colin Francis (colifran) requested a review from Mason Daugherty (mdrxy) as a code owner March 16, 2026 19:35

cr

121d2bf

This comment was marked as resolved.

Sign in to view

ccurme (ccurme) approved these changes Mar 16, 2026

View reviewed changes

Mason Daugherty (mdrxy) merged commit 0c5d501 into main Mar 16, 2026
29 checks passed

Mason Daugherty (mdrxy) deleted the open-swe/598550c7-9d68-8519-3f24-5a92b98bea26 branch March 16, 2026 21:01

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

release(deepagents-cli): 0.0.34 #1924

Merged

Mason Daugherty (mdrxy) mentioned this pull request Mar 16, 2026

hotfix(cli): guard async_subagents kwarg for sdk 0.4.x compat #1931

Merged

Mason Daugherty (mdrxy) mentioned this pull request Mar 18, 2026

feat(cli): experimental background task runtime #1704

Closed

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

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

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(sdk): add async subagent middleware for remote LangGraph servers#1758
Mason Daugherty (mdrxy) merged 48 commits intomainfrom
open-swe/598550c7-9d68-8519-3f24-5a92b98bea26

Harrison Chase (hwchase17) commented Mar 10, 2026 •

edited by mdrxy

Loading

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Uh oh!

Colin Francis (colifran) Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Uh oh!

Colin Francis (colifran) Mar 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Uh oh!

Uh oh!

open-swe bot commented Mar 12, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

ccurme (ccurme) Mar 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants


		from deepagents_cli.agent import load_async_subagents

		async_subagents = load_async_subagents() or None

Conversation

Harrison Chase (hwchase17) commented Mar 10, 2026 • edited by mdrxy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Colin Francis (colifran) Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Colin Francis (colifran) Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

William FH (hinthornw) Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

open-swe bot commented Mar 12, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

ccurme (ccurme) Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Harrison Chase (hwchase17) commented Mar 10, 2026 •

edited by mdrxy

Loading