AsyncSubAgentMiddleware(
self,
*,
async_subagents: list[AsyncSubAgent],
system_prompt: str | None | Name | Type | Description |
|---|---|---|
async_subagents* | list[AsyncSubAgent] | |
system_prompt | str | None | Default: None |
| Name | Type |
|---|---|
| async_subagents | list[AsyncSubAgent] |
| system_prompt | str | None |
Middleware for async subagents running on remote Agent Protocol servers.
This middleware adds tools for launching, monitoring, and updating
background tasks on remote Agent Protocol servers. Unlike the synchronous
SubAgentMiddleware, async subagents return immediately with a task ID,
allowing the main agent to continue working while subagents execute.
Works with any Agent Protocol-compliant server — LangGraph Platform (managed) or self-hosted (e.g. a FastAPI server implementing the Agent Protocol spec).
Task IDs are persisted in the agent state under async_tasks so they
survive context compaction/offloading and can be accessed programmatically.
On an Agent Server, the agent is told when its async subagent tasks
finish, fail or wait for the user: before each model call and after
its final answer while it runs, and through a new run when a deep
agent subagent on this deployment ends while it's idle. This needs the async path (ainvoke,
which the Agent Server uses); with invoke, only the tools work. This
may change.
Example:
from deepagents.middleware.async_subagents import AsyncSubAgentMiddleware
middleware = AsyncSubAgentMiddleware(
async_subagents=[
{
"name": "researcher",
"description": "Research agent for deep analysis",
"url": "https://my-deployment.langsmith.dev",
"graph_id": "research_agent",
}
],
)List of async subagent specifications.
Each must include name, description, and graph_id. url is
optional — omit it to use ASGI transport for local servers.
Instructions appended to the main agent's system prompt about how to use the async subagent tools.
Omit hook inputs from traces by default; set a TracePolicy to override.
Record the task notification that started this run, if one did.
(async) Record the notification that started this run, then add status updates from this agent's tasks.
Pass through: checking tasks needs the async path, which the Agent Server uses.
(async) Add status updates from this agent's tasks before the model call.
Pass through: checking tasks needs the async path, which the Agent Server uses.
(async) After a final answer, check tasks once more; on a status update, give the model another turn.
Each extra turn needs a new status update, so the tasks themselves bound how many there are.
Update the system message to include async subagent instructions.
(async) Update the system message to include async subagent instructions.