待办列表

并非所有智能体交互都是聊天。有时智能体正在执行多步骤计划，展示进度的最佳方式是一个实时更新的待办列表。深度智能体待办列表模式直接从智能体状态读取 todos 数组，在智能体执行计划时渲染每个项目及其当前状态。它是建立在与聊天相同的 useStream 钩子上的进度面板。它展示了智能体状态可以驱动任何 UI，而不仅仅是消息气泡。

工作原理

在 LangGraph 智能体中，状态不限于消息。您可以定义自定义状态键来保存任意数据。在这种情况下，是一个 todos 数组。当智能体执行计划时，它将每个待办事项的状态从 "pending" 更新为 "in_progress" 再到 "completed"。useStream 钩子通过 stream.values 暴露这些自定义状态值，您的 UI 会响应式渲染它们。流程如下：

用户提交请求
智能体创建计划并在其状态中填充 todos
智能体开始执行每个待办事项，从 pending → in_progress → completed 过渡
stream.values.todos 随智能体进度实时更新
您的 UI 使用当前状态重新渲染待办列表

设置 useStream

无需特殊配置。将 useStream 指向您的智能体并从 stream.values 读取 todos。导入您的智能体并将 typeof myAgent 作为类型参数传递给 useStream，以获得对状态值的类型安全访问：

import type { myAgent } from "./agent";

import { useStream } from "@langchain/react";

const AGENT_URL = "http://localhost:2024";

export function TodoAgent() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_todo_list",
  });

  const todos = stream.values?.todos ?? [];

  return (
    <div>
      <TodoList todos={todos} />
      {stream.messages.map((msg) => (
        <Message key={msg.id} message={msg} />
      ))}
    </div>
  );
}

<script setup lang="ts">
import { useStream } from "@langchain/vue";
import { computed } from "vue";

const AGENT_URL = "http://localhost:2024";

const stream = useStream<typeof myAgent>({
  apiUrl: AGENT_URL,
  assistantId: "deep_agent_todo_list",
});

const todos = computed(() => stream.values.value?.todos ?? []);
</script>

<template>
  <div>
    <TodoList :todos="todos" />
    <Message
      v-for="msg in stream.messages.value"
      :key="msg.id"
      :message="msg"
    />
  </div>
</template>

<script lang="ts">
  import { useStream } from "@langchain/svelte";

  const AGENT_URL = "http://localhost:2024";

  const { messages, values, submit } = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_todo_list",
  });

  $: todos = $values?.todos ?? [];
</script>

<div>
  <TodoList {todos} />
  {#each $messages as msg (msg.id)}
    <Message message={msg} />
  {/each}
</div>

import { Component, computed } from "@angular/core";
import { useStream } from "@langchain/angular";

const AGENT_URL = "http://localhost:2024";

@Component({
  selector: "app-todo-agent",
  template: `
    <div>
      <app-todo-list [todos]="todos()" />
      @for (msg of stream.messages(); track msg.id) {
        <app-message [message]="msg" />
      }
    </div>
  `,
})
export class TodoAgentComponent {
  stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_todo_list",
  });

  todos = computed(() => this.stream.values()?.todos ?? []);
}

Todo 接口

数组中每个待办事项都有一个简单的结构：

interface Todo {
  status: "pending" | "in_progress" | "completed";
  content: string;
}

属性	描述
`status`	此任务的当前状态。选项：`pending`（未开始）、`in_progress`（智能体正在处理）、`completed`（已完成）
`content`	任务内容的人类可读描述

智能体在创建计划时填充此数组，然后在执行每个步骤时更新各个项目。

构建 TodoList 组件

待办列表渲染每个项目，包含状态图标、颜色编码和反映当前状态的视觉样式：

function TodoList({ todos }: { todos: Todo[] }) {
  const completed = todos.filter((t) => t.status === "completed").length;
  const percentage = todos.length
    ? Math.round((completed / todos.length) * 100)
    : 0;

  return (
    <div className="rounded-lg border bg-white p-4 shadow-sm">
      <div className="mb-4 flex items-center justify-between">
        <h2 className="text-lg font-semibold">智能体进度</h2>
        <span className="text-sm text-gray-500">
          {completed}/{todos.length} 个任务
        </span>
      </div>

      <ProgressBar percentage={percentage} />

      <ul className="mt-4 space-y-2">
        {todos.map((todo, i) => (
          <TodoItem key={i} todo={todo} />
        ))}
      </ul>
    </div>
  );
}

进度条

视觉进度条为用户提供整体完成情况的一览概览：

function ProgressBar({ percentage }: { percentage: number }) {
  return (
    <div className="space-y-1">
      <div className="flex items-center justify-between text-xs text-gray-500">
        <span>进度</span>
        <span>{percentage}%</span>
      </div>
      <div className="h-2 overflow-hidden rounded-full bg-gray-200">
        <div
          className="h-full rounded-full bg-green-500 transition-all duration-500"
          style={{ width: `${percentage}%` }}
        />
      </div>
    </div>
  );
}

单个待办项目

每个项目获得状态图标、颜色编码文本和已完成任务的删除线样式：

function TodoItem({ todo }: { todo: Todo }) {
  const config = {
    pending: {
      icon: "○",
      textClass: "text-gray-600",
      bgClass: "bg-gray-50",
      iconClass: "text-gray-400",
    },
    in_progress: {
      icon: "◉",
      textClass: "text-amber-800",
      bgClass: "bg-amber-50 border-amber-200",
      iconClass: "text-amber-500 animate-pulse",
    },
    completed: {
      icon: "✓",
      textClass: "text-green-800 line-through",
      bgClass: "bg-green-50 border-green-200",
      iconClass: "text-green-500",
    },
  };

  const style = config[todo.status];

  return (
    <li
      className={`flex items-start gap-3 rounded-md border px-3 py-2 ${style.bgClass}`}
    >
      <span className={`mt-0.5 text-lg leading-none ${style.iconClass}`}>
        {style.icon}
      </span>
      <span className={`text-sm ${style.textClass}`}>{todo.content}</span>
    </li>
  );
}

in_progress 图标使用 animate-pulse 来吸引对当前活跃任务的注意。

计算进度

直接从 todos 数组派生进度指标：

const todos = stream.values?.todos ?? [];

const completed = todos.filter((t) => t.status === "completed").length;
const inProgress = todos.filter((t) => t.status === "in_progress").length;
const pending = todos.filter((t) => t.status === "pending").length;
const percentage = todos.length
  ? Math.round((completed / todos.length) * 100)
  : 0;

这些值随智能体修改其状态而响应式更新，使进度条和计数器保持同步。

与聊天消息结合

待办列表与常规聊天界面协同工作。实用的布局将待办列表显示为持久的侧边栏或顶部面板，聊天消息在下方：

function TodoAgentLayout() {
  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>
      )}

      <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>

      <ChatInput
        onSubmit={(text) =>
          stream.submit({ messages: [{ type: "human", content: text }] })
        }
        isLoading={stream.isLoading}
      />
    </div>
  );
}

仅当 todos.length > 0 时显示待办列表。在智能体创建计划之前，没有内容可显示。显示空组件会浪费空间。

超越 todos 的自定义状态

此模式展示了一个强大的原则：stream.values 可以暴露您的智能体定义的任何自定义状态，而不仅仅是消息。todos 数组只是一个例子。您可以使用相同的方法来：

进度指标：stream.values.progress 包含数字完成数据
生成的工件：stream.values.document 包含智能体正在构建的结构化文档
决策日志：stream.values.decisions 跟踪智能体做出的每个选择
资源列表：stream.values.sources 包含智能体找到的链接和参考

// 您的智能体定义的任何自定义状态键都可以访问
const document = stream.values?.document;
const sources = stream.values?.sources ?? [];
const confidence = stream.values?.confidence_score;

自定义状态键在您的 LangGraph 图的状态模式中定义。useStream 钩子自动将它们包含在 stream.values 中，无需任何额外的客户端配置。

动画过渡

待办状态转换实时发生，平滑的动画使这些变化感觉精致而非突兀：

function TodoItem({ todo }: { todo: Todo }) {
  return (
    <li
      className={`
        flex items-start gap-3 rounded-md border px-3 py-2
        transition-all duration-300 ease-in-out
        ${getStatusStyles(todo.status)}
      `}
    >
      <span
        className={`
          mt-0.5 text-lg leading-none transition-colors duration-300
          ${getIconStyles(todo.status)}
        `}
      >
        {getStatusIcon(todo.status)}
      </span>
      <span
        className={`
          text-sm transition-all duration-300
          ${todo.status === "completed" ? "line-through opacity-60" : ""}
        `}
      >
        {todo.content}
      </span>
    </li>
  );
}

transition-all duration-300 类确保颜色变化、删除线和不透明度变化都平滑动画过渡。

使用场景

待办列表模式适用于智能体执行结构化计划的任何场景：

项目规划：智能体将项目分解为任务并依次处理
研究工作流：每个研究问题成为智能体调查并完成的待办事项
数据处理：摄取、验证、转换和导出等步骤各自获得待办事项
入职流程：智能体逐步完成设置步骤，配置服务时逐一勾选
报告生成：报告的各部分成为待办事项：收集数据、分析趋势、撰写摘要、格式化输出

处理空状态和加载状态

处理智能体创建计划前的初始状态：

function TodoList({ todos, isLoading }: { todos: Todo[]; isLoading: boolean }) {
  if (todos.length === 0 && !isLoading) {
    return null;
  }

  if (todos.length === 0 && isLoading) {
    return (
      <div className="rounded-lg border bg-white p-4 shadow-sm">
        <div className="flex items-center gap-2 text-sm text-gray-500">
          <span className="animate-spin">⟳</span>
          智能体正在创建计划...
        </div>
      </div>
    );
  }

  return (
    <div className="rounded-lg border bg-white p-4 shadow-sm">
      {/* ... 完整的待办列表渲染 */}
    </div>
  );
}

最佳实践

醒目地显示待办列表。它是基于计划的智能体的主要进度指示器。不要将其埋在页面下方。
为状态转换添加动画。平滑的过渡使智能体感觉更响应。在背景颜色、文本装饰和不透明度上使用 CSS 过渡。
只高亮一个 in_progress 项目。智能体通常一次只处理一个任务。如果多个项目显示为 in_progress，UI 会变得嘈杂。考虑只让第一个项目有脉冲效果。
折叠或淡化已完成的项目。随着列表增长，已完成的项目变得不那么相关。降低其视觉权重，让用户专注于仍在进行的事项。
显示进度百分比。一个简单的数字如”67% 已完成”是立即可理解的，即使从房间另一头看。
保持待办列表同步。因为 stream.values 响应式更新，待办列表自动保持最新。不要添加手动轮询或刷新逻辑。

通过 MCP 连接这些文档到 Claude、VSCode 等以获取实时解答。

在 GitHub 上编辑此页面或提交 issue。

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

工作原理

设置 useStream

Todo 接口

构建 TodoList 组件

进度条

单个待办项目

计算进度

与聊天消息结合

超越 todos 的自定义状态

动画过渡

使用场景

处理空状态和加载状态

最佳实践

​工作原理

​设置 useStream

​Todo 接口

​构建 TodoList 组件

​进度条

​单个待办项目

​计算进度

​与聊天消息结合

​超越 todos 的自定义状态

​动画过渡

​使用场景

​处理空状态和加载状态

​最佳实践

工作原理

设置 useStream

Todo 接口

构建 TodoList 组件

进度条

单个待办项目

计算进度

与聊天消息结合

超越 todos 的自定义状态

动画过渡

使用场景

处理空状态和加载状态

最佳实践