消息队列让用户可以快速连续发送多条消息，而无需等待代理完成处理当前消息。每条消息都在服务器端排队并按顺序处理，让您可以完全了解和控制待处理队列。
为什么需要消息队列？
在典型的聊天界面中，用户必须等待代理完成响应后才能发送另一条消息。这在以下场景中会造成摩擦：
- 批量问题：用户想要一次提出五个相关问题，而不是等待每个答案
- 后续追问：在代理仍在工作时提交澄清或额外上下文
- 自动化测试序列：以编程方式发送一系列提示以验证代理行为
- 数据输入工作流程：一个接一个地输入结构化输入进行处理
消息队列通过立即接受所有提交并按顺序处理来解决这个问题。
工作原理
在底层，LangGraph 使用 multitaskStrategy: "enqueue" 来管理并发提交。当在代理已经处理时提交消息，它会被添加到服务器端队列。一旦当前运行完成，下一条排队的消息会自动被拾取。
useStream 钩子暴露了一个 queue 属性，提供对待处理消息的实时可见性：
| 属性 | 类型 | 描述 |
|---|
queue.entries | QueueEntry[] | 所有待处理队列条目的数组 |
queue.size | number | 当前队列中的条目数量 |
queue.cancel(id) | (id: string) => Promise<void> | 按 ID 取消特定的排队条目 |
queue.clear() | () => Promise<void> | 取消所有排队条目 |
QueueEntry 对象包含：
| 字段 | 类型 | 描述 |
|---|
id | string | 此队列条目的唯一标识符 |
values | object | 提交的输入值（包括消息） |
options | object | 随提交传递的任何其他选项 |
createdAt | string | 条目创建时间的 ISO 时间戳 |
设置 useStream
定义一个与代理状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以便对状态值进行类型安全访问。在下面的示例中，将 typeof myAgent 替换为您的接口名称：
import type { BaseMessage } from "@langchain/core/messages";
interface AgentState {
messages: BaseMessage[];
}
import { useStream } from "@langchain/react";
function Chat() {
const stream = useStream<typeof myAgent>({
apiUrl: "http://localhost:2024",
assistantId: "message_queue",
});
const handleSubmit = (text: string) => {
stream.submit({
messages: [{ type: "human", content: text }],
});
};
// Access queue state
const pendingCount = stream.queue.size;
const entries = stream.queue.entries;
return (
<div>
<MessageList messages={stream.messages} />
{pendingCount > 0 && <QueueList entries={entries} queue={stream.queue} />}
<ChatInput onSubmit={handleSubmit} />
</div>
);
}
显示队列
构建一个 QueueList 组件，显示每条待处理消息并带有取消按钮。这让用户了解等待的内容，并能够删除不再需要的项目。
function QueueList({ entries, queue }) {
return (
<div className="queue-panel">
<div className="queue-header">
<span>Queued messages ({entries.length})</span>
<button onClick={() => queue.clear()}>Clear all</button>
</div>
<ul className="queue-entries">
{entries.map((entry) => {
const text = entry.values?.messages?.[0]?.content ?? "Unknown";
return (
<li key={entry.id} className="queue-entry">
<span className="queue-text">{text}</span>
<span className="queue-time">
{new Date(entry.createdAt).toLocaleTimeString()}
</span>
<button
className="queue-cancel"
onClick={() => queue.cancel(entry.id)}
>
Cancel
</button>
</li>
);
})}
</ul>
</div>
);
}
显示每条排队消息的前几个字符作为预览，以便用户可以快速识别要取消的项目，而无需阅读完整消息。
取消排队的消息
您有两个级别的取消：
取消单个条目
通过其 ID 从队列中移除特定消息。代理将跳过它并移动到下一个条目。
await queue.cancel(entryId);
清除整个队列
一次移除所有待处理消息。在用户更改上下文或想要重新开始时很有用。
取消队列条目仅影响尚未开始处理的消息。如果代理已经在处理某条消息，从队列中取消它不会产生效果。使用 stream.stop() 中断当前运行。
使用 onCreated 链式后续提交
onCreated 回调在新运行创建时触发，让您可以编程方式提交后续消息。对于构建下一步依赖于前一个提交被接受的多步骤工作流程很有用。
stream.submit(
{ messages: [{ type: "human", content: "What is quantum computing?" }] },
{
onCreated(run) {
console.log("Run created:", run.run_id);
// Chain a follow-up
stream.submit({
messages: [{ type: "human", content: "Give me a simple analogy." }],
});
},
}
);
开始新线程
当用户想要开始新的对话时，使用 switchThread(null) 创建新线程。这会清除当前消息历史和队列。
function NewThreadButton() {
const stream = useStream<typeof myAgent>({ /* ... */ });
return (
<button onClick={() => stream.switchThread(null)}>
New conversation
</button>
);
}
完整示例
将所有内容整合在一起，这是一个带有队列管理的完整聊天组件：
function QueueChat() {
const stream = useStream<typeof myAgent>({
apiUrl: "http://localhost:2024",
assistantId: "message_queue",
});
const [input, setInput] = useState("");
const handleSubmit = () => {
if (!input.trim()) return;
stream.submit({
messages: [{ type: "human", content: input.trim() }],
});
setInput("");
};
return (
<div className="chat-container">
<header>
<h2>Queue Chat</h2>
<button onClick={() => stream.switchThread(null)}>New thread</button>
</header>
<div className="messages">
{stream.messages.map((msg, i) => (
<MessageBubble key={i} message={msg} />
))}
{stream.isLoading && <TypingIndicator />}
</div>
{stream.queue.size > 0 && (
<div className="queue-panel">
<strong>Queued ({stream.queue.size})</strong>
<button onClick={() => stream.queue.clear()}>Clear all</button>
{stream.queue.entries.map((entry) => (
<div key={entry.id} className="queue-item">
<span>{entry.values?.messages?.[0]?.content}</span>
<button onClick={() => stream.queue.cancel(entry.id)}>×</button>
</div>
))}
</div>
)}
<form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
<input
value={input}
onChange={(e) => setInput(e.target.value)}
placeholder="Type a message (you can send multiple!)"
/>
<button type="submit">Send</button>
</form>
</div>
);
}
最佳实践
- 限制队列大小：虽然队列大小没有硬性的客户端限制，但要注意非常大的队列会降低用户体验。考虑在队列超过合理阈值（例如 10 个项目）时显示警告。
- 显示队列位置：为每个排队项目编号，以便用户知道处理顺序。
- 保持输入焦点：提交后保持输入字段焦点，以便用户可以立即输入下一条消息。
- 动画过渡：当项目开始处理时，流畅地将项目从队列面板移动到消息列表。
- 优雅处理错误：如果排队消息失败，在不阻塞后续队列条目的情况下显示错误。
- 对快速提交进行防抖：对于自动化或编程提交，在消息之间添加小延迟以避免压垮服务器。
