通用 Agent 做不到的事、范式为何刚成熟、主流框架横评。
brain / hands / session 加九个组件。
系统架构图、技术选型、核心链路。
为什么只用低层 StateGraph 原语。
为什么 Agent 必须把过程实时推给前端。
四条踩坑原则；瓶颈正从模型转向工程。
Orin 的目标：搭一个公司共享的 Agent 后端，把知识库、Skill、业务渠道集中接入一次，所有人开箱即用。
结论：模型能力是起点，让 agent 真正可用的是工具链和范式的成熟 —— 现在搭一个生产级 Agent 是工程问题，不再是研究问题。
| 框架 | 定位 | 得到 | 主要限制 |
|---|---|---|---|
| LangGraph | 低层编排原语（StateGraph） | 控制流透明、checkpoint/HITL/时间旅行免费、不绑模型 | harness 要自己搭，曲线陡 |
| CrewAI | 高层角色/任务 DSL | 原型极快、内置 memory 与角色层级 | 生产可靠性弱，深度定制绕框架走 |
| Claude Agent SDK | 高层 harness，MCP 原生 | 电池全包，MCP 生态最广，官方维护 | 只能用 Claude，深度控制流较弱 |
| OpenAI Agents SDK | 轻量原语 + handoff | agent 间交接一等公民，内置 tracing | 绑 OpenAI，成熟度较低 |
| Vercel AI SDK | 前端 / TS 向流式工具包 | 多模型、Next.js 深度集成、流式 UI 最好 | 后端编排非强项，TS only |
| MS Agent Framework | 企业级（AutoGen + SK 合并） | OpenTelemetry、Entra ID、Python/.NET 双栈 | 两套历史包袱，复杂度高 |
| CopilotKit / AG-UI | 前端协议层（非 agent 框架） | 工具卡/思考链/状态同步标准事件 | 只解决 UI，后端要另选 |
我们的选择：LangGraph（后端编排）+ AG-UI（前端事件流）—— 一个要控制力、一个要前端标准化，两者都选「不锁死、可组合」。
Claude + harness：决定下一步、把工具调用路由出去。
沙箱与工具：真正读文件、跑代码、执行 git、查网络。
append-only 日志：发生过的一切，可持久、可恢复。
think → act → observe 主循环。
文件 / bash / web / MCP。
compaction 压缩，跨会话续命。
跨交互保留什么、检索什么。
委派子任务到独立上下文。
工具分级、人工检查点。
状态可落盘、可恢复孤儿任务。
生命周期注入点，扩展不改主循环。
测试 / eval 闭环。
| 层 | 选型 | 作用 |
|---|---|---|
| 编排 | LangGraph | 控制 ReAct 循环、工具调用、状态流转 |
| 后端 | Python 3.12 + FastAPI | 提供 /chat、/runs、/admin 接口 |
| 模型 | Claude API | 推理、规划、工具调用决策 |
| 沙箱 | Cloudflare Sandbox（E2B 备选） | 真实 shell、文件系统、代码执行 |
| 持久化 | Postgres + pgvector | 会话、checkpoint、记忆、向量检索 |
| 知识库 | Dify + KnowledgeSource 注册表 | 接入工单、QA、业务知识库 |
| 产物 | R2 | 文件、图表、报告等最终交付物 |
| 交互/观测 | AG-UI 事件流 · Langfuse | 实时渲染 + trace / eval |
START │ ▼ call_model ─▶ route ─┬─▶ tools ─▶ call_model │ ├─▶ human_approval ─▶ tools │ └─▶ finalize ─▶ END
图只负责三件事：调模型 · 跑工具 · 判断继续还是结束。上下文压缩 / 权限 / 记忆 / 检索 / 持久化 / 异常收尾，都在外围模块。
| Harness 组件 | Orin 里的实现 |
|---|---|
| Agent Loop | LangGraph ReAct 循环 |
| Tool Ecosystem | 沙箱、知识库、记忆、Skill、文件工具 |
| Context Management | 长上下文裁剪、摘要、tail-window 保留 |
| Memory | mem0 + pgvector，异步写入用户长期记忆 |
| Knowledge | Dify 双 dataset + KnowledgeSource 注册表 |
| Skills | SKILL.md 按需加载，封装业务操作手册 |
| Permissions / HITL | 高风险动作预留人工确认，沙箱隔离兜底 |
| Session Persistence | Postgres checkpoint，任务可恢复 |
| Verification | 失败 trace 转 eval，沉淀本地回归测试 |
观点：Agent 能不能稳定完成任务，关键不只在模型，也在这圈 harness —— 模型负责判断下一步，harness 负责给它正确上下文、工具、权限、反馈，以及失败后的恢复路径。
保存当前会话状态。
一个函数做一件事。
根据状态决定下一步。
中途暂停，等人工确认或外部事件。
价值：① 控制流透明 ② 每一步状态可检查 ③ checkpoint 天然支持恢复 ④ HITL / 时间旅行调试 / 失败重放都有扩展空间。
出问题时看不到模型实际收到什么、走了哪条路径。
黑盒 agent executor 让调试变成猜谜。
Orin 是内部生产平台：接知识库、接飞书、跑长任务、写文件、恢复任务、持久化产物 —— 最重要的是可控性。开发成本更高，但问题定位清楚、架构边界清楚。
开始思考 → 正在调用工具 → 工具参数 → 执行结果 → 正在生成文件 → 失败在哪 → 最终产物在哪。
把 Agent 的过程拆成标准事件，让前端可以稳定渲染 —— 工具卡 / 思考链 / 状态同步直接消费。
与 MCP 互补：MCP 解决 agent 怎么连工具，AG-UI 解决 agent 怎么把过程交给用户。
| 事件类型 | 前端表现 |
|---|---|
| 文本事件 | 打字机输出 |
| 工具事件 | 工具卡片、参数、执行结果 |
| 状态事件 | 任务进度、错误、完成、产物链接 |
RUN_STARTED ↓ TEXT_MESSAGE_START / CONTENT ↓ TOOL_CALL_START / ARGS / END ↓ TEXT_MESSAGE_CONTENT ↓ ARTIFACT_CREATED ↓ RUN_FINISHED
工程纪律：无论成功还是失败，后端都必须发 closing event。异常直接逃逸 → SSE 流断 → 前端永远卡在 thinking。graph 内部要兜住异常，把失败也变成一条可展示、可记录、可恢复的事件。
所以 Orin 收敛成唯一 live 图 build_chat_graph，所有能力（上下文压缩 / 知识检索 / 记忆 / Skill / 沙箱 / 产物 / 事件流 / trace+eval）都必须挂到真实路径上。先保证一条主链路可靠，再在这条链路上加能力。
call_model 最容易变成垃圾场 —— 全塞一个函数里，后面一定改不动。加能力 = 加一个 capability，删能力 = 摘掉一个 capability。主循环保持稳定，能力持续演进。
guardrail / compression / reminder 已拆成独立 capability；只剩 vision 还内置在 legacy_turn。结构对了，迁移还差这一步。
run 状态、thread 状态、checkpoint、产物链接、失败原因 —— 全在 DB。
恢复孤儿任务，至少能告诉用户：成功、失败、还是需要重试。
Agent 一旦跑长任务就会遇到大量现实问题 —— 唯一可靠的兜底，是把状态全落到 DB。
evals/tasks/*.yaml真正有效的方法，是持续把事故沉淀成评测集。
更好的 context engineering
更安全的沙箱
更标准的 tool protocol
更稳定的 frontend protocol
更强的可观测 + eval
更清晰的权限 / 人工确认
更易复用的能力单元
更可控的成本
Agent 平台的竞争，会越来越像基础设施竞争。
harness 写死太多流程，下一代模型变强后旧规则会反过来限制它。Orin 的取向：控制权尽量给模型，确定性能力交给工具，安全边界放在权限和沙箱，状态管理放在 DB，失败样本交给 eval。
harness 不替模型思考，它提供环境、工具、边界和反馈。 · Q & A