OpenMAIC 源码全解析：多智能体协作与交互通信（CopilotKit 实战）

在线教育正在经历从"看视频（MOOC）"到"AI 陪练（AI-native）"的范式转移。清华大学团队近期开源的 OpenMAIC（Open Multi-Agent Interactive Classroom，开放式多智能体交互课堂）正是这场变革的急先锋。它不仅能将任意长文本或主题一键转化为包含幻灯片、测验和 HTML 动态模拟实验的完整课程，更创造性地引入了由 AI 讲师、助教及"显眼包"同学组成的多智能体虚拟教室。

作为开发者，OpenMAIC 最吸引人的地方在于其底层精妙的多智能体状态机编排 以及前端流畅的交互通信机制。

本文将深入拆解 OpenMAIC 的源码架构，剖析其如何利用 LangGraph 进行多角色协同，并展示如何结合 CopilotKit 赋予这个虚拟课堂更强的实时交互与副驾驶（Copilot）能力。

核心架构：两阶段流式生成管线

OpenMAIC 基于 Next.js 16 + React 19 + TypeScript 5 构建，其内容生成逻辑并没有选择让 LLM 一气呵成，而是采用了典型的两阶段管线（Two-Stage Pipeline）设计，以确保课程的结构化与严谨性：

复制代码

[ 输入主题/文档 ] 
       │
       ▼
 ┌───────────┐
 │   Stage 1 │ ──> 大模型分析受众与大纲 (Outline)
 └───────────┘
       │
       ▼
 ┌───────────┐
 │   Stage 2 │ ──> 动态生成多模态教学场景 (Scenes: 幻灯片/代码/动画)
 └───────────┘

为了让这套复杂的管线在多角色之间流畅流转，OpenMAIC 底层使用了 LangGraph 1.1 来作为状态机的编排核心。

源码探秘：LangGraph 驱动的多智能体协作

打开 OpenMAIC 的后端核心代码（通常位于 core/agents/ 或通过 server-providers.yml 进行多模型路由），你会发现它定义了 28+ 种原子动作类型（Action Types），涵盖了语音播报、白板联动、随堂测试等。

其多智能体状态机的流转机制可以抽象为以下代码逻辑：

复制代码

// 伪代码：OpenMAIC 多智能体状态机定义
import { StateGraph, END } from "@langchain/langgraph";

// 定义课堂状态结构
interface ClassroomState {
  currentScene: number;
  whiteboardData: any[];
  chatHistory: Message[];
  activeAgent: "teacher" | "assistant" | "student_clown" | "deep_thinker";
}

const classroomWorkflow = new StateGraph<ClassroomState>({
  channels: { /* 状态通道初始化 */ }
})
  // 1. 讲师授课节点
  .addNode("teacher_agent", async (state) => {
    // 负责讲解 PPT，实时往白板写公式
    const output = await callLLM({ role: "Teacher", context: state });
    return { 
      chatHistory: [...state.chatHistory, output.message],
      whiteboardData: [...state.whiteboardData, output.drawings]
    };
  })
  // 2. 活跃学生/显眼包互动节点
  .addNode("clown_agent", async (state) => {
    // 负责提出趣味性问题或插科打诨，打破沉闷气氛
    const jokeOrQuestion = await callLLM({ role: "ClassClown", context: state });
    return { chatHistory: [...state.chatHistory, jokeOrQuestion] };
  })
  // 3. 动态路由控制
  .addConditionalEdges("teacher_agent", (state) => {
    if (state.currentScene % 3 === 0) return "clown_agent"; // 每讲3个场景，学生插话
    return END;
  });

四大核心 AI 角色分工

Teacher Agent（主讲老师）： 负责课程主线推进，配合 VoxCPM2 语音库进行 TTS 语音合成，同时利用激光笔、聚光灯组件在白板上绘制概念图。
Teaching Assistant（助教）： 管理随堂测试，收集用户交互反馈并给出情感支持。
Class Clown（活跃气氛组/显眼包）： 触发新观点，降低认知疲劳。
Deep Thinker（深度思考者）： 专门提出硬核质疑，拓展知识边界。

实战进阶：引入 CopilotKit 接管多智能体通信

虽然 OpenMAIC 本身自带了完备的课件播放引擎（Idle -> Playing -> Live 状态切换），但如果我们想在前端提供一个"全局教学副驾驶（Copilot）"，让用户能随时通过对话打断课堂、控制进度、甚至命令 AI 老师"在白板上画个二叉树"，该怎么做？

这时候，全栈 AI 交互框架 CopilotKit 就派上用场了。我们可以利用 CopilotKit 的 useCopilotReadable 和 useCopilotAction 钩子，将 OpenMAIC 的内部状态暴露给前端副驾驶，并赋予其反向控制多智能体系统的能力。

1. 状态共享：让 Copilot 随时看懂课堂进度

在 OpenMAIC 的课堂主页面组件中，我们注入 useCopilotReadable：

复制代码

import { useCopilotReadable } from "@copilotkit/react-core";

export function ClassroomConsole({ currentScene, messages, whiteboardContent }) {
  // 将 OpenMAIC 当前的多智能体课堂上下文实时同步给 Copilot 视图
  useCopilotReadable({
    description: "当前虚拟课堂的实时状态，包括课件进度和白板内容",
    value: {
      currentSceneId: currentScene.id,
      sceneTitle: currentScene.title,
      lastTeacherWords: messages.filter(m => m.role === 'teacher').pop()?.text,
      hasActiveQuiz: currentScene.type === 'quiz'
    }
  });

  return (
    <div className="classroom-layout">
      {/* 渲染白板、PPT与聊天框 */}
    </div>
  );
}

2. 行为绑定：通过 Copilot 操控 AI 智能体

接下来，我们注册一个 Copilot Action，允许用户直接向副驾驶发指令，由副驾驶越权向状态机注入新节点或更改当前状态（例如：切换 PPT、重答测验）：

复制代码

import { useCopilotAction } from "@copilotkit/react-core";

export function ClassroomControls({ jumpToScene, appendAgentMessage }) {
  
  // 注册切换课件的 Action
  useCopilotAction({
    name: "changeLessonScene",
    description: "跳转到指定的课程章节或幻灯片页码",
    parameters: [
      {
        name: "sceneNumber",
        type: "number",
        description: "目标页码或章节索引",
        required: true,
      },
    ],
    handler: async ({ sceneNumber }) => {
      jumpToScene(sceneNumber);
    },
  });

  // 注册一个"插话/提问"的 Action
  useCopilotAction({
    name: "injectStudentQuestion",
    description: "替学生向 AI 讲师发起追问，并触发 roundtable（圆桌讨论）",
    parameters: [
      {
        name: "questionText",
        type: "string",
        description: "具体的提问内容",
        required: true,
      }
    ],
    handler: async ({ questionText }) => {
      appendAgentMessage({
        role: "user_surrogate",
        text: questionText,
        triggerAgentRoundtable: true // 激活 LangGraph 中的多方辩论流
      });
    }
  });
}

通过将 CopilotKit 的 Action 桥接到 OpenMAIC 内部的 Playback 引擎，用户的聊天输入框直接变成了课堂的"最高指挥所"。你不需要去点界面上繁琐的按钮，只需要对副驾驶说："我没听懂刚才关于 Bloom 认知分类法的解释，让 Deep Thinker 帮我用大白话考考我。" CopilotKit 就会立刻识别意图，调用相应的 Action 修改 Next.js 状态，进而驱动后端的 LangGraph 状态机调整行为。

总结与启示

清华团队的 OpenMAIC 完美示范了"LLM 编排核心化（LangGraph）+ 前端多模态呈现（Next.js/React）"的现代 AI 应用范式。通过结合 CopilotKit，我们更进一步地将原有的"主从式（用户看 AI 演戏）"课堂，改造成了"协同式（用户、副驾驶、多智能体融为一体）"的全新体验。