useStream: Streaming Agent State to React
The useStream React hook connects your UI to a LangGraph agent with real-time streaming — messages, tool progress, interrupts, branching, subagent output, and reconnection. Works with any LangGraph backend via apiUrl or custom transport.
Quick Reference
- →Import from @langchain/langgraph-sdk/react — also available for Vue, Svelte, and Angular
- →stream.isLoading is the correct loading indicator — no 'status' enum or 'isRunning' property exists
- →Stream modes control what you receive: 'messages' for LLM tokens, 'values' for full state, 'tools' for tool lifecycle, 'custom' for user-defined data
- →Resume an interrupt with stream.submit(null, { command: { resume: value } }) — no resume() function exists
- →Enable branching with fetchStateHistory: true — then use setBranch(), getMessagesMetadata(), and checkpoint-based submit to fork conversations
- →stream.stop() disconnects the client but keeps the agent running server-side — reconnect with stream.joinStream(runId)
- →stream.toolProgress (requires streamMode 'tools') tracks tool lifecycle: starting, running, completed, error with intermediate data
- →Type your hook as useStream<typeof myAgent>({...}) for compile-time safety on state shape and interrupt types
Should You Use useStream?
useStream is purpose-built for one situation: a React UI that talks to a LangGraph agent. If your backend is not a LangGraph graph, useStream will not work — it requires the LangGraph streaming protocol (SSE + checkpoint API). Before reaching for it, verify you actually need it.
| Scenario | Right Tool | Why |
|---|---|---|
| LangGraph agent backend | useStream | Built for this — handles checkpoints, interrupts, branching |
| Generic LLM API (OpenAI, Anthropic direct) | Vercel AI SDK useChat | useStream speaks LangGraph protocol only |
| Server-side rendering (Next.js RSC) | Server action + streaming | useStream is a client-side hook; no browser = no hook |
| Simple one-shot completion (no streaming) | fetch() + await | useStream adds complexity you don't need |
| Vue, Svelte, or Angular | @langchain/vue, @langchain/svelte, @langchain/angular | Same API surface, framework-specific package |
useStream will silently fail or return empty data if your backend does not implement the LangGraph streaming protocol. Use the Vercel AI SDK's useChat for generic OpenAI-compatible APIs.
useStream wins when you need any combination of: real-time LLM token streaming, per-tool progress tracking, human-in-the-loop interrupts, conversation branching, or multi-agent subgraph streaming — all with automatic checkpoint management and reconnection.