cloudwego/eino：Go 生态写 LLM Agent，从 ChatModelAgent 到图编排与中断恢复
仓库: github.com/cloudwego/eino（Apache-2.0，Go 语言，要求 Go 1.18+；stars/tags 等实时数据以仓库页面为准）
Eino（读作 aino）是 cloudwego 用 Go 写的 LLM 应用开发框架。cloudwego 是字节跳动开源组织，旗下还有 Kitex、Hertz 等项目。框架设计参考 LangChain、Google ADK，目标是保持 Go 惯例：类型与接口显式，组件之间通过接口衔接，而不是靠字符串协议到处拼。
框架整体提供四块能力：
- Components（组件层）：ChatModel、Tool、Retriever、ChatTemplate 这类可复用构建块，官方实现在 eino-ext 中覆盖 OpenAI、Ollama、Claude、Gemini、Ark、Elasticsearch 等。
- ADK（Agent 开发套件）：工具调用、多智能体协调、上下文管理，以及带人类介入的中断/恢复，附带可直接使用的 agent 模式。
- Composition（组合层）：把组件连成图/工作流，可独立运行，也可以暴露成 agent 的一个工具。
- Examples：常见模式与真实用例的可运行示例。
最小可用的 agent：ChatModelAgent
配置一个 ChatModel，可选挂上 tools，就是一个能跑的 agent：
chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
Model: "gpt-4o",
APIKey: os.Getenv("OPENAI_API_KEY"),
})
agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
Model: chatModel,
})
runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
iter := runner.Query(ctx, "Hello, who are you?")
for {
event, ok := iter.Next()
if !ok {
break
}
fmt.Println(event.Message.Content)
}
给 agent 加工具时，在 ToolsConfig 里声明：
Tools: []tool.BaseTool{weatherTool, calculatorTool},
之后 agent 内部自行跑 ReAct 循环，自己决定什么时候调工具、什么时候给最终响应。这个层适合“单个模型 + 一组工具就能闭环”的对话任务；如果后面还要多步计划、多个角色分工，就该上 DeepAgent。
复杂任务：DeepAgent 拆解与派发
DeepAgent 面向的是更复杂的任务：先把问题拆成步骤，委派给子 agent 执行，再跟踪整体进度。可以协调多个专门的 agent，也可以让它跑 shell 命令、执行 Python、联网搜索。适合任务结构不确定、需要边推进边规划的场景；代价是执行过程不像固定流程图那样完全可预期。
图编排：用 Composition 固定流程
需要精确控制执行流时，用 compose 建图：
graph := compose.NewGraph[*Input, *Output]()
graph.AddLambdaNode("validate", validateFn)
graph.AddChatModelNode("generate", chatModel)
graph.AddLambdaNode("format", formatFn)
graph.AddEdge(compose.START, "validate")
graph.AddEdge("validate", "generate")
// ... 连接 format 节点与 END
runnable, _ := graph.Compile(ctx)
result, _ := runnable.Invoke(ctx, input)
这里的特点是流程阶段、节点依赖、输入输出类型都在图上固定下来，适合“流程确定”的管线，比如校验 → 生成 → 格式化；也适合给 LLM 造一个外部工具：通过 graphtool 包把整张图包成 agent 的 tool，让自治的 agent 去调用一段确定性的工作流：
graphtool.NewInvokableGraphTool(graph, "data_pipeline", "Process and validate data")
编排图越精确，行为越可预测，但它要求流程在运行前就能画清楚；流程本身需要“现想”的任务，放给 DeepAgent 更合适。
流式处理
框架在编排过程中自动处理节点间的数据流：拼接、装箱、合并、复制。组件只需要实现对自己有意义的流式范式，不需要自己维护上游到下游的搬运逻辑。上层拿到的 Runner/Stream 是迭代器接口，方便以流的方式消费 LLM 输出。
回调切面：固定点注入可观测性
框架在固定节点提供回调切面：OnStart、OnEnd、OnError、OnStartWithStreamInput、OnEndWithStreamOutput。日志、追踪、指标都挂在统一切点上，而不是散落在业务代码里。适合需要统一观测 agent 生命周期、并按阶段打点埋点的场景。
中断与恢复：human-in-the-loop
agent 或 tool 可以在任意位置暂停，等待人类输入，之后从检查点恢复继续执行。状态持久化与路由由框架处理。适合人工审批、需要澄清用户意图、或运行中要修正输入/工具结果的交互式任务，不需要业务自己维护暂停时的会话状态。
仓库划分与工程要求
框架按职责拆成几个部分：
- eino 主仓：类型定义、流式机制、组件抽象、编排能力、agent 实现、切面机制。
- eino-ext：组件实现、回调处理器、示例、评估器、prompt 优化器。
- eino-devops：可视化开发与调试。
- eino-examples：示例应用与最佳实践。
依赖要求是 Go 1.18 及以上。代码风格规定用 golangci-lint，导出符号需要带 GoDoc，格式走 gofmt -s，import 顺序固定为标准库 → 第三方 → 本地。
文档与相关仓库
- 主仓库：github.com/cloudwego/eino
- 官网/文档：cloudwego.io，内有 Eino 用户手册与快速开始，提供中文（zh）文档
- 组件与实现：github.com/cloudwego/eino-ext
- 示例仓库：github.com/cloudwego/eino-examples