OpenMAIC
OpenMAIC 架构：从材料到可恢复的多智能体课堂会话
跟踪工作台、LangGraph 代理运行时、Provider 适配器、持久化、课堂产物和导出边界。
你将学会
- Map OpenMAIC's observable runtime boundaries
- Evaluate provider and persistence contracts
- Design a traceable architecture review
开始前需要
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
先看结论
- Model OpenMAIC as workbench, agent runtime, artifact tools, and delivery adapters.
- Durable sessions and provider neutrality introduce explicit state and capability contracts.
- Trace materials, state, artifacts, persistence, and exports with reproducible identifiers.
The boundaries visible in the README
可以把 OpenMAIC 看成材料与工作台、LangGraph 代理运行时、课堂工具产物、持久化与导出四条边界。Provider 中立和 Durable Session 带来能力矩阵、状态恢复、取消幂等和导出校验等工程问题，不能只凭演示页面判断。
This is an editorial architecture model, not a claim about every internal module. The README names Next.js 16, React 19, TypeScript 5, LangGraph 1.1, and Tailwind CSS 4, plus provider-neutral model, media, search, and storage backends. Pin a commit and inspect the package graph before treating those labels as an implementation contract.
Follow one material through the system
Start with an uploaded document or a web-search result. The session-material layer should normalize metadata and make the source available to the workbench; the agent then turns the learning objective into a plan and invokes course skills. Durable sessions matter here: the v1.0.0 notes say runs can survive restarts, be cancelled, resumed, or steered, so state transitions deserve the same review as UI components.
The artifact boundary is where generated content becomes inspectable. A slide deck, quiz, simulation, or voice asset should carry enough session context to identify its source materials, model/provider route, and generation revision. Export is a separate boundary: a successful chat response does not prove that a .pptx or HTML renderer handled fonts, media, or untrusted input safely.
Provider and persistence adapters
Provider neutrality reduces lock-in but multiplies contracts. Chat, image, TTS, ASR, search, and storage can have different credentials, timeouts, quotas, and data-retention rules. Keep those adapters behind explicit capability checks and record which route produced an artifact; otherwise a fallback can silently change the lesson.
The README highlights a pluggable persistence stack and a one-command Postgres reference deployment. For an architecture review, test a restart between two agent steps, verify that cancellation is idempotent, and compare the restored session with the last emitted artifact. A database connection that works in the happy path is not proof of resumability.
Architecture review checklist
Draw a trace with request ID, material hash, agent state, tool invocation, provider, artifact path, persistence event, and export checksum. Redact document contents and API secrets, but keep identifiers and failure reasons. Then exercise a provider timeout, malformed upload, duplicate resume, and export failure; each should fail at a named boundary and leave a recoverable state.
The most important design choice is keeping generated teaching content reviewable. OpenMAIC's multi-agent classroom can make learning immersive, but subject-matter accuracy, accessibility, and audience suitability remain application-level gates rather than properties guaranteed by orchestration.
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
Pin a commit and list the runtime, provider, and persistence packages.
- 2
Trace one material from upload/search through an agent step and artifact.
- 3
Restart or cancel mid-run and verify durable state and idempotent resume.
- 4
Export a deck or HTML artifact, record its checksum, and review content and safety.
可复制示例
material hash -> session event -> agent state -> tool/provider call
-> artifact metadata -> durable save -> export checksum常见问题
Does LangGraph alone make a session durable?
No. Durability depends on the application's persistence and recovery implementation; verify it with a restart and a replayable session fixture.
Can every provider produce identical classroom artifacts?
No guarantee. Compare capability, schema, media support, latency, and error behavior per provider and record the selected route.
资料来源
- OpenMAIC README (captured 2026-08-31)来源核查 2026-08-31
- OpenMAIC repository来源核查 2026-08-31