子代理流式处理

当协调代理生成专业子代理（如研究员、分析师、撰稿人）时，你需要将协调器的消息与每个子代理的流式输出分开渲染。在 useStream 中设置 filterSubagentMessages: true 以清晰分离这两个流，然后使用 getSubagentsByMessage 将每个子代理的进度卡片附加到触发它的协调器消息上。

为何过滤子代理消息

如果不进行过滤，每个子代理生成的每个令牌都会交错出现在协调器的消息流中，导致内容难以阅读。使用 filterSubagentMessages: true 后：

stream.messages 仅包含协调器的消息
每个子代理的内容可通过 stream.subagents 和 stream.getSubagentsByMessage 访问
界面保持清晰：协调器的推理过程与专家的工作内容分离

这种分离让你可以在一个位置渲染协调器的消息，并将每个子代理的进度卡片精确地附加到其所属位置：即生成它的协调器消息下方。

设置 useStream

始终设置 filterSubagentMessages: true。这会从主消息流中移除子代理令牌，以便你可以独立渲染协调器的消息和子代理输出。定义一个与你的代理状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以便类型安全地访问状态值。在下面的示例中，将 typeof myAgent 替换为你的接口名称：

import type { BaseMessage } from "@langchain/core/messages";

interface AgentState {
  messages: BaseMessage[];
}

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

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

export function DeepAgentChat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "deep_agent_subagent_cards",
    filterSubagentMessages: true,
  });

  return (
    <div>
      {stream.messages.map((msg) => (
        <MessageWithSubagents
          key={msg.id}
          message={msg}
          subagents={stream.getSubagentsByMessage(msg.id)}
        />
      ))}
    </div>
  );
}

提交消息并启用子图流式处理

提交消息时，启用子图流式处理并设置适当的递归限制。深度代理工作流通常涉及多层嵌套子图，因此较高的递归限制可防止过早终止：

stream.submit(
  { messages: [{ type: "human", content: text }] },
  { streamSubgraphs: true }
);

DeepAgents 默认的递归限制为 10,000，这对于大多数多专家设置已足够。如有需要，可通过 config.recursion_limit 覆盖此设置。

SubagentStreamInterface 接口

每个子代理都暴露一个 SubagentStreamInterface，其中包含有关子代理任务、状态和时间的元数据：

interface SubagentStreamInterface {
  id: string;
  status: "pending" | "running" | "complete" | "error";
  messages: BaseMessage[];
  result: string | undefined;
  toolCall: {
    id: string;
    name: string;
    args: {
      description: string;
      subagent_type: string;
      [key: string]: unknown;
    };
  };
  startedAt: number | undefined;
  completedAt: number | undefined;
}

属性	描述
`id`	此子代理实例的唯一标识符
`status`	生命周期状态：`pending` → `running` → `complete` 或 `error`
`messages`	子代理自身的消息流，实时更新
`result`	最终输出文本，仅在 `status` 为 `"complete"` 时可用
`toolCall`	生成此子代理的工具调用，包括任务元数据
`toolCall.args.description`	协调器分配给此子代理的任务描述
`toolCall.args.subagent_type`	专家的类型或名称（例如 `"researcher"`、`"analyst"`）
`startedAt`	子代理开始执行的时间戳
`completedAt`	子代理完成的时间戳

将子代理链接到消息

getSubagentsByMessage 方法返回由特定 AI 消息生成的子代理。这使你可以将子代理卡片直接渲染在触发它们的协调器消息下方：

const turnSubagents = stream.getSubagentsByMessage(msg.id);

此方法返回一个 SubagentStreamInterface 对象数组。如果该消息未生成任何子代理，则返回空数组。

构建 SubagentCard 组件

每个子代理卡片显示专家的名称、任务描述、流式内容或最终结果以及时间信息：

import { AIMessage } from "@langchain/core/messages";

function SubagentCard({
  subagent,
}: {
  subagent: SubagentStreamInterface;
}) {
  const [expanded, setExpanded] = useState(true);

  const title =
    subagent.toolCall?.args?.subagent_type ?? `Agent ${subagent.id}`;
  const description = subagent.toolCall?.args?.description ?? "";

  const lastAIMessage = subagent.messages
    .filter(AIMessage.isInstance)
    .at(-1);

  const displayContent =
    subagent.status === "complete"
      ? subagent.result
      : typeof lastAIMessage?.content === "string"
        ? lastAIMessage.content
        : "";

  const elapsed = getElapsedTime(subagent.startedAt, subagent.completedAt);

  return (
    <div className="rounded-lg border bg-white shadow-sm">
      <button
        onClick={() => setExpanded(!expanded)}
        className="flex w-full items-center justify-between p-4"
      >
        <div className="flex items-center gap-3">
          <StatusIcon status={subagent.status} />
          <div>
            <h4 className="font-semibold capitalize">{title}</h4>
            <p className="text-xs text-gray-500">{description}</p>
          </div>
        </div>
        <div className="flex items-center gap-2">
          {elapsed && (
            <span className="text-xs text-gray-400">{elapsed}</span>
          )}
          <StatusBadge status={subagent.status} />
        </div>
      </button>

      {expanded && displayContent && (
        <div className="border-t px-4 py-3">
          <div className="prose prose-sm max-w-none line-clamp-6">
            {displayContent}
            {subagent.status === "running" && (
              <span className="inline-block h-4 w-1 animate-pulse bg-blue-500" />
            )}
          </div>
        </div>
      )}
    </div>
  );
}

function getElapsedTime(
  startedAt: number | undefined,
  completedAt: number | undefined
): string | null {
  if (!startedAt) return null;
  const end = completedAt ?? Date.now();
  const seconds = Math.round((end - startedAt) / 1000);
  if (seconds < 60) return `${seconds}s`;
  return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
}

状态图标和徽章

一致的视觉指示器帮助用户一目了然地解析子代理状态：

function StatusIcon({ status }: { status: SubagentStreamInterface["status"] }) {
  switch (status) {
    case "pending":
      return <span className="text-gray-400">○</span>;
    case "running":
      return <span className="animate-spin text-blue-500">◉</span>;
    case "complete":
      return <span className="text-green-500">✓</span>;
    case "error":
      return <span className="text-red-500">✕</span>;
  }
}

function StatusBadge({ status }: { status: SubagentStreamInterface["status"] }) {
  const styles = {
    pending: "bg-gray-100 text-gray-600",
    running: "bg-blue-100 text-blue-700",
    complete: "bg-green-100 text-green-700",
    error: "bg-red-100 text-red-700",
  };

  return (
    <span className={`rounded-full px-2 py-0.5 text-xs font-medium ${styles[status]}`}>
      {status}
    </span>
  );
}

进度跟踪

显示进度条和计数器，让用户知道有多少子代理已完成：

function SubagentProgress({
  subagents,
}: {
  subagents: SubagentStreamInterface[];
}) {
  const completed = subagents.filter((s) => s.status === "complete").length;
  const total = subagents.length;
  const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;

  return (
    <div className="space-y-1">
      <div className="flex items-center justify-between text-xs text-gray-500">
        <span>子代理进度</span>
        <span>
          {completed}/{total} 完成
        </span>
      </div>
      <div className="h-2 overflow-hidden rounded-full bg-gray-200">
        <div
          className="h-full rounded-full bg-blue-500 transition-all duration-300"
          style={{ width: `${percentage}%` }}
        />
      </div>
    </div>
  );
}

渲染带有子代理卡片的消息

关键布局模式是渲染每个协调器消息，如果该消息生成了子代理，则立即在其下方渲染它们的卡片：

function MessageWithSubagents({
  message,
  subagents,
}: {
  message: BaseMessage;
  subagents: SubagentStreamInterface[];
}) {
  if (message.type === "human") {
    return <HumanMessage content={message.content} />;
  }

  return (
    <div className="space-y-3">
      {message.content && (
        <div className="prose prose-sm max-w-none">
          {message.content}
        </div>
      )}

      {subagents.length > 0 && (
        <div className="ml-4 space-y-3 border-l-2 border-blue-200 pl-4">
          <SubagentProgress subagents={subagents} />
          {subagents.map((subagent) => (
            <SubagentCard key={subagent.id} subagent={subagent} />
          ))}
        </div>
      )}
    </div>
  );
}

合成指示器

所有子代理完成后，协调器需要时间将结果合成为最终响应。在此阶段显示清晰的指示器：

function SynthesisIndicator({
  subagents,
  isLoading,
}: {
  subagents: SubagentStreamInterface[];
  isLoading: boolean;
}) {
  const allComplete =
    subagents.length > 0 &&
    subagents.every((s) => s.status === "complete" || s.status === "error");

  if (!allComplete || !isLoading) return null;

  return (
    <div className="flex items-center gap-2 rounded-lg bg-purple-50 px-4 py-2 text-sm text-purple-700">
      <span className="animate-spin">⟳</span>
      正在从 {subagents.length} 个子代理合成结果{subagents.length !== 1 ? "们" : ""}...
    </div>
  );
}

对于复杂的多专家工作流，合成阶段可能需要几秒钟。清晰的“正在合成结果…”指示器可以防止用户误以为代理已停滞。

调试未过滤的输出

在开发过程中，你可以临时设置 filterSubagentMessages: false，以在主消息流中查看所有子代理的原始交错输出。这对于验证子代理令牌是否正确流动很有用，但不应在生产 UI 中使用。

使用场景

深度代理子代理卡片适用于以下代理工作流场景：

深度研究：协调器派遣研究员调查问题的不同方面，然后综合他们的发现
多专家分析：例如领域专家（法律、金融、技术）各自贡献其观点
复杂任务分解：规划器将大型任务分解为子任务，并将每个子任务分配给专业工作者
代码审查流水线：单独的代理处理安全审查、风格检查、性能分析和文档审查

访问完整的子代理映射

除了按消息查找外，你还可以通过 stream.subagents 一次性访问所有子代理：

const allSubagents = [...stream.subagents.values()];
const running = allSubagents.filter((s) => s.status === "running");
const completed = allSubagents.filter((s) => s.status === "complete");
const errors = allSubagents.filter((s) => s.status === "error");

这对于构建全局进度指示器或仪表板非常有用，这些仪表板汇总所有子代理活动，而不考虑是哪个协调器消息生成的。

最佳实践

始终设置 filterSubagentMessages: true。未过滤的流会产生协调器和子代理令牌难以阅读的交错。
显示任务描述。toolCall.args.description 字段告诉用户每个子代理被要求执行的确切任务。始终突出显示此信息。
使用可折叠卡片。在包含 5 个以上子代理的工作流中，自动折叠已完成的卡片，以便用户可以专注于正在进行的工作。
显示时间数据。显示每个子代理花费的时间有助于用户理解性能特征并识别瓶颈。
设置适当的递归限制。具有嵌套子图的深度代理工作流需要比默认值 25 更高的限制。建议从 100 开始。
按子代理处理错误。一个子代理失败不应导致整个 UI 崩溃。在该子代理的卡片中显示错误，同时其他子代理继续运行。

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

为何过滤子代理消息

设置 useStream

提交消息并启用子图流式处理

SubagentStreamInterface 接口

将子代理链接到消息

构建 SubagentCard 组件

状态图标和徽章

进度跟踪

渲染带有子代理卡片的消息

合成指示器

调试未过滤的输出

使用场景

访问完整的子代理映射

最佳实践

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

​为何过滤子代理消息

​设置 useStream

​提交消息并启用子图流式处理

​SubagentStreamInterface 接口

​将子代理链接到消息

​构建 SubagentCard 组件

​状态图标和徽章

​进度跟踪

​渲染带有子代理卡片的消息

​合成指示器

​调试未过滤的输出

​使用场景

​访问完整的子代理映射

​最佳实践

为何过滤子代理消息

设置 useStream

提交消息并启用子图流式处理

SubagentStreamInterface 接口

将子代理链接到消息

构建 SubagentCard 组件

状态图标和徽章

进度跟踪

渲染带有子代理卡片的消息

合成指示器

调试未过滤的输出

使用场景

访问完整的子代理映射

最佳实践