;
};
LangGraph agents aren't black boxes. Every graph is composed of **named nodes**
that execute in sequence or in parallel: classify, research, analyze,
synthesize. Graph execution cards make this pipeline visible by rendering a card
for each node, showing its status, streaming its content in real time, and
tracking completion across the entire workflow. Users see exactly what the agent
is doing, which step it's on, and what each step produced.
## How graph nodes map to UI cards
A LangGraph graph defines a series of nodes, each responsible for a specific
task. For example, a research pipeline might have:
1. **Classify**: categorize the user's query
2. **Research**: gather relevant information
3. **Analyze**: draw conclusions from the research
4. **Synthesize**: produce a final, polished response
Each node writes its output to a specific key in the graph's state. By mapping
these node names and state keys to UI components, you can create a visual
representation of the entire pipeline.
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const PIPELINE_NODES = [
{ name: "classify", stateKey: "classification", label: "Classify" },
{ name: "do_research", stateKey: "research", label: "Research" },
{ name: "analyze", stateKey: "analysis", label: "Analyze" },
{ name: "synthesize", stateKey: "synthesis", label: "Synthesize" },
];
const PIPELINE_NODE_NAMES = new Set(PIPELINE_NODES.map((n) => n.name));
```
## Setting up useStream
Wire up `useStream` as usual. The key properties you'll use are `messages`
(for streaming content routing), `values` (for completed node outputs), and
`getMessagesMetadata` (for identifying which node produced each token).
Import your agent and pass `typeof myAgent` as a type parameter to `useStream` for type-safe access to state values:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import type { myAgent } from "./agent";
```
```tsx React theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
const AGENT_URL = "http://localhost:2024";
export function PipelineChat() {
const stream = useStream({
apiUrl: AGENT_URL,
assistantId: "graph_execution_cards",
});
return (
`,
})
export class PipelineChatComponent {
PIPELINE_NODES = PIPELINE_NODES;
stream = useStream({
apiUrl: AGENT_URL,
assistantId: "graph_execution_cards",
});
}
```
## Routing streaming tokens to nodes
As the agent streams, each message is annotated with metadata that identifies
which graph node produced it. Use `getMessagesMetadata` to extract the
`langgraph_node` value and route tokens to the correct card:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function getStreamingContent(
messages: BaseMessage[],
getMetadata: (msg: BaseMessage) => MessageMetadata | undefined
): Record {
const content: Record = {};
for (const message of messages) {
if (message.type !== "ai") continue;
const metadata = getMetadata(message);
const node = metadata?.streamMetadata?.langgraph_node;
if (node && PIPELINE_NODE_NAMES.has(node)) {
content[node] = typeof message.content === "string"
? message.content
: "";
}
}
return content;
}
```
This gives you a map from node name to its current streaming content. As tokens
arrive, the corresponding card updates in real time.
The `streamMetadata.langgraph_node` field is set automatically by LangGraph.
You don't need any special configuration on the backend. Just stream messages
as usual, and the metadata is included.
## Determining node status
Each node can be in one of four states: not started, streaming, complete, or
idle. You derive the status from two sources: the streaming content map (for
active nodes) and `stream.values` (for completed nodes):
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type NodeStatus = "idle" | "streaming" | "complete";
function getNodeStatus(
node: { name: string; stateKey: string },
streamingContent: Record,
values: Record
): NodeStatus {
if (values?.[node.stateKey]) return "complete";
if (streamingContent[node.name]) return "streaming";
return "idle";
}
```
## Building the pipeline progress bar
A horizontal progress bar at the top gives users a bird's-eye view of the
entire pipeline. Each step is a labeled segment that fills in as nodes complete:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function PipelineProgress({
nodes,
values,
streamingContent,
}: {
nodes: typeof PIPELINE_NODES;
values: Record;
streamingContent: Record;
}) {
return (
);
}
```
## Building collapsible NodeCard components
Each node gets its own card that shows the status badge, content (streaming or
final), and a collapsible body for long outputs:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function NodeCard({
node,
status,
streamingContent,
completedContent,
}: {
node: { name: string; stateKey: string; label: string };
status: NodeStatus;
streamingContent: string | undefined;
completedContent: unknown;
}) {
const [collapsed, setCollapsed] = useState(false);
const displayContent =
status === "complete"
? formatContent(completedContent)
: streamingContent ?? "";
const statusBadge = {
idle: { text: "Waiting", className: "bg-gray-100 text-gray-600" },
streaming: {
text: "Running",
className: "bg-blue-100 text-blue-700 animate-pulse",
},
complete: { text: "Done", className: "bg-green-100 text-green-700" },
};
const badge = statusBadge[status];
return (
{!collapsed && displayContent && (
{displayContent}
{status === "streaming" && (
)}
)}
);
}
function formatContent(value: unknown): string {
if (typeof value === "string") return value;
if (value == null) return "";
return JSON.stringify(value, null, 2);
}
```
## Streaming vs. completed content
There are two sources of content for each node, and picking the right one
matters for a smooth UX:
| Source | When to use |
| ------------------------------ | ------------------------------------------------------------------------- |
| `streamingContent[node.name]` | While the node is actively streaming, this contains tokens as they arrive |
| `stream.values[node.stateKey]` | After the node completes, this contains the final, committed output |
The pattern is: show streaming content for live updates, fall back to the
committed state value once the node is done.
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
for (const node of PIPELINE_NODES) {
const status = getNodeStatus(node, streamingContent, stream.values);
const content =
status === "streaming"
? streamingContent[node.name]
: stream.values?.[node.stateKey];
}
```
Streaming content may include partial tokens or markdown that hasn't been
fully formed yet. If you render markdown, make sure your renderer handles
incomplete syntax gracefully (e.g., an unclosed bold marker `**`).
## Putting it all together
Here's the full card list that combines routing, status detection, and card
rendering:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function NodeCardList({
nodes,
messages,
values,
getMetadata,
}: {
nodes: typeof PIPELINE_NODES;
messages: BaseMessage[];
values: Record;
getMetadata: (msg: BaseMessage) => MessageMetadata | undefined;
}) {
const streamingContent = getStreamingContent(messages, getMetadata);
return (
);
}
```
## Use cases
Graph execution cards work well for any multi-step pipeline where visibility
matters:
* **Research pipelines**: classify → gather sources → analyze → synthesize a
report
* **Content generation**: outline → draft → fact-check → edit → publish
* **Data processing**: ingest → validate → transform → aggregate → export
* **Code generation**: understand requirements → plan architecture → write
code → review → test
* **Decision workflows**: gather context → evaluate options → score
alternatives → recommend
## Handling dynamic pipelines
Not all graphs have a fixed set of nodes. Some pipelines add or skip nodes
based on the input. Handle this by checking which state keys actually have
values:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const activeNodes = PIPELINE_NODES.filter(
(node) =>
streamingContent[node.name] ||
values?.[node.stateKey] ||
node.name === currentNode
);
```
This ensures your UI only shows cards for nodes that are relevant to the
current execution, avoiding empty placeholder cards.
If your graph has conditional branching (e.g., skip "Research" for simple
factual queries), the skipped nodes will never appear in the streaming content
or state values. Your pipeline progress bar should reflect this by dimming or
hiding skipped steps.
## Best practices
* **Define nodes declaratively**. Keep your `PIPELINE_NODES` array as a single
source of truth that maps node names, state keys, and display labels.
* **Prefer streaming content for active nodes**. It gives users immediate
feedback. Only fall back to committed state values after the node completes.
* **Auto-collapse completed nodes**. In long pipelines, auto-collapse finished
cards so users can focus on the currently active step.
* **Show estimated timing**. If you have historical data on how long each node
takes, display a time estimate to set user expectations.
* **Add a global progress indicator**. Complement per-node cards with an
overall progress bar (e.g., "Step 2 of 4") at the top of the pipeline view.
* **Handle errors per node**. If a node fails, show the error in its card
without collapsing the entire pipeline. Other nodes may still complete
successfully.
***
[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/langgraph/frontend/graph-execution.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).