前端概览

为什么需要它

你有没有试过在前端展示 Deep Agent 的工作过程？

文档索引

获取完整的文档索引，发现所有可用页面

协调者-工作者

Deep Agent 采用 coordinator-worker 架构——主 Agent 规划，子 Agent 执行

说白了，协调者负责拆任务，工作者负责干活。在前端，useStream 同时展示协调者的消息和每个子 Agent 的流式状态。

创建 Deep Agent

后端只需一行 createDeepAgent，即可启用子 Agent 机制

创建方式与普通 Agent 类似，但多了一个 subagents 配置项，用于声明可用的子 Agent 类型。

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  tools: [getWeather],          // 主 Agent 可用的工具列表
  systemPrompt: "You are a helpful assistant",  // 主 Agent 的系统指令
  subagents: [
    {
      name: "researcher",       // 子 Agent 类型名称
      description: "Research assistant",  // 描述什么任务应该委派给它
    },
  ],
});

连接前端

使用 useStream 连接后端，获取完整的 Deep Agent 状态

前端用 useStream 与后端通信，方式和 createAgent 完全一致。但 Deep Agent 提供了额外的状态属性。

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

function App() {
  const stream = useStream(typeof agent === "undefined" ? {} : {
    apiUrl: "http://localhost:2024",   // LangGraph Server 地址
    assistantId: "agent",              // Agent 的唯一标识
  });

  // Deep Agent 特有状态（普通 Agent 没有）
  const todos = stream.values?.todos;       // 待办任务列表，由 write_todos 工具驱动
  const subagents = stream.subagents;       // 所有子 Agent 的实时状态 Map

  return (
    <div>
      {/* 渲染协调者消息 */}
      {stream.messages.map(msg => <Message key={msg.id} data={msg} />)}

      {/* 渲染子 Agent 卡片 */}
      {subagents?.map(sub => <SubagentCard key={sub.id} data={sub} />)}

      {/* 渲染待办列表 */}
      {todos && <TodoList items={todos} />}
    </div>
  );
}

子 Agent 流式

实时展示每个子 Agent 的执行内容、进度和结果

当协调者委派任务给子 Agent 时，stream.subagents 会实时更新。每个子 Agent 包含名称、状态和流式输出内容。

// 子 Agent 状态结构示例
const subagent = {
  id: "sub_001",
  name: "researcher",          // 子 Agent 类型名称
  status: "running",           // running | completed | error
  taskId: "task_003",          // 关联的任务 ID
  messages: [                  // 该子 Agent 的流式消息
    { role: "assistant", content: "正在搜索相关文档..." },
    { role: "assistant", content: "找到 3 篇相关论文，正在分析..." },
  ],
};

待办列表

通过与 Agent 状态同步的实时待办列表跟踪任务进度

协调者使用内置的 write_todos 工具来规划任务。前端通过 stream.values.todos 获取这些待办事项并实时渲染。

// 待办列表数据结构示例
const todos = [
  { id: "todo_1", content: "搜索用户相关资料", status: "completed" },
  { id: "todo_2", content: "分析搜索结果并整理要点", status: "in_progress" },
  { id: "todo_3", content: "编写最终报告", status: "pending" },
];

// 在 React 组件中渲染
// 渲染待办列表，状态驱动图标
function TodoList({ items }) {
  return (
    <div className="todo-list">
      <h3>任务规划</h3>
      {items.map(todo => (
        <div key={todo.id} className={`todo-item ${todo.status}`}>
          {todo.status === "completed" && <span>✓</span>}
          {todo.status === "in_progress" && <span>⟳</span>}
          {todo.status === "pending" && <span>○</span>}
          <span>{todo.content}</span>
        </div>
      ))}
    </div>
  );
}

沙箱模式

构建类 IDE 的 UI，包含文件浏览器、代码查看器和差异面板

当子 Agent 在沙箱中执行代码时，前端可以渲染一个完整的 IDE 体验，让用户看到文件变更和代码差异。

// 文件树数据结构
const fileTree = [
  { type: "dir", name: "src",
    children: [
      { type: "file", name: "index.ts" },
      { type: "file", name: "utils.ts" },
    ]
  },
  { type: "file", name: "package.json" },
];

// 差异数据结构
const diff = {
  file: "src/index.ts",
  changes: [
    { type: "add", line: 5,
      content: "import { serve } from './server';" },
    { type: "remove", line: 3,
      content: "const port = 3000;" },
  ],
};

消息过滤

使用 filterSubagentMessages 选项自动隔离各子 Agent 的消息

在复杂场景中，协调者和多个子 Agent 的消息混合在一起。在 useStream 配置中开启 filterSubagentMessages: true，stream.messages 就会自动按子 Agent 过滤，实现消息隔离渲染。

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

function SubagentPanel({ subagentId }) {
  const stream = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    filterSubagentMessages: true,  // 自动按子 Agent 隔离消息
  });

  // stream.messages 已自动按当前子 Agent 过滤
  const messages = stream.messages;

  return (
    <div className="subagent-panel">
      {messages.map(msg => (
        <div key={msg.id} className="message">
          {msg.content}
        </div>
      ))}
    </div>
  );
}

完整示例

把所有前端模式组合起来——消息 + 子 Agent + 待办 + 沙箱

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

// 1. 后端创建 Deep Agent
const agent = createDeepAgent({
  tools: [searchTool, codeTool],  // 主 Agent 可用的工具
  subagents: [
    { name: "researcher", description: "搜索和分析" },
    { name: "coder", description: "编写和执行代码" },
  ],
});

// 2. 前端组件：通过 useStream 获取 Deep Agent 的完整状态
function DeepAgentUI() {
  const stream = useStream({
    apiUrl: "http://localhost:2024",
    assistantId: "agent",
    filterSubagentMessages: true,  // 自动按子 Agent 隔离消息
  });

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

  return (
    <div className="deep-agent-ui">
      {/* 主消息区 */}
      <ChatPanel messages={stream.messages} />

      {/* 子 Agent 卡片区 */}
      {subagents.map(sub => (
        <SubagentCard key={sub.id} subagent={sub}
          messages={stream.messages}
        />
      ))}

      {/* 待办列表侧边栏 */}
      {todos && <TodoListSidebar items={todos} />}
    </div>
  );
}

三大模式总览

Deep Agent 前端提供三个核心模式，覆盖从简单到复杂的所有场景

生态兼容性

Deep Agent 构建在 LangGraph 运行时之上，与 LangChain 前端模式完全兼容

LangChain 前端模式——包括 Markdown 消息渲染、工具调用展示、人在回路（Human-in-the-Loop）——同样适用于 Deep Agent。

// useStream 的核心 API 对比
// LangChain 模式                    // Deep Agent 扩展
stream.messages                  → stream.subagents
stream.values                    → stream.values.todos
stream.submit(input)             → filterSubagentMessages: true（配置选项）

动手练习

构建一个最小化的 Deep Agent 前端

现在轮到你了。停下来，用刚学的知识构建一个最小可用的 Deep Agent 前端界面。

// 练习目标：
// 1. 创建一个 Deep Agent（后端）
// 2. 用 useStream 连接它（前端）
// 3. 渲染协调者消息
// 4. 渲染子 Agent 卡片（可折叠）
// 5. 渲染待办列表（显示任务进度）

// 后端模板
import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  tools: [],                      // 添加你的工具
  subagents: [
    { name: "helper", description: "通用助手" },
  ],
});

本章回顾

到这里，你已经掌握了 Deep Agent 前端的全貌

延伸阅读