简介：本文围绕对话式 Agent 的工程落地，提出“统一消息模型 + 运行时适配 + 前端编排”的三段式解耦方案。读者将掌握如何让前端与任意流式后端解耦，统一处理工具调用、回合循环与事件流，并为历史回放、检查点与评测预留扩展接口，从而用一套可组合能力支撑笔记、知识库、项目管理等多业务场景。

agent-">Agent 框架选型与前端编排实践：构建可组合的对话式智能能力

在构建面向多业务场景的对话式 AI 能力时，团队往往会面临一个共性难题：不同业务线（如笔记、知识库、项目管理）都需要对话式交互，但各自的技术栈、后端实现和交互诉求又不尽相同。如果每条业务线都重复造轮子，不仅开发成本高，后续的维护和演进也会变得异常困难。本文将围绕“统一消息模型 + 运行时适配 + 前端编排”的三段式架构，探讨如何构建一套可组合、可扩展的 Agent 能力底座，并以一期“对话模式”落地为例，展开具体的工程设计思路。

一、业务诉求与设计目标

在讨论具体技术方案之前，有必要先厘清业务侧的核心诉求。以笔记、知识库、项目管理三类场景为例，它们对 AI 能力的需求可以归纳为以下几点：

对话式交互是基础：三类场景都需要“对话式”AI 能力，用户通过自然语言与系统交互，获取信息或完成任务。
能力逐步演进：从单轮问答起步，逐步演进到多轮对话、工具调用、上下文增强，最终实现可追溯、可回放的完整 Agent 能力。
统一入口，避免重复建设：不希望每条业务线各自实现一套对话逻辑，而是期待用同一套可组合的 Hook 即插即用。
一期范围可控：先完成对话模式打底，但保留“多消息一回合”“工具调用”“历史/检查点”等能力的扩展接口。

这些诉求指向一个核心设计原则：将复杂性解耦，让每一层只关心自己的职责。具体来说，就是将整体架构拆分为消息模型、运行时适配和前端编排三个部分，分别解决“数据如何表达”“事件如何流转”“交互如何组织”三个问题。

二、三段式架构设计

2.1 消息即协议：统一消息模型

在多业务、多后端的场景下，前端最忌讳的就是直接消费后端返回的原始事件。不同后端可能采用不同的流式协议（SSE、WebSocket、Fetch ReadableStream 等），返回的事件结构也千差万别。如果前端直接依赖这些原始结构，一旦后端调整协议，前端就要跟着大改。

因此，第一步是定义一套统一消息模型，将后端回传的事件统一解码为前端可消费的消息结构。UI 只消费消息，不关心消息来源的细节。核心消息类型包括：

UserMessage：用户输入的消息。
AssistantMessage：助手回复的消息。
ThinkingMessage：模型的思考过程（如推理链）。
ActionExecutionMessage：工具调用或动作执行的消息。
ResultMessage：工具执行结果或最终结果消息。

每条消息都包含 status 字段（如 pending、streaming、completed、error）以及可选的 parentMessageId，用于表达消息之间的父子关系，从而支持多消息一回合的复杂场景。模型本身是可扩展的，后续可以方便地加入图片消息、状态消息等类型。

interface BaseMessage {
  id: string;
  role: 'user' | 'assistant' | 'system';
  status: 'pending' | 'streaming' | 'completed' | 'error';
  parentMessageId?: string;
  createdAt: number;
}
interface AssistantMessage extends BaseMessage {
  role: 'assistant';
  content: string;
  thinking?: string;
  actions?: ActionExecutionMessage[];
}

统一消息模型的价值在于：它为前端提供了一个稳定的契约。无论后端如何变化，只要 Adapter 能将事件转换为这套模型，前端逻辑就无需改动。

2.2 运行时可插拔：Runtime Adapter

有了统一消息模型，下一步就是解决“如何将任意后端的流式输出转换为标准消息”的问题。这就是 Runtime Adapter 的职责。

Adapter 的核心设计原则是协议无关、面向任意后端流。只要后端能够以流的形式输出事件，无论采用的是 SSE、GraphQL 订阅、WebSocket 还是 Fetch ReadableStream，Adapter 都可以将其转换为统一的 AgentStreamEvent，前端逻辑零差异。

Adapter 对外暴露的核心接口包括：

generateResponse(params)：发起一次对话请求，返回 ReadableStream<AgentStreamEvent>。
retry(params)：对某次请求进行重试或生成变体。
sendFeedback(params)：统一提交正/负反馈，用于后续的评测与优化。

interface RuntimeAdapter {
  generateResponse(params: GenerateParams): ReadableStream<AgentStreamEvent>;
  retry(params: RetryParams): ReadableStream<AgentStreamEvent>;
  sendFeedback(params: FeedbackParams): Promise<void>;
}

这种设计的优势在于：前端编排层完全不需要感知后端协议。当需要切换或新增后端时，只需实现一个新的 Adapter，前端代码无需任何修改。同时，Adapter 层也为后续的多后端混合调度、灰度切换等能力留下了空间。

2.3 前端可编排：Hook 与 Context 胶水层

消息模型和 Adapter 解决了数据与协议的问题，但前端还需要一个稳定的胶水层来管理上下文、工具、重试/变体、回调等交互逻辑。这一层通过 Hook 和 Context 来实现，形成可复用的编排能力。

核心编排职责包括：

上下文管理：维护当前会话的消息列表、threadId、runId 等状态。
工具注册与调用：管理可用的工具集合，并在消息流中识别和处理工具调用事件。
重试与变体：支持对某次回复进行重试或生成多个变体供用户选择。
回调与副作用：在消息状态变化时触发相应的回调，如持久化、埋点、通知等。

function useAgentRuntime(adapter: RuntimeAdapter) {
  const [messages, setMessages] = useState<BaseMessage[]>([]);
  const [threadId] = useState(() => generateThreadId());
  const send = useCallback(async (input: string) => {
    const stream = adapter.generateResponse({ input, threadId });
    // 消费流并将事件转换为消息模型
    for await (const event of stream) {
      setMessages(prev => reduceEvent(prev, event));
    }
  }, [adapter, threadId]);
  return { messages, send, retry, sendFeedback };
}

通过这层编排，业务方只需要引入对应的 Hook，就能获得完整的对话式能力，而无需关心底层的消息解码和协议适配。

三、渐进增强：从对话模式到完整 Agent

一期落地聚焦“对话模式”，但架构设计上必须为后续能力预留接口。具体来说：

threadId / runId：在消息模型中预留这两个标识，为后续的历史记录、检查点、回放和评测能力提供基础。threadId 标识一个会话线程，runId 标识一次具体的运行回合。
多消息一回合：通过 parentMessageId 和消息类型扩展，支持一次用户输入触发多个助手消息（如思考、工具调用、结果）的场景。
工具调用：ActionExecutionMessage 和 ResultMessage 的类型定义已经就位，后续只需在编排层增加工具注册和调度的逻辑。
历史与检查点：基于 threadId 和 runId，可以方便地实现会话历史的持久化和断点恢复。

这种渐进增强的策略，使得一期可以快速交付价值，同时不会为后续演进设置障碍。

四、总结

构建可组合的对话式 Agent 能力，关键在于解耦。通过“统一消息模型 + 运行时适配 + 前端编排”的三段式架构，我们实现了：

消息即协议：前端只消费统一消息，不关心后端协议细节。
运行时可插拔：Adapter 屏蔽不同流式协议的差异，前端逻辑零改动。
前端可编排：Hook/Context 提供稳定的胶水层，业务方即插即用。
渐进增强：一期做对话，但为工具调用、历史、检查点、评测预留接口。

这套架构不仅适用于笔记、知识库、项目管理等场景，也可以作为更广泛的对话式 AI 能力的通用底座。在实际落地过程中，建议团队根据自身业务节奏，先跑通对话模式的核心链路，再逐步叠加工具调用、多轮上下文和可追溯能力，最终形成完整的 Agent 能力闭环。

Agent 框架选型与前端编排实践