) => {
return new Command({ // [!code highlight]
update: { // [!code highlight]
messages: [
new ToolMessage({
content: `Issue type recorded as: ${input.issueType}`,
tool_call_id: config.toolCallId,
}),
],
issueType: input.issueType,
currentStep: "resolution_specialist", // [!code highlight]
},
});
},
{
name: "record_issue_type",
description:
"Record the type of issue and transition to resolution specialist.",
schema: z.object({
issueType: IssueTypeSchema,
}),
}
);
const escalateToHuman = tool(
async (input) => {
// In a real system, this would create a ticket, notify staff, etc.
return `Escalating to human support. Reason: ${input.reason}`;
},
{
name: "escalate_to_human",
description: "Escalate the case to a human support specialist.",
schema: z.object({
reason: z.string(),
}),
}
);
const provideSolution = tool(
async (input) => {
return `Solution provided: ${input.solution}`;
},
{
name: "provide_solution",
description: "Provide a solution to the customer's issue.",
schema: z.object({
solution: z.string(),
}),
}
);
```
Notice how `record_warranty_status` and `record_issue_type` return `Command` objects that update both the data (`warranty_status`, `issue_type`) AND the `current_step`. This is how the state machine works - tools control workflow progression.
## 3. 定义步骤配置
Define prompts and tools for each step. First, define the prompts for each step:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Define prompts as constants for easy reference
const WARRANTY_COLLECTOR_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Warranty verification
At this step, you need to:
1. Greet the customer warmly
2. Ask if their device is under warranty
3. Use record_warranty_status to record their response and move to the next step
Be conversational and friendly. Don't ask multiple questions at once.`;
const ISSUE_CLASSIFIER_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Issue classification
CUSTOMER INFO: Warranty status is {warranty_status}
At this step, you need to:
1. Ask the customer to describe their issue
2. Determine if it's a hardware issue (physical damage, broken parts) or software issue (app crashes, performance)
3. Use record_issue_type to record the classification and move to the next step
If unclear, ask clarifying questions before classifying.`;
const RESOLUTION_SPECIALIST_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Resolution
CUSTOMER INFO: Warranty status is {warranty_status}, issue type is {issue_type}
At this step, you need to:
1. For SOFTWARE issues: provide troubleshooting steps using provide_solution
2. For HARDWARE issues:
- If IN WARRANTY: explain warranty repair process using provide_solution
- If OUT OF WARRANTY: escalate_to_human for paid repair options
Be specific and helpful in your solutions.`;
```
Then map step names to their configurations using a dictionary:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Step configuration: maps step name to (prompt, tools, required_state)
const STEP_CONFIG = {
warranty_collector: {
prompt: WARRANTY_COLLECTOR_PROMPT,
tools: [recordWarrantyStatus],
requires: [],
},
issue_classifier: {
prompt: ISSUE_CLASSIFIER_PROMPT,
tools: [recordIssueType],
requires: ["warrantyStatus"],
},
resolution_specialist: {
prompt: RESOLUTION_SPECIALIST_PROMPT,
tools: [provideSolution, escalateToHuman],
requires: ["warrantyStatus", "issueType"],
},
} as const;
```
This dictionary-based configuration makes it easy to:
* See all steps at a glance
* Add new steps (just add another entry)
* Understand the workflow dependencies (`requires` field)
* Use prompt templates with state variables (e.g., `{warranty_status}`)
## 4. 创建基于步骤的中间件
Create middleware that reads `current_step` from state and applies the appropriate configuration. We'll use the `@wrap_model_call` decorator for a clean implementation:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createMiddleware } from "langchain";
const applyStepMiddleware = createMiddleware({
name: "applyStep",
stateSchema: SupportState,
wrapModelCall: async (request, handler) => {
// Get current step (defaults to warranty_collector for first interaction)
const currentStep = request.state.currentStep ?? "warranty_collector"; // [!code highlight]
// Look up step configuration
const stepConfig = STEP_CONFIG[currentStep]; // [!code highlight]
// Validate required state exists
for (const key of stepConfig.requires) {
if (request.state[key] === undefined) {
throw new Error(`${key} must be set before reaching ${currentStep}`);
}
}
// Format prompt with state values (supports {warrantyStatus}, {issueType}, etc.)
let systemPrompt: string = stepConfig.prompt;
for (const [key, value] of Object.entries(request.state)) {
systemPrompt = systemPrompt.replace(`{${key}}`, String(value ?? ""));
}
// Inject system prompt and step-specific tools
return handler({
...request, // [!code highlight]
systemPrompt, // [!code highlight]
tools: [...stepConfig.tools], // [!code highlight]
});
},
});
```
This middleware:
1. **Reads current step**: Gets `current_step` from state (defaults to "warranty\_collector").
2. **Looks up configuration**: Finds the matching entry in `STEP_CONFIG`.
3. **Validates dependencies**: Ensures required state fields exist.
4. **Formats prompt**: Injects state values into the prompt template.
5. **Applies configuration**: Overrides the system prompt and available tools.
The `request.override()` method is key - it allows us to dynamically change the agent's behavior based on state without creating separate agent instances.
## 5. 创建智能体
Now create the agent with the step-based middleware and a checkpointer for state persistence:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
// Collect all tools from all step configurations
const allTools = [
recordWarrantyStatus,
recordIssueType,
provideSolution,
escalateToHuman,
];
// Initialize the model
const model = new ChatOpenAI({
model: "gpt-5.4-mini",
temperature: 0.7,
});
// Create the agent with step-based configuration
const agent = createAgent({
model,
tools: allTools,
stateSchema: SupportState, // [!code highlight]
middleware: [applyStepMiddleware], // [!code highlight]
checkpointer: new MemorySaver(), // [!code highlight]
});
```
**Why a checkpointer?** The checkpointer maintains state across conversation turns. Without it, the `current_step` state would be lost between user messages, breaking the workflow.
## 6. 测试工作流
Test the complete workflow:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { HumanMessage } from "@langchain/core/messages";
import { v7 as uuid7 } from "uuid";
// Configuration for this conversation thread
const threadId = uuid7();
const config = { configurable: { thread_id: threadId } };
// Turn 1: Initial message - starts with warranty_collector step
console.log("=== Turn 1: Warranty Collection ===");
let result = await agent.invoke(
{ messages: [new HumanMessage("Hi, my phone screen is cracked")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
// Turn 2: User responds about warranty
console.log("\n=== Turn 2: Warranty Response ===");
result = await agent.invoke(
{ messages: [new HumanMessage("Yes, it's still under warranty")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
console.log(`Current step: ${result.currentStep}`);
// Turn 3: User describes the issue
console.log("\n=== Turn 3: Issue Description ===");
result = await agent.invoke(
{ messages: [new HumanMessage("The screen is physically cracked from dropping it")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
console.log(`Current step: ${result.currentStep}`);
// Turn 4: Resolution
console.log("\n=== Turn 4: Resolution ===");
result = await agent.invoke(
{ messages: [new HumanMessage("What should I do?")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
```
Expected flow:
1. **Warranty verification step**: Asks about warranty status
2. **Issue classification step**: Asks about the problem, determines it's hardware
3. **Resolution step**: Provides warranty repair instructions
## 7. 理解状态转换
Let's trace what happens at each turn:
### 第 1 轮：初始消息
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
messages: [new HumanMessage("Hi, my phone screen is cracked")],
currentStep: "warranty_collector" // Default value
}
```
Middleware applies:
* System prompt: `WARRANTY_COLLECTOR_PROMPT`
* Tools: `[record_warranty_status]`
### 第 2 轮：记录保修后
Tool call: `recordWarrantyStatus("in_warranty")` returns:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
new Command({
update: {
warrantyStatus: "in_warranty",
currentStep: "issue_classifier" // State transition!
}
})
```
Next turn, middleware applies:
* System prompt: `ISSUE_CLASSIFIER_PROMPT` (formatted with `warranty_status="in_warranty"`)
* Tools: `[record_issue_type]`
### 第 3 轮：问题分类后
Tool call: `recordIssueType("hardware")` returns:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
new Command({
update: {
issueType: "hardware",
currentStep: "resolution_specialist" // State transition!
}
})
```
Next turn, middleware applies:
* System prompt: `RESOLUTION_SPECIALIST_PROMPT` (formatted with `warranty_status` and `issue_type`)
* Tools: `[provide_solution, escalate_to_human]`
The key insight: **Tools drive the workflow** by updating `current_step`, and **middleware responds** by applying the appropriate configuration on the next turn.
## 8. 管理消息历史
As the agent progresses through steps, message history grows. Use [summarization middleware](/oss/javascript/langchain/short-term-memory#summarize-messages) to compress earlier messages while preserving conversational context:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createAgent, SummarizationMiddleware } from "langchain"; // [!code highlight]
import { MemorySaver } from "@langchain/langgraph";
const agent = createAgent({
model,
tools: allTools,
stateSchema: SupportState,
middleware: [
applyStepMiddleware,
new SummarizationMiddleware({ // [!code highlight]
model: "gpt-5.4-mini",
trigger: { tokens: 4000 },
keep: { messages: 10 },
}),
],
checkpointer: new MemorySaver(),
});
```
See the [short-term memory guide](/oss/javascript/langchain/short-term-memory) for other memory management techniques.
## 9. 增加灵活性：返回上一步
Some workflows need to allow users to return to previous steps to correct information (e.g., changing warranty status or issue classification). However, not all transitions make sense—for example, you typically can't go back once a refund has been processed. For this support workflow, we'll add tools to return to the warranty verification and issue classification steps.
If your workflow requires arbitrary transitions between most steps, consider whether you need a structured workflow at all. This pattern works best when steps follow a clear sequential progression with occasional backwards transitions for corrections.
Add "go back" tools to the resolution step:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { tool } from "langchain";
import { Command } from "@langchain/langgraph";
import { z } from "zod";
const goBackToWarranty = tool( // [!code highlight]
async () => {
return new Command({ update: { currentStep: "warranty_collector" } }); // [!code highlight]
},
{
name: "go_back_to_warranty",
description: "Go back to warranty verification step.",
schema: z.object({}),
}
);
const goBackToClassification = tool( // [!code highlight]
async () => {
return new Command({ update: { currentStep: "issue_classifier" } }); // [!code highlight]
},
{
name: "go_back_to_classification",
description: "Go back to issue classification step.",
schema: z.object({}),
}
);
// Update the resolution_specialist configuration to include these tools
STEP_CONFIG.resolution_specialist.tools.push(
goBackToWarranty,
goBackToClassification
);
```
Update the resolution specialist's prompt to mention these tools:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const RESOLUTION_SPECIALIST_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Resolution
CUSTOMER INFO: Warranty status is {warrantyStatus}, issue type is {issueType}
At this step, you need to:
1. For SOFTWARE issues: provide troubleshooting steps using provide_solution
2. For HARDWARE issues:
- If IN WARRANTY: explain warranty repair process using provide_solution
- If OUT OF WARRANTY: escalate_to_human for paid repair options
If the customer indicates any information was wrong, use:
- go_back_to_warranty to correct warranty status
- go_back_to_classification to correct issue type
Be specific and helpful in your solutions.`;
```
Now the agent can handle corrections:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const result = await agent.invoke(
{ messages: [new HumanMessage("Actually, I made a mistake - my device is out of warranty")] },
config
);
// Agent will call go_back_to_warranty and restart the warranty verification step
```
## 完整示例
Here's everything together in a runnable script:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createMiddleware, createAgent } from "langchain";
import { z } from "zod";
import { v4 as uuidv4 } from "uuid";
import { tool, ToolMessage, type ToolRuntime, HumanMessage } from "langchain";
import { Command, MemorySaver, StateSchema } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
// Define the possible workflow steps
const SupportStepSchema = z.enum([
"warranty_collector",
"issue_classifier",
"resolution_specialist",
]);
const WarrantyStatusSchema = z.enum(["in_warranty", "out_of_warranty"]);
const IssueTypeSchema = z.enum(["hardware", "software"]);
// State for customer support workflow
const SupportState = new StateSchema({
currentStep: SupportStepSchema.optional(),
warrantyStatus: WarrantyStatusSchema.optional(),
issueType: IssueTypeSchema.optional(),
});
const recordWarrantyStatus = tool(
async (input, config: ToolRuntime) => {
return new Command({
update: {
messages: [
new ToolMessage({
content: `Warranty status recorded as: ${input.status}`,
tool_call_id: config.toolCallId,
}),
],
warrantyStatus: input.status,
currentStep: "issue_classifier",
},
});
},
{
name: "record_warranty_status",
description:
"Record the customer's warranty status and transition to issue classification.",
schema: z.object({
status: WarrantyStatusSchema,
}),
}
);
const recordIssueType = tool(
async (input, config: ToolRuntime) => {
return new Command({
update: {
messages: [
new ToolMessage({
content: `Issue type recorded as: ${input.issueType}`,
tool_call_id: config.toolCallId,
}),
],
issueType: input.issueType,
currentStep: "resolution_specialist",
},
});
},
{
name: "record_issue_type",
description:
"Record the type of issue and transition to resolution specialist.",
schema: z.object({
issueType: IssueTypeSchema,
}),
}
);
const escalateToHuman = tool(
async (input) => {
// In a real system, this would create a ticket, notify staff, etc.
return `Escalating to human support. Reason: ${input.reason}`;
},
{
name: "escalate_to_human",
description: "Escalate the case to a human support specialist.",
schema: z.object({
reason: z.string(),
}),
}
);
const provideSolution = tool(
async (input) => {
return `Solution provided: ${input.solution}`;
},
{
name: "provide_solution",
description: "Provide a solution to the customer's issue.",
schema: z.object({
solution: z.string(),
}),
}
);
// Define prompts as constants for easy reference
const WARRANTY_COLLECTOR_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Warranty verification
At this step, you need to:
1. Greet the customer warmly
2. Ask if their device is under warranty
3. Use record_warranty_status to record their response and move to the next step
Be conversational and friendly. Don't ask multiple questions at once.`;
const ISSUE_CLASSIFIER_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Issue classification
CUSTOMER INFO: Warranty status is {warranty_status}
At this step, you need to:
1. Ask the customer to describe their issue
2. Determine if it's a hardware issue (physical damage, broken parts) or software issue (app crashes, performance)
3. Use record_issue_type to record the classification and move to the next step
If unclear, ask clarifying questions before classifying.`;
const RESOLUTION_SPECIALIST_PROMPT = `You are a customer support agent helping with device issues.
CURRENT STAGE: Resolution
CUSTOMER INFO: Warranty status is {warranty_status}, issue type is {issue_type}
At this step, you need to:
1. For SOFTWARE issues: provide troubleshooting steps using provide_solution
2. For HARDWARE issues:
- If IN WARRANTY: explain warranty repair process using provide_solution
- If OUT OF WARRANTY: escalate_to_human for paid repair options
Be specific and helpful in your solutions.`;
// Step configuration: maps step name to (prompt, tools, required_state)
const STEP_CONFIG = {
warranty_collector: {
prompt: WARRANTY_COLLECTOR_PROMPT,
tools: [recordWarrantyStatus],
requires: [],
},
issue_classifier: {
prompt: ISSUE_CLASSIFIER_PROMPT,
tools: [recordIssueType],
requires: ["warrantyStatus"],
},
resolution_specialist: {
prompt: RESOLUTION_SPECIALIST_PROMPT,
tools: [provideSolution, escalateToHuman],
requires: ["warrantyStatus", "issueType"],
},
} as const;
const applyStepMiddleware = createMiddleware({
name: "applyStep",
stateSchema: SupportState,
wrapModelCall: async (request, handler) => {
// Get current step (defaults to warranty_collector for first interaction)
const currentStep = request.state.currentStep ?? "warranty_collector";
// Look up step configuration
const stepConfig = STEP_CONFIG[currentStep];
// Validate required state exists
for (const key of stepConfig.requires) {
if (request.state[key] === undefined) {
throw new Error(`${key} must be set before reaching ${currentStep}`);
}
}
// Format prompt with state values (supports {warrantyStatus}, {issueType}, etc.)
let systemPrompt: string = stepConfig.prompt;
for (const [key, value] of Object.entries(request.state)) {
systemPrompt = systemPrompt.replace(`{${key}}`, String(value ?? ""));
}
// Inject system prompt and step-specific tools
return handler({
...request,
systemPrompt,
tools: [...stepConfig.tools],
});
},
});
// Collect all tools from all step configurations
const allTools = [
recordWarrantyStatus,
recordIssueType,
provideSolution,
escalateToHuman,
];
const model = new ChatOpenAI({
model: "gpt-5.4-mini",
});
// Create the agent with step-based configuration
const agent = createAgent({
model,
tools: allTools,
middleware: [applyStepMiddleware],
checkpointer: new MemorySaver(),
});
// Configuration for this conversation thread
const threadId = uuidv4();
const config = { configurable: { thread_id: threadId } };
// Turn 1: Initial message - starts with warranty_collector step
console.log("=== Turn 1: Warranty Collection ===");
let result = await agent.invoke(
{ messages: [new HumanMessage("Hi, my phone screen is cracked")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
// Turn 2: User responds about warranty
console.log("\n=== Turn 2: Warranty Response ===");
result = await agent.invoke(
{ messages: [new HumanMessage("Yes, it's still under warranty")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
console.log(`Current step: ${result.currentStep}`);
// Turn 3: User describes the issue
console.log("\n=== Turn 3: Issue Description ===");
result = await agent.invoke(
{
messages: [
new HumanMessage("The screen is physically cracked from dropping it"),
],
},
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
console.log(`Current step: ${result.currentStep}`);
// Turn 4: Resolution
console.log("\n=== Turn 4: Resolution ===");
result = await agent.invoke(
{ messages: [new HumanMessage("What should I do?")] },
config
);
for (const msg of result.messages) {
console.log(msg.content);
}
```
## 后续步骤
* Learn about the [subagents pattern](/oss/javascript/langchain/multi-agent/subagents-personal-assistant) for centralized orchestration
* Explore [middleware](/oss/javascript/langchain/middleware) for more dynamic behaviors
* Read the [multi-agent overview](/oss/javascript/langchain/multi-agent) to compare patterns
* Use [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-langchain-multi-agent-handoffs-customer-support) to debug and monitor your multi-agent system
***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
[在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/multi-agent/handoffs-customer-support.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。