子代理流式传输

当协调器 Agent 生成专门的子代理（研究者、分析师、作家）时，您需要将协调器的消息与每个子代理的流式传输输出分开呈现。在 useStream 中设置 filterSubagentMessages: true 可以干净地分离这两个流，然后使用 getSubagentsByMessage 将每个子代理的进度卡片附加到触发它的协调器消息上。

为什么过滤子代理消息

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

stream.messages 仅包含协调器的消息
每个子代理的内容可以通过 stream.subagents 和 stream.getSubagentsByMessage 访问
UI 保持整洁：协调器的推理与专家的工作分开

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

设置 useStream

始终设置 filterSubagentMessages: true。这会将子代理 token 从主消息流中移除，以便您独立渲染协调器的消息和子代理输出。定义一个与 Agent 状态模式匹配的 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>
  );
}

使用子图流式传输提交

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

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>
  );
}

渲染带有子代理卡片的 messages

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

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 ? "s" : ""}...
    </div>
  );
}

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

调试未过滤的输出

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

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

为什么过滤子代理消息

设置 useStream

使用子图流式传输提交

SubagentStreamInterface

将子代理链接到消息

构建 SubagentCard

状态图标和徽章

进度跟踪

渲染带有子代理卡片的 messages

合成指示器

调试未过滤的输出

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

​为什么过滤子代理消息

​设置 useStream

​使用子图流式传输提交

​SubagentStreamInterface

​将子代理链接到消息

​构建 SubagentCard

​状态图标和徽章

​进度跟踪

​渲染带有子代理卡片的 messages

​合成指示器

​调试未过滤的输出

为什么过滤子代理消息

设置 useStream

使用子图流式传输提交

SubagentStreamInterface

将子代理链接到消息

构建 SubagentCard

状态图标和徽章

进度跟踪

渲染带有子代理卡片的 messages

合成指示器

调试未过滤的输出