Specification for an async subagent running on a remote Agent Protocol server.
Async subagents connect to any Agent Protocol-compliant server via the LangGraph SDK. They run as background tasks that the main agent can monitor and update.
Compatible with LangGraph Platform / LangSmith Deployment (managed) and self-hosted servers.
Authentication for LangGraph Platform / LangSmith Deployment is handled
automatically by the SDK via environment variables (LANGGRAPH_API_KEY,
LANGSMITH_API_KEY, or LANGCHAIN_API_KEY). For self-hosted servers,
pass custom auth via headers.
Omitting url uses in-process ASGI transport for a local server. This
transport is available only through an async parent-agent entrypoint,
such as ainvoke. The synchronous invoke path requires a URL for a
reachable Agent Protocol server.
When tracing is on, launches and updates of subagents on this deployment
(no url) send the parent's LangSmith trace headers, so a receiver can
nest the subagent's run under the parent's trace. This may change.
Each task's thread is created with
metadata={"subagent_name": ..., "parent_thread_id": ...}, so apps can
find a parent's subagent threads with threads.search, and a subagent's
graph factory can read them from its run's config["metadata"].
subagent_name is this spec's name. This may change.
Launches and updates on this deployment run with the parent's current run
context, not the child's prior context. Queued updates capture that context
when sent, not when they start. A remote subagent (url) receives no context.
| webhook | NotRequired[str] |
| update_strategy | NotRequired[Literal['interrupt', 'enqueue']] |
| notify_parent | NotRequired[bool] |
| mode | NotRequired[Literal['isolated', 'fork']] |
Unique identifier for the async subagent.
What this subagent does.
The main agent uses this to decide when to delegate.
The graph name or assistant ID on the remote server.
URL of the Agent Protocol server.
Defaults to the LangGraph SDK's default endpoint. Omit to use ASGI transport for local servers.
Additional headers to include in requests to the remote server.
URL the Agent Server calls whenever a run of this subagent finishes.
How update_async_task sends a follow-up while a run is active. Defaults to 'interrupt'.
interrupt: stop the current run and start the follow-up.enqueue: queue the follow-up behind the current run. The task is pending
until the follow-up starts. If the current run stops to ask its user for
approval or input, the follow-up still starts, and that request is dropped.update_strategy may change along with how queued follow-ups are tracked.
Whether this subagent may wake this agent when it finishes while this agent is idle. Defaults to True.
Set it to False when the application delivers results itself, for example
through webhook. This agent still sees the subagent's updates while it runs.
notify_parent may change along with how subagents wake their parent.
When using mode="fork", configure the remote agent to match the parent's model,
system prompt, tools, and prompt-processing middleware if you want prompt-cache
reuse. 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.
isolated (default): send only the delegated task description.fork: send a snapshot of the parent's conversation at launch, followed
by the task description, for background work.Different configurations are supported for context sharing, but you should not expect parent-to-child cache reuse with them.
mode="fork" is experimental and may change in a future release.