Async subagents

Launch background subagents that run concurrently while the supervisor continues interacting with the user

Async subagents let a supervisor agent launch background tasks that return immediately, so the supervisor can continue interacting with the user while subagents work concurrently. The supervisor can check progress, send follow-up instructions, or cancel tasks at any point.

This builds on subagents, which run synchronously and block the supervisor until completion. Use async subagents when tasks are long-running, parallelizable, or need mid-flight steering.

Async subagents are a preview feature available in deepagents 1.9.0. Preview features are under active development and APIs may change.

Async subagents communicate with any server that implements the Agent Protocol. You can use LangSmith Deployments, or self-host any Agent Protocol-compatible server. Each subagent runs independently of the supervisor, which controls them through the SDK to launch, check, update, and cancel.

When to use async subagents

Dimension	Sync subagents	Async subagents
Execution model	Supervisor blocks until subagent completes	Returns job ID immediately; supervisor continues
Concurrency	Parallel but blocking	Parallel and non-blocking
Mid-task updates	Not possible	Send follow-up instructions via update_async_task
Cancellation	Not possible	Cancel running tasks via cancel_async_task
Statefulness	Stateless — no persistent state between invocations	Stateful — maintains state on its own thread across interactions
Best for	Tasks where the agent should wait for results before continuing	Long-running, complex tasks managed interactively in a chat

Configure async subagents

Define async subagents as a list of AsyncSubAgent specs, each pointing to an Agent Protocol server:

Google

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "google-genai:gemini-3.5-flash",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  subagents: [...asyncSubagents],
});

import { createDeepAgent, type AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent for information gathering and synthesis",
    graphId: "researcher",
    // No url → ASGI transport (co-deployed in the same deployment)
  },
  {
    name: "coder",
    description: "Coding agent for code generation and review",
    graphId: "coder",
    // url: "https://coder-deployment.langsmith.dev"  // Optional: HTTP transport for remote
  },
];

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  subagents: [...asyncSubagents],
});

Field	Type	Description
name	string	Required. Unique identifier. The supervisor uses this when launching tasks.
description	string	Required. What this subagent does. The supervisor uses this to decide which agent to delegate to.
graphId	string	Required. The graph ID (or assistant ID) on the Agent Protocol server. For LangGraph-based deployments, this must match a graph registered in langgraph.json.
url	string	Optional. When omitted, uses ASGI transport (in-process). When set, uses HTTP transport to a remote Agent Protocol server.
headers	Record<string, string>	Optional. Additional headers for requests to the remote server. Use for custom authentication with self-hosted Agent Protocol servers.

For LangGraph-based deployments, register all graphs in the same langgraph.json for co-deployed setups:

{
  "graphs": {
    "supervisor": "./src/supervisor.py:graph",
    "researcher": "./src/researcher.py:graph",
    "coder": "./src/coder.py:graph"
  }
}

Use the async subagent tools

The AsyncSubAgentMiddleware which is included in the default middleware stack when async subagents are configured, gives the supervisor five tools:

Tool	Purpose	Returns
start_async_task	Start a new background task	Task ID (immediately)
check_async_task	Get current status and result of a task	Status + result (if complete)
update_async_task	Send new instructions to a running task	Confirmation + updated status
cancel_async_task	Stop a running task	Confirmation
list_async_tasks	List all tracked tasks with live statuses	Summary of all tasks

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:

• Launch creates a new thread on the server, starts a run with the task description as input, and returns the thread ID as the task ID. The supervisor reports this ID to the user and does not poll for completion.
• Check fetches the current run status. If the run succeeded, it retrieves the thread state to extract the subagent’s final output. If still running, it reports that to the user.
• Update creates a new run on the same thread with an interrupt multitask strategy. The previous run is interrupted, 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. Terminal statuses (success, error, cancelled) are returned from cache.

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).

Choose a transport

ASGI transport (co-deployed)

When a subagent spec omits the url field, the LangGraph SDK uses ASGI transport — SDK calls are routed through in-process function calls rather than HTTP. For LangGraph-based deployments, this requires both graphs to be registered in the same langgraph.json.

ASGI transport eliminates network latency and requires no additional auth configuration. The subagent still runs as a separate thread with its own state. This is the recommended default.

HTTP transport (remote)

Add a url field to switch to HTTP transport, where SDK calls go over the network to a remote Agent Protocol server:

{
  name: "researcher",
  description: "Research agent",
  graphId: "researcher",
  url: "https://my-research-deployment.langsmith.dev",
}

For LangGraph deployments, authentication is handled by the LangGraph SDK using 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 deployment topology

Single deployment

A single deployment means all agents are co-deployed on the same server using ASGI transport. For LangGraph-based deployments, register all graphs in one langgraph.json. This is the recommended starting point — one server to manage, zero network latency between agents.

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 are co-deployed via ASGI, others remote via HTTP:

import type { AsyncSubAgent } from "deepagents";

const asyncSubagents: AsyncSubAgent[] = [
  {
    name: "researcher",
    description: "Research agent",
    graphId: "researcher",
    // No url → ASGI (co-deployed)
  },
  {
    name: "coder",
    description: "Coding agent",
    graphId: "coder",
    url: "https://coder-deployment.langsmith.dev",
    // url present → HTTP (remote)
  },
];

Best practices

Size the worker pool for local development

When running locally with langgraph 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.

langgraph dev --n-jobs-per-worker 10

Write clear subagent descriptions

The supervisor uses descriptions to decide which subagent to launch. Be specific and action-oriented:

Good

// Good
{
  name: "researcher",
  description: "Conducts in-depth research using web search. Use for questions requiring multiple searches and synthesis.",
  graphId: "researcher",
}

// Bad
{
  name: "helper",
  description: "helps with stuff",
  graphId: "helper",
}

Trace with thread IDs

When using LangGraph-based deployments, every async subagent run is a standard LangGraph run, fully visible in LangSmith. The supervisor’s trace shows tool calls for launch, check, update, cancel, and list. Each subagent run appears as a separate trace, linked by thread ID. Use the thread ID (task ID) to correlate supervisor orchestration traces with subagent execution traces.

Troubleshooting

Supervisor polls immediately after launch

Problem: The supervisor calls check in a loop right after launching, turning async execution into blocking.

Solution: The middleware injects system prompt rules to prevent this. If polling persists, reinforce the behavior in your supervisor’s system prompt:

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "google_genai:gemini-3.5-flash",
  systemPrompt: `...your instructions...

    After launching an async subagent, ALWAYS return control to the user.
    Never call check_async_task immediately after launch.`,
  subagents: [...asyncSubagents],
});

Supervisor reports stale status

Problem: The supervisor references a task status from earlier in conversation history instead of making a fresh check call.

Solution: The middleware prompt instructs the model that “task statuses in conversation history are always stale.” If this still occurs, add explicit instructions to always call check or list before reporting status.

Task ID lookup failures

Problem: The supervisor truncates or reformats the task ID, causing check or cancel to fail.

Solution: The middleware prompt instructs the model to always use the full task ID. If truncation persists, this is typically a model-specific issue — 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 Deployments. It demonstrates a supervisor with researcher and coder subagents running as background tasks.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.