;
};
Conversations with AI agents are rarely linear. You may want to rephrase a
question, regenerate a response you didn't like, or explore a completely
different conversational path without losing your previous work. Branching chat
brings version-control semantics to your chat UI. Every edit creates a new
branch, and you can freely navigate between them.
This feature requires the [LangGraph Agent Server](/langsmith/local-server). Run your agent locally with `langgraph dev` or [deploy it to LangSmith](/langsmith/deployment) to use this pattern.
## What is branching chat?
Branching chat treats a conversation as a tree rather than a list. Each message
is a node, and editing a message or regenerating a response creates a **fork**
from that point. The original path is preserved as a sibling branch, so users
can switch back and forth between different conversation trajectories.
Key capabilities:
* **Edit any user message:** rewrite a previous prompt and re-run the agent
from that point
* **Regenerate any AI response:** ask the agent to produce a different answer
for the same input
* **Navigate branches:** switch between different versions of the conversation
using per-message branch controls
## Set up useStream with history
To enable branching, pass `fetchStateHistory: true` so that `useStream`
retrieves checkpoint metadata needed for branch operations.
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: "branching_chat",
fetchStateHistory: 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-chat",
template: `
@for (msg of stream.messages(); track msg.id) {
}
`,
})
export class ChatComponent {
stream = useStream({
apiUrl: AGENT_URL,
assistantId: "branching_chat",
fetchStateHistory: true,
});
handleEdit(msg: any, metadata: any, text: string) {
const checkpoint = metadata.firstSeenState?.parent_checkpoint;
if (!checkpoint) return;
this.stream.submit(
{ messages: [{ ...msg, content: text }] },
{ checkpoint }
);
}
handleRegenerate(metadata: any) {
const checkpoint = metadata.firstSeenState?.parent_checkpoint;
if (!checkpoint) return;
this.stream.submit(undefined, { checkpoint });
}
}
```
## Understand message metadata
The `getMessagesMetadata(msg)` function returns branch information for each
message:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
interface MessageMetadata {
branch: string;
branchOptions: string[];
firstSeenState: {
parent_checkpoint: Checkpoint | null;
};
}
```
| Property | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
| `branch` | The branch ID of this specific message version |
| `branchOptions` | Array of all branch IDs available for this message position |
| `firstSeenState.parent_checkpoint` | The checkpoint just before this message. Use it as the fork point for edits and regenerations |
When a message has only one version, `branchOptions` contains a single entry.
After an edit or regeneration, new branch IDs are added to `branchOptions`,
and you can navigate between them.
## Edit a message
To edit a user message and create a new branch:
1. Get the `parent_checkpoint` from the message's metadata
2. Submit the edited message with that checkpoint
3. The agent re-runs from that point, creating a new branch
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function handleEdit(
stream: ReturnType,
originalMsg: HumanMessage,
metadata: MessageMetadata,
newText: string
) {
const checkpoint = metadata.firstSeenState?.parent_checkpoint;
if (!checkpoint) return;
stream.submit(
{
messages: [{ ...originalMsg, content: newText }],
},
{ checkpoint }
);
}
```
After the edit:
* The message's `branchOptions` gains a new entry
* The view switches to the new branch automatically
* The agent re-runs from the fork point with the updated message
* The original version is preserved and accessible via the branch switcher
## Regenerate a response
To regenerate an AI response without changing the input:
1. Get the `parent_checkpoint` from the AI message's metadata
2. Submit with `undefined` input and the parent checkpoint
3. The agent produces a fresh response, creating a new branch
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function handleRegenerate(
stream: ReturnType,
metadata: MessageMetadata
) {
const checkpoint = metadata.firstSeenState?.parent_checkpoint;
if (!checkpoint) return;
stream.submit(undefined, { checkpoint });
}
```
Each regeneration creates a new branch for the AI message at that position.
Users can then use the branch switcher to compare different responses.
Regeneration is useful for non-deterministic agents. Since LLM outputs vary
with temperature, regenerating the same prompt often produces meaningfully
different responses.
## Build a branch switcher
When a message has multiple branches, show a compact inline control with the
current version index and navigation arrows:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function BranchSwitcher({
metadata,
onSwitch,
}: {
metadata: MessageMetadata;
onSwitch: (branchId: string) => void;
}) {
const { branch, branchOptions } = metadata;
if (branchOptions.length <= 1) return null;
const currentIndex = branchOptions.indexOf(branch);
const hasPrev = currentIndex > 0;
const hasNext = currentIndex < branchOptions.length - 1;
return (
{currentIndex + 1}/{branchOptions.length}
);
}
```
When the user clicks a branch arrow, call `stream.setBranch(branchId)` to
switch the conversation view to that branch. This is instant since all branch
data is already loaded via `fetchStateHistory: true`.
Switching branches affects not only the target message but also all subsequent
messages. If you switch to a different version of message 3, messages 4, 5, 6,
etc. will also update to reflect the conversation that followed that version.
## How branching works under the hood
LangGraph persists every state transition as a **checkpoint**. When you submit
with a `checkpoint` parameter, the backend forks from that point instead of
appending to the current conversation. The result is a tree structure:
```
User: "What is React?"
└─ AI: "React is a JavaScript library..." (branch A)
└─ AI: "React is a UI framework..." (branch B, regenerated)
User: "Tell me about hooks" (branch A)
└─ AI: "Hooks are functions..."
User: "Tell me about JSX" (edited from branch A)
└─ AI: "JSX is a syntax extension..."
```
Each branch is an independent path through the conversation tree. Switching
branches updates the displayed messages but does not delete any data. All
branches persist in the checkpoint store.
## Complete message component
Here is a full component that combines message display, editing, regeneration,
and branch switching:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function MessageWithBranching({
message,
metadata,
stream,
}: {
message: BaseMessage;
metadata: MessageMetadata;
stream: ReturnType;
}) {
const [isEditing, setIsEditing] = useState(false);
const [editText, setEditText] = useState(message.content as string);
const isHuman = message._getType() === "human";
const isAI = message._getType() === "ai";
const hasBranches = metadata.branchOptions.length > 1;
return (