;
};
When a coordinator agent spawns specialist subagents (a researcher, an
analyst, a writer), you need to render the orchestrator's messages separately
from each subagent's streaming output. Set `filterSubagentMessages: true` in
`useStream` to cleanly split these two streams, then use
`getSubagentsByMessage` to attach each subagent's progress card to the
coordinator message that triggered it.
## Why filter subagent messages
Without filtering, every token produced by every subagent appears interleaved
in the coordinator's message stream, making it unreadable. With
`filterSubagentMessages: true`:
* `stream.messages` contains only the coordinator's messages
* Each subagent's content is accessible through `stream.subagents` and
`stream.getSubagentsByMessage`
* The UI stays clean: the coordinator's reasoning is separate from the
specialists' work
This separation lets you render the orchestrator's messages in one place and
attach each subagent's progress card exactly where it belongs: beneath the
coordinator message that spawned it.
## Setting up useStream
Always set `filterSubagentMessages: true`. This removes subagent tokens from
the main message stream so you can render the coordinator's messages and
subagent output independently.
Define a TypeScript interface matching your agent's state schema and pass it as a type parameter to `useStream` for type-safe access to state values. In the examples below, replace `typeof myAgent` with your interface name:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import type { BaseMessage } from "@langchain/core/messages";
interface AgentState {
messages: BaseMessage[];
}
```
```tsx React theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
const AGENT_URL = "http://localhost:2024";
export function DeepAgentChat() {
const stream = useStream({
apiUrl: AGENT_URL,
assistantId: "deep_agent_subagent_cards",
filterSubagentMessages: true,
});
return (
```
```ts Angular theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { Component } from "@angular/core";
import { useStream } from "@langchain/angular";
const AGENT_URL = "http://localhost:2024";
@Component({
selector: "app-deep-agent-chat",
template: `
@for (msg of stream.messages(); track msg.id) {
}
`,
})
export class DeepAgentChatComponent {
stream = useStream({
apiUrl: AGENT_URL,
assistantId: "deep_agent_subagent_cards",
filterSubagentMessages: true,
});
}
```
## Submitting with subgraph streaming
When submitting a message, enable subgraph streaming and set an appropriate
recursion limit. Deep agent workflows often involve multiple layers of nested
subagraphs, so a higher recursion limit prevents premature termination:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
stream.submit(
{ messages: [{ type: "human", content: text }] },
{ streamSubgraphs: true }
);
```
DeepAgents sets a default recursion limit of 10,000, which is sufficient for
most multi-expert setups. You can override this via `config.recursion_limit` if
needed.
## The SubagentStreamInterface
Each subagent exposes a `SubagentStreamInterface` with metadata about the
subagent's task, status, and timing:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
interface SubagentStreamInterface {
id: string;
status: "pending" | "running" | "complete" | "error";
messages: BaseMessage[];
result: string | undefined;
toolCall: {
id: string;
name: string;
args: {
description: string;
subagent_type: string;
[key: string]: unknown;
};
};
startedAt: number | undefined;
completedAt: number | undefined;
}
```
| Property | Description |
| ----------------------------- | ---------------------------------------------------------------------- |
| `id` | Unique identifier for this subagent instance |
| `status` | Lifecycle state: `pending` → `running` → `complete` or `error` |
| `messages` | The subagent's own message stream, updated in real time |
| `result` | The final output text, available only when `status` is `"complete"` |
| `toolCall` | The tool call that spawned this subagent, including task metadata |
| `toolCall.args.description` | The task description the coordinator assigned to this subagent |
| `toolCall.args.subagent_type` | The type or name of the specialist (e.g., `"researcher"`, `"analyst"`) |
| `startedAt` | Timestamp when the subagent began executing |
| `completedAt` | Timestamp when the subagent finished |
## Linking subagents to messages
The `getSubagentsByMessage` method returns the subagents spawned by a specific
AI message. This lets you render subagent cards directly beneath the
coordinator message that triggered them:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const turnSubagents = stream.getSubagentsByMessage(msg.id);
```
This returns an array of `SubagentStreamInterface` objects. If the message
didn't spawn any subagents, it returns an empty array.
## Building the SubagentCard
Each subagent card shows the specialist's name, task description, streaming
content or final result, and timing information:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { AIMessage } from "@langchain/core/messages";
function SubagentCard({
subagent,
}: {
subagent: SubagentStreamInterface;
}) {
const [expanded, setExpanded] = useState(true);
const title =
subagent.toolCall?.args?.subagent_type ?? `Agent ${subagent.id}`;
const description = subagent.toolCall?.args?.description ?? "";
const lastAIMessage = subagent.messages
.filter(AIMessage.isInstance)
.at(-1);
const displayContent =
subagent.status === "complete"
? subagent.result
: typeof lastAIMessage?.content === "string"
? lastAIMessage.content
: "";
const elapsed = getElapsedTime(subagent.startedAt, subagent.completedAt);
return (
);
}
function getElapsedTime(
startedAt: number | undefined,
completedAt: number | undefined
): string | null {
if (!startedAt) return null;
const end = completedAt ?? Date.now();
const seconds = Math.round((end - startedAt) / 1000);
if (seconds < 60) return `${seconds}s`;
return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
}
```
## Status icons and badges
Consistent visual indicators help users parse subagent status at a glance:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function StatusIcon({ status }: { status: SubagentStreamInterface["status"] }) {
switch (status) {
case "pending":
return ○;
case "running":
return ◉;
case "complete":
return ✓;
case "error":
return ✕;
}
}
function StatusBadge({ status }: { status: SubagentStreamInterface["status"] }) {
const styles = {
pending: "bg-gray-100 text-gray-600",
running: "bg-blue-100 text-blue-700",
complete: "bg-green-100 text-green-700",
error: "bg-red-100 text-red-700",
};
return (
{status}
);
}
```
## Progress tracking
Show a progress bar and counter so users know how many subagents have finished:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function SubagentProgress({
subagents,
}: {
subagents: SubagentStreamInterface[];
}) {
const completed = subagents.filter((s) => s.status === "complete").length;
const total = subagents.length;
const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
return (
Subagent progress
{completed}/{total} complete
);
}
```
## Rendering messages with subagent cards
The key layout pattern is to render each coordinator message, and if that message
spawned subagents, render their cards immediately below it:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function MessageWithSubagents({
message,
subagents,
}: {
message: BaseMessage;
subagents: SubagentStreamInterface[];
}) {
if (message.type === "human") {
return ;
}
return (
{message.content && (
{message.content}
)}
{subagents.length > 0 && (
{subagents.map((subagent) => (
))}
)}
);
}
```
## Synthesis indicator
After all subagents complete, the coordinator takes time to synthesize their
results into a final response. Show a clear indicator during this phase:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function SynthesisIndicator({
subagents,
isLoading,
}: {
subagents: SubagentStreamInterface[];
isLoading: boolean;
}) {
const allComplete =
subagents.length > 0 &&
subagents.every((s) => s.status === "complete" || s.status === "error");
if (!allComplete || !isLoading) return null;
return (
);
}
```
The synthesis phase can take several seconds for complex multi-expert
workflows. A clear "Synthesizing results..." indicator prevents users from
thinking the agent has stalled.
## Debug unfiltered output
During development, you can temporarily set `filterSubagentMessages: false` to
see the raw, interleaved output from all subagents in the main message stream.
This is useful for verifying that subagent tokens are flowing correctly, but
should not be used in production UIs.
## Use cases
Deep agent subagent cards are the right choice when your agent workflow
involves:
* **Deep research** where a coordinator dispatches researchers to investigate
different facets of a question, then synthesizes their findings
* **Multi-expert analysis** such as domain specialists (legal, financial, technical)
each contribute their perspective
* **Complex task decomposition** where a planner breaks a large task into subtasks
and assigns each to a specialist worker
* **Code review pipelines** where separate agents handle security review, style
checking, performance analysis, and documentation review
## Accessing the full subagents map
Beyond per-message lookup, you can access all subagents at once through
`stream.subagents`:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const allSubagents = [...stream.subagents.values()];
const running = allSubagents.filter((s) => s.status === "running");
const completed = allSubagents.filter((s) => s.status === "complete");
const errors = allSubagents.filter((s) => s.status === "error");
```
This is useful for building global progress indicators or dashboards that
summarize all subagent activity regardless of which coordinator message spawned
them.
## Best practices
* **Always set `filterSubagentMessages: true`**. Unfiltered streams produce an
unreadable interleaving of coordinator and subagent tokens.
* **Show task descriptions**. The `toolCall.args.description` field tells users
exactly what each subagent was asked to do. Always display this prominently.
* **Use collapsible cards**. In workflows with 5+ subagents, auto-collapse
completed cards so users can focus on active work.
* **Display timing data**. Showing how long each subagent took helps users
understand performance characteristics and identify bottlenecks.
* **Set an appropriate recursion limit**. Deep agent workflows with nested
subgraphs need higher limits than the default 25. Start with 100.
* **Handle errors per subagent**. One subagent failing shouldn't crash the
entire UI. Show the error in that subagent's card while others continue
running.
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/frontend/subagent-streaming.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).