;
};
Async iterator tools yield progress updates as they execute, letting you show real-time feedback for long-running operations. Instead of a blank loading spinner while the agent searches, scrapes, or processes data, users see a live progress bar with status details.
## What are async iterator tools?
Standard tools execute and return a single result. Async iterator tools are different — they **yield intermediate progress updates** during execution before producing a final result. This is implemented using async generators on the server side.
Consider a web search tool that crawls multiple pages:
1. Start searching → yield `{ status: "starting", completed: 0, total: 5 }`
2. First page crawled → yield `{ status: "searching", completed: 1, total: 5, latest: "example.com" }`
3. Second page crawled → yield `{ status: "searching", completed: 2, total: 5, latest: "docs.org" }`
4. ...and so on until complete
Each progress update streams to the client in real time via the `toolProgress` property on `useStream`.
## Use cases
* **Web scraping** — crawling multiple URLs with per-page progress
* **File processing** — batch transformations on uploaded documents
* **Database queries** — scanning large datasets with row-count progress
* **API aggregation** — calling multiple third-party APIs sequentially
* **Code analysis** — linting or testing across multiple files
* **Data pipelines** — ETL steps with stage-level progress
## The `toolProgress` property
The `useStream` hook exposes `toolProgress`, an array of `ToolProgress` objects representing active and recently completed tool executions:
```ts theme={null}
interface ToolProgress {
name: string;
toolCallId: string;
state: string;
data: {
total?: number;
completed?: number;
latest?: string;
status?: string;
[key: string]: unknown;
};
}
```
| Field | Type | Description |
| ---------------- | -------- | ------------------------------------------------------------------------- |
| `name` | `string` | The name of the tool being executed |
| `toolCallId` | `string` | Unique identifier linking this progress to a specific tool call |
| `state` | `string` | Current state of the tool (e.g., `"starting"`, `"running"`, `"complete"`) |
| `data` | `object` | Custom progress payload with flexible fields |
| `data.total` | `number` | Total number of items to process |
| `data.completed` | `number` | Number of items processed so far |
| `data.latest` | `string` | Description of the most recently processed item |
| `data.status` | `string` | Human-readable status label |
## Accessing `toolProgress` from `useStream`
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={null}
import type { BaseMessage } from "@langchain/core/messages";
interface AgentState {
messages: BaseMessage[];
}
```
```tsx React theme={null}
import { useStream } from "@langchain/react";
function Chat() {
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "async_tools",
});
const toolProgress = stream.toolProgress ?? [];
const activeProgress = toolProgress.filter((tp) => tp.state !== "complete");
return (
);
}
```
### Status mapping
Map the tool's state to user-friendly labels and colors:
```ts theme={null}
function getStatusLabel(state: string): string {
switch (state) {
case "starting":
return "Pending";
case "running":
case "searching":
return "Running";
case "complete":
return "Complete";
default:
return state;
}
}
function getStatusColor(state: string): string {
switch (state) {
case "starting":
return "status-pending";
case "running":
case "searching":
return "status-running";
case "complete":
return "status-complete";
default:
return "status-unknown";
}
}
```
### Styling the progress card
```css theme={null}
.tool-progress-card {
background: white;
border: 1px solid #e5e7eb;
border-radius: 8px;
padding: 16px;
margin: 8px 0;
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
}
.progress-header {
display: flex;
align-items: center;
gap: 8px;
margin-bottom: 12px;
}
.tool-name {
font-weight: 500;
color: #374151;
}
.status-badge {
font-size: 0.75em;
font-weight: 600;
padding: 2px 8px;
border-radius: 12px;
text-transform: uppercase;
letter-spacing: 0.05em;
}
.status-pending {
background: #fef3c7;
color: #92400e;
}
.status-running {
background: #dbeafe;
color: #1e40af;
}
.status-complete {
background: #d1fae5;
color: #065f46;
}
.progress-bar-container {
width: 100%;
height: 6px;
background: #f3f4f6;
border-radius: 3px;
overflow: hidden;
margin-bottom: 8px;
}
.progress-bar {
height: 100%;
background: linear-gradient(90deg, #6366f1, #8b5cf6);
border-radius: 3px;
transition: width 0.3s ease;
}
.progress-details {
display: flex;
align-items: center;
gap: 12px;
font-size: 0.85em;
color: #6b7280;
}
.progress-pct {
font-weight: 600;
color: #374151;
}
.progress-latest {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
max-width: 200px;
}
```
## Calculating progress percentage
The percentage calculation is straightforward but needs guard checks for missing data:
```ts theme={null}
const pct = tp.data?.total
? Math.round((tp.data.completed / tp.data.total) * 100)
: 0;
```
Some tools may not report `total` upfront (e.g., when the number of items isn't known until partway through execution). In these cases, consider showing an indeterminate progress indicator instead of a bar at 0%.
### Indeterminate progress fallback
```tsx theme={null}
{data?.total ? (
) : (
)}
```
```css theme={null}
.progress-bar-indeterminate {
height: 100%;
width: 40%;
background: linear-gradient(90deg, #6366f1, #8b5cf6);
border-radius: 3px;
animation: indeterminate 1.5s infinite ease-in-out;
}
@keyframes indeterminate {
0% { transform: translateX(-100%); }
100% { transform: translateX(350%); }
}
```
## Filtering completed progress
Once a tool completes, you typically want to remove its progress card and let the final result appear in the message stream. Filter by state:
```ts theme={null}
const activeProgress = toolProgress.filter((tp) => tp.state !== "complete");
```
Alternatively, keep completed cards visible briefly with a fade-out animation:
```tsx theme={null}
function ToolProgressCard({ progress }: { progress: ToolProgress }) {
const isComplete = progress.state === "complete";
return (
{/* ... card content ... */}
);
}
```
```css theme={null}
.fade-out {
animation: fadeOut 1s ease forwards;
animation-delay: 0.5s;
}
@keyframes fadeOut {
to {
opacity: 0;
height: 0;
padding: 0;
margin: 0;
overflow: hidden;
}
}
```
## Combining with regular tool calls
Async iterator tools and standard tool calls can coexist in the same agent. The final result of an async iterator tool appears in the message stream as a regular tool response, while progress updates come through `toolProgress`.
```tsx theme={null}
function MessageList({ messages, toolProgress }) {
return (
);
}
```
Position progress cards inline with messages rather than in a separate panel. This creates a natural reading flow where users see the progress update followed by the result in the same conversation thread.
## Handling multiple concurrent tools
An agent may execute multiple async iterator tools in parallel. Each has its own `toolCallId`, so they render as separate progress cards:
```tsx theme={null}
{activeProgress.map((tp) => (
))}
```
When multiple tools run simultaneously, consider stacking their progress cards vertically with clear labels so users can distinguish between them:
```tsx theme={null}
function MultiToolProgress({ progressItems }: { progressItems: ToolProgress[] }) {
return (
);
}
```
## Best practices
Progress updates arrive at the rate the server yields them. If updates are too frequent (e.g., per-row in a million-row scan), throttle rendering on the client side to avoid DOM thrashing.
* **Show the latest item** — displaying `data.latest` gives users a sense of *what* is being processed, not just *how much*
* **Use transitions on the progress bar** — `transition: width 0.3s ease` makes the bar animate smoothly between updates
* **Handle missing totals** — fall back to an indeterminate progress bar when `data.total` is not yet known
* **Clean up completed cards** — remove or fade out progress cards once the tool finishes to keep the UI uncluttered
* **Throttle rapid updates** — if progress updates arrive faster than 60fps, debounce the state updates to maintain smooth rendering
* **Provide cancel affordance** — if the agent supports interruption, add a cancel button to the progress card so users can abort long-running tools
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/frontend/async-iterator-tools.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.