做教育信息化这几年，我越来越觉得课堂上的AI工具不是太少，而是太散。老师手里捏着两三个对话框，学生那边又用一个答题器，学情数据散落在不同后台里，根本没法串成一条线。所以我动手做了OpenMAIC——一个开源的、面向交互式课堂的多智能体平台。标题里的三个词各有分量：开源意味着所有人都能拿到核心代码自己改；多智能体意味着不是用一个模型统一回答所有问题，而是把助教、批改、讨论、学情分析拆成不同角色的AI单元；交互式课堂则是落地的场景，让AI真正参与课堂节奏，而不是躲在作业后台。这篇文章从设计思路、系统架构到实操部署，完整复盘一下这个平台，适合正在做课堂信息化、AI教研工具，或者单纯对多智能体系统感兴趣的朋友参考。

1. 为什么做OpenMAIC：课堂智能化一直缺一个“编排层”

1.1 传统课堂里AI工具的三大通病

前几年大家聊智慧课堂，核心思路都是"给老师配个AI助手"，但实际落地的产品我接触下来，普遍有三类问题。

第一是工具孤岛。答疑用一个系统，测验用另一个平台，作业批改再开一个账号。每套系统都有自己的学生数据，但这些数据格式不一样、口径不一样，老师想统计"这个班这个月到底哪些知识点掌握得差"，需要手工把三份Excel导出来做透视表。这不是个例，是常态。

第二是交互浅。很多课堂AI产品本质就是个加了点教育话术的聊天机器人，学生问一句AI答一句，答完就没了。它不会主动记录谁在哪个知识点上卡住了，也不会把课堂上的问答沉淀成教学资源，更不会在小组讨论时出来做一个辅助角色。课堂问答产生的数据是金矿，但大多数工具直接把这些数据倒掉了。

第三是角色混乱。一个模型同时干答疑、出题、批改、点评的活，看着全能，其实每个场景都做不深。答疑需要严谨克制，批改需要标准清晰，讨论引导需要发散包容。把这么多性格塞进一个提示词里，结果就是哪个场景都不满意，老师用两次就放弃了。

1.2 OpenMAIC想解决的问题

我当时的产品设计目标很明确：做一个课堂智能化的"编排层"。核心思路是三条。

第一，用智能体分工代替单一模型。每个Agent只负责一个课堂角色，助教就是助教，批改就是批改，各有一份独立的系统提示词、独立的知识库入口、独立的记忆空间。彼此可以通过消息总线交换信息，但职责边界不越线。

第二，让课堂数据自动回流。学生和Agent的每一轮对话、每一次答题、每一份提交的作业，都自动写入持久化层。老师打开学情面板，能直接看到结构化分析，不用自己做数据清洗。

第三，交互不设限。支持课堂实时问答、小组讨论、课后答疑、作业批改、学情报告等场景，全部通过可配置的智能体工作流串联起来。老师可以在课前花两分钟配置好一个"课堂大脑"，课上专心讲课，把重复性工作交给Agent。

这个平台我给真实的合作课堂跑过，也拆出来放到开源社区里给同行改。下面讲的架构和方案，都是实际跑通了的东西，你可以直接照搬思路，也可以当成一个多智能体项目的入门案例来看。

2. OpenMAIC的整体设计拆解：五个模块和一条总线

2.1 前端交互层：课堂不应该是ChatGPT式的一问一答

OpenMAIC的前端不是传统意义上的管理后台，更像一个"课堂控制台"。老师端面板分成三个区：左侧是智能体配置区，中间是实时交互区，右侧是学情动态区。学生端比较轻，一个对话窗口加上一个轻量的答题面板就够了。

我特意没有做成纯聊天界面。原因是课堂场景有它自己的节奏：老师需要快速切换话题、发起投票、查看谁没参与，这些操作在聊天流里做效率太低。所以前端层做成了"卡片式交互"——每个智能体发言都生成结构化卡片，问答卡片带反馈按钮，分析卡片带图表，任务卡片带截止时间。学生看到的不再是一堆气泡消息，而是一张一张清晰的信息卡。

2.2 服务编排层：请求怎么路由给正确的Agent

服务编排是整个平台的中枢，处理四件事：意图识别、智能体路由、上下文组装、结果后处理。

意图识别不是简单的关键词匹配。我试过两种方案，一种是用分类模型直接判断用户问题属于"助教答疑""小组讨论""作业批改"中的哪一类，准确率大概能到85%；另一种是让路由Agent自己判断，利用大模型的工具调用能力选择交给哪个下游Agent。后者胜在灵活，课堂里经常有跨场景问题，比如学生问"这个作业的第三题和上课讲的概念有什么关系"，这种问题直接路由给助教还是批改Agent都尴尬，但路由Agent可以把它拆分成两个子任务分别分发。

上下文组装是个小学问。每个Agent需要的上下文不一样：助教需要本堂课的知识点和一些扩展阅读，批改Agent需要评分标准和优秀范例，学情Agent需要全班历次交互记录。所以编排层不能把所有上下文一股脑塞给所有Agent，否则token账单先爆炸。我做了一个轻量级记忆库，按Agent维度存储会话摘要，请求进来时只拉取相关片段。

2.3 智能体集合：四个默认Agent和自定义接口

平台默认内置四个Agent，也开放自定义接口，让老师或开发者可以注册自己的Agent。四个默认角色的定位是：

自定义Agent的接入方式走统一协议：每个Agent是一个独立的服务，对外暴露一个标准接口，输入是"上下文+用户消息"，输出是"回复内容+结构化信息"。只要符合这个协议，用Python、Node.js还是多少年前的Java都无所谓。

2.4 知识库与持久化层：让AI带着课堂记忆工作

知识库是整个平台的地基。它存三类数据：课程资料、课堂记录、学生画像。课程资料就是课件、讲义、参考书、历史试题，通过向量化和检索增强生成的方式接入每个Agent。课堂记录包括问答日志、参与度数据、讨论过程。学生画像是长期积累的个体学习档案。

实际工程里我用了一套经典RAG方案：离线把学习资料切块、嵌入、存入向量数据库；在线查询时，根据用户问题做语义检索，取出最相关的块组装成参考上下文。切块策略上我没用固定字数切分，而是按语义边界切——每个块尽量是一个完整的知识点，这样检索命中率明显好于简单按文本长度切块。

2.5 实时通道与同步机制

课堂场景对实时性有要求。学生提问之后，希望几秒内就有回应，这不能用传统"发请求等响应"的HTTP模式硬扛。前端和编排层之间走的是WebSocket长连接，消息双向实时推送。编排层内部用消息队列做异步解耦，比如作业批改这类耗时操作，提交后先返回"已收到"，后台批完再主动推送结果。

同步机制上踩过一个坑：课堂里多端同时操作时，Agent状态可能会有冲突。比如老师在前端改了一个Agent的提示词，同时有一个学生正在和这个Agent对话。后来统一加了版本号机制，Agent在会话中记录自己使用的配置版本，老师修改配置后新会话用新版本，已有会话保持旧版本跑完，保证一致性。

3. 核心智能体设计：课堂里的每个角色都得有对应Agent

3.1 课堂助教Agent：守住知识边界的默认入口

助教Agent是所有Agent里使用频率最高的一个。它的定位不是"什么都知道的全能AI"，而是"这门课的助教"——知识范围限定在课程相关的内容，不会回答无关问题，也不会越俎代庖直接告诉学生答案。

提示词的核心约束有三条：第一，只能基于知识库内容回答，明确知道就答，不确定就说不确定，不能模型一本正经编答案；第二，采用苏格拉底式引导，学生问一个概念，不直接给完整解释，先反问学生一个引导性问题，让学生自己推导；第三，对涉及主观判断的内容，必须标注"这是我根据xxx资料整理的，建议和老师确认"这类免责提醒。

这个Agent我做了模型分层调用。简单的概念解释、题目引导，用小参数模型跑就够，响应快、成本低；复杂推理、需要多步推导的问题，才路由到大模型。识别逻辑不复杂，编排层根据问题的token长度和关键词密度做个初步判断，拿不准的都送大模型。

3.2 小组讨论Agent：从提需求到引导讨论

这个Agent是OpenMAIC里交互逻辑最复杂的一个。它服务的不只是单人，而是整个小组。小组讨论的场景是：几个学生围绕一个主题讨论，Agent在讨论群里扮演一个"讨论促进者"的角色。

它的工作流程分三步。拿到讨论主题后，第一步先做"话题拆解"，把这个主题拆成三到五个讨论维度。比如讨论"人工智能对教育的影响"，就拆成技术可能性、教师角色变化、学习方式变化、伦理风险、落地难点五个角度。第二步是"提问介入"，当一个维度讨论冷场时，Agent会发一个问题把话题再拉回来，比如"刚才大家提到了效率提升，那你们觉得有没有可能因为效率提升导致依赖过度？"第三步是"观点归纳"，讨论到一定阶段，Agent会输出一份阶段小结，把发散的观点整理成结构化的分类列表，帮助小组看到讨论全貌。

这个Agent在工程上要注意一个点：它在群里发言必须克制。默认情况下，每轮讨论最多介入两次，其余时间保持静默。否则学生会觉得有个AI一直盯着讨论，心理压力很大，反而不愿意说。

3.3 作业批改Agent：要有评分依据，不要扔个分数

八年前我刚开始做信息化的时候，给学生作业批改都是给个总分然后写两句评语，后来发现这种方式对学生的帮助有限——学生不知道分扣在哪、怎么改。所以批改Agent的设计目标很明确：每个成绩必须带依据，每句评语必须可执行。

第一版批改Agent只做规则匹配，题库有标准答案就比对，没有就跳过。后来引入大模型做开放式作业的批改，比如论述题、编程题、实验报告。核心逻辑是：先拆评分维度，再按维度打分，最后汇总生成反馈。比如编程题拆成功能完整性、代码规范性、算法效率、注释质量四个维度。每个维度给出分数档和一句改进建议。

批改结果不只是给学生看，还要回流到学情分析Agent。每个学生的批改数据打上"知识点"标签，这样学情分析Agent就能算出来"这个班在递归算法这个知识点上的平均掌握度只有62%"，自动给老师生成教学调整建议。

3.4 学情分析Agent：数据回流才是多智能体的隐藏价值

如果说前面三个Agent是"前台服务"，那学情分析Agent就是"后台赚钱的部门"。它不直接和学生交互，但负责把整个平台的交互数据变成教学策略。

它的输入数据源有三块：助教答疑记录、小组讨论记录、作业批改结果。处理流程是：每天定时做一次ETL，把原始记录解析、清洗、打标签，写入分析库；然后按知识点做掌握度聚合，按学生个体做能力画像，按班级群体做趋势分析；最后生成结构化报告，推送给老师端。

这里要特别说明数据隐私问题。课堂数据涉及未成年人，处理必须严格。平台默认开启了数据脱敏，学生信息只保留唯一标识，不做姓名关联分析。部署到学校内部的实例，数据全部存储在本地，不经过云端中转。开源协议里也明确了：使用方有责任遵守当地教育数据保护条例。

4. 课堂场景实操实录：从配置到上线

4.1 课堂创建与智能体配置案例

假设一位老师要在某高校的"操作系统原理"课上启用OpenMAIC。他要做的配置流程是这样。

第一步：创建一个课堂。填课程名称、班级列表、学期时间。这是元数据，后面所有Agent都挂在这个课堂下面，数据和权限天然隔离。

第二步：配置课堂助教Agent。绑定课程资料知识库，上传课件PDF和参考教材。设置助教风格为"引导式"，设置知识边界为"只回答操作系统相关概念和算法问题"。这里我建议老师们有个避坑心态：知识边界设置得越窄，回答质量反而越高。与其让它覆盖整本教材，不如只让它负责本学期前六章的内容，宁缺毋滥。

第三步：配置作业批改规则。这步要花点心思把评分维度写清楚。以"进程同步与互斥"这章的作业为例，老师可以定义四个维度：概念准确性（30分）、算法流程完整性（30分）、代码实现正确性（25分）、规范与注释（15分）。每个维度配上参考的正例和反例。配置完成后，批改Agent提交一份作业，会生成一个带评分明细的卡片，每项扣分都有对应标注。

4.2 一份Agent配置示例（核心协议格式）

自定义Agent接入协议是平台的一个核心开放点。下面是一份最简配置示例，一个"课后答疑"Agent的注册配置，协议字段可以直接复用：

agent_id: tutor_afterclass name: 课后助教 description: 负责课后疑难问题解答，偏向概念梳理与例题引导 entry: http://127.0.0.1:8101/tutor protocol_version: "1.0" capabilities: - type: chat input: text output: text + structured_reply - type: rg_retrieve knowledge_base_ids: - kb_os_course_2024 - kb_os_exercise_sets limits: max_context_length: 4096 max_response_tokens: 512 temperature: 0.3

这个配置的意思是这个Agent监听本机8101端口的服务，可以做文本对话，并且能检索两套知识库材料。temperature设到0.3是为了让它在答疑时保持严谨，不要发挥得太过头。如果你想让答疑风格活泼一点，可以调到0.6到0.8，但课堂场景我建议不要超过0.5。

4.3 拿到配置后跑一个真实交互流程

配置好之后，课堂上的完整流程是什么样的？以"死锁的四个必要条件"这堂45分钟的课为例。

上课第10分钟，老师讲到死锁的互斥条件，有学生不理解，直接在学生端提问："为什么互斥是死锁的必要条件？互斥不是资源本来的属性吗？"这个请求发送到编排层，意图识别判定为"助教答疑"，路由到课堂助教Agent。课堂助教检索知识库，命中教材里"资源互斥"的片段，然后不是直接给答案，而是先反问："如果一个资源可以被多个进程同时占用，你觉得还会发生死锁吗？"学生回答"不会吧"，Agent再进一步解释互斥为什么是必要而非充分条件，顺带把"循环等待"和"互斥"的关系理清楚。这轮问答结束后，学情分析Agent在后台自动记了一条："某学生，死锁概念，理解程度中等，需要巩固"。

第25分钟，老师发起小组讨论，主题是"银行家算法在实际系统中适合用吗？”小组讨论Agent拆解出四个维度，在小组群里逐步提出引导问题。其中一组讨论始终没进入正题，Agent提示"可以结合一个具体的操作系统实例来分析"，帮学生找到了切入点。

第40分钟，老师布置作业，是两道死锁分析的题。作业提交后，批改Agent按评分维度批改，第一个维度给了18分（满分30），备注"概念描述正确，但缺少对'持有并等待'条件的推导过程，建议补充分析"。老师端实时收到批改结果，直接在课堂上就能点出共性问题。下课之后，学情分析Agent推送一份"本课掌握度分布"报告，老师看到"死锁必要条件的掌握度为71%，建议下次课花5分钟回顾"，这个闭环就完成了。

5. 部署、扩展与成本控制

5.1 私有化部署不锁模型

做教育类平台，模型必须能换。OpenMAIC在接口层做了模型适配器，对外暴露统一的chat接口，内部可以对接不同的模型来源。私有化部署的学校，可以用本地部署的开源模型；SaaS场景可以使用商业API。切换模型时只改配置，不用改业务代码。

我在这个设计上没少花心思。模型适配层抽象了三个核心方法：generate（生成回复）、generate_stream（流式生成）、generate_structured（生成结构化输出）。有了这个抽象层，从梁文锋家的推理模型换到开源对话模型，只需要实现一个新适配器类，300行代码以内能搞定。

5.2 并发扩容和水位控制

课堂场景有一个很典型的技术特征：消息流量集中在课堂时间段，而且有小规模的突发性。一个班50个人，如果同时提问，瞬间可能产生20到30个并发请求。如果遇到公开课、直播课，并发可能到几百。

这里的经验是"提前压测，按峰值3倍规划"。我专门做过一次模拟压测：模拟200个学生同时发起请求，观察编排层和每个Agent服务的资源占用、响应时间。根据压测结果，把消息队列的最大缓冲、每个Agent服务的线程池大小、数据库连接池上限都做了对应调整。另外加了一个水位控制策略：当队列积压超过阈值时，请求进入等待队列，前端提示"老师正在回答前面的问题，请稍等一下"，避免系统在一波突发流量下被打垮。

5.3 token费用建模：别让账单吓到你

多智能体架构最大的隐藏成本是token的重复消耗。同一段上下文，路由Agent读一遍，助教Agent读一遍，学情Agent存储又占一份。如果管理不好，月账单会是个惊吓。

我的做法是三层管控。第一层是上下文裁剪：每个Agent拿到手的信息，只保留与其职责相关的部分。第二层是缓存优先：同一问题在一小段时间内被多次提问，直接复用之前的结果，不再调用模型。第三层是模型分层：意图识别用紧凑模型，简单的课堂问答用小模型，只有复杂推理才调大模型。跑了一个学期下来，课堂场景和非课堂场景的token消耗基本能维持在预算范围内。

6. 常见问题与排查实录

6.1 上下文污染和角色混乱

多智能体系统最经典的问题是A Agent的对话历史被B Agent读到。比如某次课堂问答讨论到"哲学"相关话题，助教Agent的回答被误路由到了作业批改Agent的知识上下文里，批改机器人说话口气突然变得很像哲学老师。

排查思路是：先在编排层的日志里看每个请求的路由记录，确认Agent是否被正确分发；再检查记忆库的键名是否按Agent维度做了隔离。我遇到的第一次这种问题，就是因为记忆库的键名漏了Agent ID，所有Agent共用了一个上下文存储空间。加了Agent ID前缀做隔离之后，角色混乱问题基本消失。

6.2 并发超时与重试风暴

有一次线上课堂，某学生连续点了三次发送按钮，前端每次都触发了请求，结果产生了三条重复的并发任务，把后端一些能跑重合的Agent服务拖垮了。处理方案是前端做请求幂等：每个学生端的消息带上一个唯一的client_message_id，后端靠这个ID做去重。第二个问题是后端Agent服务响应慢时，前端会自动重试，形成了"重试风暴"。后来在后端加了熔断器：当Agent服务错误率超过阈值时，直接快速失败，不再等待超时，避免故障扩散。

6.3 知识库命中率低，答非所问

当助教Agent回答质量明显下降时，我建议优先排查RAG检索环节。最常犯的错误是把整本PDF丢进去做向量化，没有做切块和清洗。PDF里大量的章节目录、页眉页脚、公式图注会严重污染向量空间。处理方式是先做解析预处理，剥掉页眉页脚和目录，按"小节"级别切块，公式部分单独存储并配上文字描述。这个改动做完之后，知识库命中率通常能提升一倍。

6.4 Agent之间互相调用的死循环

自定义Agent接入多了之后，可能出现循环调用：Agent A调用Agent B，Agent B又调用Agent A。这种死循环用日志能看出来——同一个请求ID会出现多层嵌套的调用记录。排查方式是给每次跨Agent调用设置最大深度和单次调用超时，同时限制每条消息最多只能跨Agent转发三次。超时之后自动终止循环，并返回一条兜底提示。

说实话，我一开始自己也没把握这套东西能在真实课堂里站住脚。但跑了一整个学期之后，最让我确信做对了的，是"分工"这件事。每个Agent只负责一类事，知识边界清晰、行为模式稳定，学生用下来没有那种"AI飘忽不定"的感觉。老师那边也不用盯着后台帮AI纠错了，因为每个Agent的输出范围被收窄之后，出错的概率本来就小很多。如果你也想做一个多智能体项目，不管是不是教育场景，我建议先从"拆分角色边界"开始，而不是先折腾模型选型。你要是自己开了实例跑出了问题，欢迎到社区仓库聊聊，这类场景的坑，一个人踩一遍，大家就都不用再踩了。