async: true. See Async subagents in Managed Deep Agents.
Async subagents run on any server that implements the Agent Protocol, such as LangSmith Agent Server or a self-hosted Agent Protocol server. Each subagent runs independently of the supervisor. The supervisor starts, checks, updates, and cancels it through the SDK. Notifications and webhooks require Agent Server.
Compare sync and async subagents
Configure async subagents
Define async subagents as a list ofAsyncSubAgent specs, each pointing to an Agent Protocol server:
For LangGraph-based deployments, register all graphs in the same
langgraph.json for co-deployed setups:
Use the async subagent tools
TheAsyncSubAgentMiddleware which is included in the Deep Agents stack when async subagents are configured, gives the supervisor five tools:
The supervisor’s LLM calls these tools like any other tool. The middleware handles thread creation, run management, and state persistence automatically.
Understand the lifecycle
A typical interaction follows this sequence:On Agent Server, the supervisor does not need to check on the task: when the subagent finishes, the task notifies the supervisor.
- Launch creates a new thread on the server and starts a run with input determined by the launch mode. Isolated mode sends only the task description. Fork mode also sends the parent’s effective conversation history.
start_async_taskreturns the thread ID as the task ID. - Check fetches the task’s current status, plus its result, error, or what it is asking the user.
- Update creates a new run on the same thread. By default it interrupts the previous run, and the subagent restarts with the full conversation history plus the new instructions. The task ID stays the same.
- Cancel calls
runs.cancel()on the server and marks the task as"cancelled". - List iterates over all tracked tasks. For non-terminal tasks, it fetches live status from the server in parallel. For terminal statuses (
success,error,timeout,cancelled,interrupted), it uses the cached status.
updateStrategy: "enqueue". Update then queues the new run behind the current one, and the task is pending until it starts. Cancelling the task also cancels earlier runs that are still active.
If the current run pauses for input or approval before the follow-up starts, the follow-up still starts and that request is dropped.
updateStrategy requires deepagents>=1.16.0. It is in beta; APIs and behavior may change between releases.waiting. Updating a waiting task drops its pending request, and cancelling one only marks it as "cancelled", since it has no active run. See Handle subagents waiting for input.
On Agent Server, subagents notify the supervisor when they finish, fail, or need input. While the supervisor is busy, it receives those notifications before its next model call. A subagent that finishes or fails wakes an idle supervisor with a new run, if both are on the same deployment. Only subagents that are deep agents wake an idle supervisor. A subagent waiting for input does not wake the supervisor. The supervisor receives that notification on its next run.
Task notifications require
deepagents>=1.16.0, and notification metadata requires deepagents>=1.16.2. They are in beta; APIs and behavior may change between releases.HumanMessage. Notifications can include images and other multimodal media. Each notification carries notification metadata: its source is "async_subagent", and its data is a TaskEvent (task_id, agent_name, status, run_id). Read it with getNotificationMetadata to show notifications differently from user messages:
Refusal results from async subagents require
deepagents>=1.16.4.Deliver results through your app
webhook and notifyParent require deepagents>=1.16.0. notifyParent is in beta; APIs and behavior may change between releases.webhook to have the Agent Server call your app whenever a run of the subagent finishes. The call includes the run’s thread ID, run ID, status, and metadata, including parent_thread_id and subagent_name. To deliver results through your app instead of waking the supervisor, also turn off parent notifications. The supervisor still receives notifications while it is running.
Handle subagents waiting for input
The
waiting status requires deepagents>=1.16.0. It is in beta; APIs and behavior may change between releases.interrupt() or human-in-the-loop, check_async_task and list_async_tasks report it as waiting. Only check_async_task also returns its pending interrupts. The supervisor cannot answer or approve on the user’s behalf. The request is for the user.
Your app answers it on the subagent’s own thread. The task ID is the subagent’s thread ID:
update_async_task.
Understand state management
Task metadata is stored in a dedicated state channel (asyncTasks) on the supervisor’s graph, separate from the message history. This is critical because deep agents compact their message history when the context window fills up. If task IDs were only in tool messages, they would be lost during compaction. The dedicated channel ensures the supervisor can always recall its tasks through list_async_tasks, even after multiple rounds of summarization.
Each tracked task records the task ID, agent name, thread ID, run ID, status, and timestamps (createdAt, checkedAt, updatedAt).
Find a supervisor’s subagent threads
Thread tagging requires
deepagents>=1.16.0.start_async_task creates each subagent thread with metadata: { parent_thread_id }, the supervisor’s thread ID. Use it to find a supervisor’s subagent threads, or to read the supervisor’s thread in a subagent’s graph factory:
Choose a transport
Same-deployment (omit url)
When a subagent spec omits the url field, the LangGraph SDK talks to the Agent Server that is running this graph, using the address that server provides. Elsewhere, the SDK defaults to http://localhost:8123. For LangGraph-based deployments, register both graphs in the same langgraph.json.
Deployed Agent Servers provide this address from version 0.18.0 (langgraph dev already does). On earlier versions, set url to the deployment URL.
HTTP transport (remote)
Add aurl field to switch to HTTP transport, where SDK calls go over the network to a remote Agent Protocol server:
LANGSMITH_API_KEY (or LANGGRAPH_API_KEY) from environment variables. Self-hosted Agent Protocol servers may use a different authentication mechanism.
Use HTTP transport when subagents need independent scaling, different resource profiles, or are maintained by a different team.
Choose a launch mode
Themode field on each AsyncSubAgent spec controls what conversation context the subagent receives when a task starts.
"isolated" is the right choice for most tasks. Use "fork" when the subagent needs established context. For example, use "fork" for a background drafting agent that should write in the style and voice already set up in the conversation.
Fork mode
Setmode: "fork" on any AsyncSubAgent spec:
start_async_task sends a snapshot of the parent’s effective conversation history, followed by the task description. If the parent has compacted its history, the snapshot includes that compacted context, not every original message. Later messages from the parent are not forwarded to the child.
The subagent starts on a new server thread. Fork mode sends conversation messages as run input; it does not copy the parent’s checkpoint history or all parent state. Metadata can associate the new thread with its supervisor, but that association does not itself transfer conversation context.
Prompt-cache reuse. To get cache hits on the forked conversation prefix, configure the remote agent with the same model, system prompt, tools, and prompt-processing middleware as the parent. Fork mode copies conversation history; it does not synchronize those settings. Matching configuration is necessary but not sufficient: the rendered prefix must match, and cache hits depend on the provider.
Offloaded media. If the parent offloads media with offloadBinaryContent, fork mode sends references to it rather than the media itself. The subagent must be a deep agent that shares the parent’s backend to see the media; other deep agents get a note that it’s unavailable, and other graphs can’t use these messages.
Choose a deployment topology
Single deployment
A single deployment means all agents are co-deployed on the same Agent Server. Omiturl so each graph reaches the others through that server. For LangGraph-based deployments, register all graphs in one langgraph.json. This is the recommended starting point — one server to manage.
Split deployment
Supervisor on one server, subagents on another via HTTP transport. Use when subagents need different compute profiles or independent scaling.Hybrid
In a hybrid deployment, some subagents omiturl (same Agent Server), others set url for a remote server:
Best practices
Size the worker pool for local development
When running locally withlanggraph dev, increase the worker pool to accommodate concurrent subagent runs. Each active run occupies a worker slot. A supervisor with 3 concurrent subagent tasks requires 4 slots (1 supervisor + 3 subagents). Under-provisioning causes launches to queue.
Write clear subagent descriptions
The supervisor uses descriptions to decide which subagent to launch. Be specific and action-oriented:Trace subagent runs
When using LangGraph-based deployments, every async subagent run is a standard LangGraph run, fully visible in LangSmith. The supervisor’s trace shows itsstart_async_task, check_async_task, update_async_task, cancel_async_task, and list_async_tasks calls. By default, each subagent run appears as a separate trace. Use the thread ID (task ID) to match a subagent’s traces to the supervisor’s.
Subagents on the same deployment also receive the supervisor’s trace headers. To show a subagent’s runs nested under the supervisor’s trace, have the subagent’s graph adopt those trace headers. See distributed tracing on Agent Server.
Troubleshooting
Supervisor polls immediately after launch
Problem: The supervisor callscheck_async_task in a loop right after launching, turning async execution into blocking.
Solution: The supervisor does not need to check. On Agent Server, the subagent notifies the supervisor when the task finishes, fails, or needs input. The start_async_task tool description already tells the model not to check status right after launching. If polling persists, reinforce this in your supervisor’s system prompt:
Supervisor reports stale status
Problem: The supervisor reports a task status from earlier in the conversation instead of checking the task again. Solution: Thecheck_async_task and list_async_tasks tool descriptions tell the model that statuses in conversation history are stale. If this still occurs, add instructions to call check_async_task or list_async_tasks before reporting a task’s status. With notifications on, the supervisor learns about each status change without checking.
Task ID lookup failures
Problem: The supervisor truncates or reformats the task ID, causingcheck_async_task or cancel_async_task to fail.
Solution: The task ID argument of each tool tells the model to pass the full task ID. If truncation persists, the cause is typically model-specific. Try a different model, or add “always show the full task_id, never truncate or abbreviate it” to your system prompt.
Subagent launches queue instead of running
Problem: Launching a subagent hangs or takes a long time to start. Solution: The worker pool is likely exhausted. Increase the pool size with--n-jobs-per-worker. See Size the worker pool.
Reference implementation
The async-deep-agents repository contains working examples in both Python and TypeScript that deploy to LangSmith Agent Server. It demonstrates a supervisor with researcher and coder subagents running as background tasks.Connect these docs to your agent of choice via MCP for real-time answers.

