;
};
Agents can invoke external tools like weather APIs, calculators, web search,
database queries, and more. The results are in raw JSON. This pattern shows you
how to render
structured, type-safe UI cards for every tool call your agent makes, complete
with loading states and error handling.
## How tool calling works
When a LangGraph agent decides it needs external data, it emits one or more
**tool calls** as part of an AI message. Each tool call includes:
* **name**: the tool being invoked (e.g. `"get_weather"`, `"calculator"`)
* **args**: the structured arguments passed to the tool
* **id**: a unique identifier linking the call to its result
The agent runtime executes the tool, and the result comes back as a
`ToolMessage`. The `useStream` hook unifies all of this into a single
`toolCalls` array you can render directly.
## Setting up useStream
The first step is wiring up `useStream` to your agent backend. The hook returns
reactive state including a `toolCalls` array that updates in real time as the
agent streams.
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 Chat() {
const stream = useStream({
apiUrl: AGENT_URL,
assistantId: "tool_calling",
});
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-chat",
template: `
@for (msg of stream.messages(); track msg.id) {
}
`,
})
export class ChatComponent {
stream = useStream({
apiUrl: AGENT_URL,
assistantId: "tool_calling",
});
}
```
## The ToolCallWithResult type
Each entry in the `toolCalls` array is a `ToolCallWithResult` object:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
interface ToolCallWithResult {
call: {
id: string;
name: string;
args: Record;
};
result: ToolMessage | undefined;
state: "pending" | "completed" | "error";
}
```
| Property | Description |
| ----------- | ------------------------------------------------------------------------------------------ |
| `call.id` | Unique ID matching the AI message's `tool_calls` entry |
| `call.name` | The name of the tool (e.g. `"get_weather"`) |
| `call.args` | Structured arguments the agent passed to the tool |
| `result` | The `ToolMessage` response, available once the tool finishes |
| `state` | Lifecycle state: `"pending"` while running, `"completed"` on success, `"error"` on failure |
## Filtering tool calls per message
An AI message may trigger multiple tool calls, and your chat may contain many AI
messages. To render the right tool cards under each message, filter by matching
`call.id` against the message's `tool_calls` array:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function Message({
message,
toolCalls,
}: {
message: AIMessage;
toolCalls: ToolCallWithResult[];
}) {
const messageToolCalls = toolCalls.filter((tc) =>
message.tool_calls?.find((t) => t.id === tc.call.id)
);
return (
{message.content}
{messageToolCalls.map((tc) => (
))}
);
}
```
## Building specialized tool cards
Rather than dumping raw JSON, build dedicated UI components for each tool. Use
`call.name` to select the right card:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function ToolCard({ toolCall }: { toolCall: ToolCallWithResult }) {
if (toolCall.state === "pending") {
return ;
}
if (toolCall.state === "error") {
return ;
}
switch (toolCall.call.name) {
case "get_weather":
return ;
case "calculator":
return (
);
case "web_search":
return ;
default:
return ;
}
}
```
### Weather card example
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function WeatherCard({
args,
result,
}: {
args: { location: string };
result: ToolMessage;
}) {
const data = JSON.parse(result.content as string);
return (
{args.location}
{data.temperature}°F
{data.condition}
);
}
```
### Loading and error states
Always handle the pending and error states to give users clear feedback:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function LoadingCard({ name }: { name: string }) {
return (
);
}
```
## Type-safe tool arguments
If your tools are defined with structured schemas, you can use the
`ToolCallFromTool` utility type to get fully typed `args`:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "@langchain/core/tools";
import { z } from "zod";
const getWeather = tool(async ({ location }) => { /* ... */ }, {
name: "get_weather",
description: "Get the current weather for a location",
schema: z.object({
location: z.string().describe("City name"),
}),
});
type WeatherToolCall = ToolCallFromTool;
// WeatherToolCall.call.args is now { location: string }
```
Using `ToolCallFromTool` gives you compile-time safety. If the tool schema
changes, your UI components will flag type errors immediately.
## Rendering tool calls inline with streaming text
Tool calls often arrive interleaved with streamed text. The `useStream` hook
keeps `toolCalls` in sync with the stream, so pending cards appear as soon as
the agent emits the call, before the tool has finished executing.
This means users see:
1. The AI's text as it streams in
2. A loading card the moment a tool call is emitted
3. The card updates to show the result once the tool completes
Tool calls update in place. The same `call.id` transitions from `"pending"` to
`"completed"` (or `"error"`), so your UI re-renders the same component
with new state.
## Handling multiple concurrent tool calls
Agents can invoke several tools in parallel. The `toolCalls` array will contain
multiple entries with `state: "pending"` simultaneously. Each resolves
independently, so your UI should handle partial completion gracefully:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function ToolCallList({ toolCalls }: { toolCalls: ToolCallWithResult[] }) {
const pending = toolCalls.filter((tc) => tc.state === "pending");
const completed = toolCalls.filter((tc) => tc.state === "completed");
return (
);
}
```
## Best practices
Follow these guidelines when building tool call UIs:
* **Always handle all three states**: `pending`, `completed`, and `error`.
Users should never see a blank card.
* **Parse results safely**. Tool results arrive as strings. Wrap
`JSON.parse()` in a try/catch and show a fallback on parse failure.
* **Provide a generic fallback**. Not every tool needs a bespoke card. Render
a collapsible JSON view for unknown tool names.
* **Show the tool name and args during loading**. Users want to know *what*
the agent is doing, even before the result arrives.
* **Keep cards compact**. Tool cards sit inline with chat messages. Avoid
overwhelming the conversation with oversized widgets.
***
[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/langchain/frontend/tool-calling.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).