工作原理
DeepAgents 内置的 todos 状态 + useStream hook 的实时同步
在 LangGraph Agent 中，状态不仅限于消息。除了你可以自己定义的自定义状态键，DeepAgents 还内置了 todos 数组来保存 Agent 的任务计划——它由内置的 todoListMiddleware 自动注入，无需手动定义。当 Agent 执行计划时，它通过内置的 write_todos 工具把每个待办项的状态从 "pending" 更新为 "in_progress" 再到 "completed"。
1. 用户提交
发送请求给 Agent
2. 创建计划
Agent 填充 todos 数组
3. 逐步执行
pending → in_progress → completed
4. 实时同步
stream.values.todos 更新
5. UI 重渲染
组件响应式更新视图
// Agent 端：todos 是 DeepAgents 内置状态键，
// 由 createAgent({ middleware: [todoListMiddleware()] }) 自动注入，
// 开发者无需（也不应）在 Annotation 中手动定义它。
// Agent 通过内置的 write_todos 工具更新 todo 列表（每次调用替换整个数组）。
const AgentState = Annotation({
// messages 是 LangGraph 的标准状态键，使用内置的消息归并器
messages: Annotation({ reducer: messagesReducer }),
// 在这里你只需定义自己的自定义状态键；todos 会由中间件自动加入
});
// 前端：useStream hook 建立与 Agent 的流式连接
const stream = useStream({
apiUrl: "http://localhost:2024", // LangGraph 服务地址
assistantId: "deep_agent_todo_list", // 在 langgraph.json 中注册的图名称
});
// 从流式状态中读取 todos 数组，响应式更新
const todos = stream.values?.todos ?? [];
数据接口
每个待办项具有简单的结构——三个状态值 + 人类可读描述
interface Todo {
status: "pending" | "in_progress" | "completed";
content: string;
}| 属性 | 类型 | 说明 |
|---|---|---|
status |
"pending" | "in_progress" | "completed" |
任务的当前状态。pending 未开始、in_progress Agent 正在处理、completed 已完成 |
content |
string |
人类可读的任务描述，如"搜索相关文档" |
pending（未开始）
灰色图标 ○，灰色背景。Agent 尚未开始处理此项。
in_progress（进行中）
琥珀色图标 ◉，琥珀色背景，脉冲动画吸引用户注意。Agent 当前正在处理此项。
completed（已完成）
绿色图标 ✓，绿色背景，删除线样式。Agent 已完成此项。
状态流转方向：Agent 在创建计划时填充此数组，然后在执行每个步骤时更新各个待办项的状态。整个生命周期是
pending → in_progress → completed 的单向流转。
聊天结合
待办列表与聊天消息配合使用——顶部面板 + 下方消息区
function TodoAgentLayout() {
// 建立与 Agent 的流式连接
const stream = useStream<typeof myAgent>({
apiUrl: AGENT_URL,
assistantId: "deep_agent_todo_list",
});
const todos = stream.values?.todos ?? [];
return (
<div className="flex h-screen flex-col">
{/* 条件渲染：只在有待办项时显示进度面板 */}
{todos.length > 0 && (
<div className="border-b bg-gray-50 p-4">
<TodoList todos={todos} />
</div>
)}
{/* 聊天消息区：flex-1 占据剩余空间，支持滚动 */}
<main className="flex-1 overflow-y-auto p-6">
<div className="mx-auto max-w-2xl space-y-4">
{stream.messages.map((msg) => (
<Message key={msg.id} message={msg} />
))}
</div>
</main>
{/* 输入框：提交时构造 HumanMessage 发送给 Agent */}
<ChatInput
onSubmit={(text) =>
stream.submit({
messages: [{ type: "human", content: text }]
})
}
isLoading={stream.isLoading}
/>
</div>
);
}
注意：仅当
todos.length > 0 时才显示待办列表。在 Agent 创建计划之前，没有任何内容可显示。显示空组件只会浪费屏幕空间。
