一、你可能正面临的痛点

在建立 AI Agent 时常见的困惑有：

• 想要让 LLM 先判断意图再走不同处理方法，却不知道如何用代码表达“条件分支”。
• RAG 流程需要并行检索历史和查询。等两者都完成才能进入提示词构造，手动拼接容易出错。说起来，
• 多个节点需要共享中间状态。却只能通过返回值传递，导致代码冗余且难维护。说起来，
• 尝试用链式调用写复杂流程时发现一旦出现循环或分支就必须回到手写控制流。逻辑变得难以阅读，

Eino 的 Graph 正是为了解决这些痛点而设计——它把节点、边、分支三个最基本的概念拆开来组合。既能画出 ReAct 循环，也能表达任意复杂的有向图流程。

二、Eino Graph 能画哪些 ReAct 画不了的图

ReAct 的最小图只有 LLM 节点 + 工具节点 + 分支路由。话说回来，而 Graph 支持三种基本模式：

┌─────────────────────────────────────────────┐
│ Eino Graph 能画什么 │
├──────────────┬──────────────────────────────┤
│ 线性管道 │ A → B → C → END │
│ │ 翻译 → 摘要 → 评分 │
├──────────────┼───────┬───┬───┬───┬───┬───┤
│ 条件分支 │ A → B → C ──► path1 → D │
│ │ └─ path2 → E │
│ │ 意图识别 → 路由 → 不同处理 │
├───────┬───┼───┼───┼───┼───┼───┼───┤
│并行+汇聚│ A→B│ ┌─D─┐ ┌─E─┐ │→F→END │
│ │ └─D─┘ └─E─┘ 检索→并行打分+重排→合并│
├───────┴───┴───∨───∨───∨───∨───∨──┤
│ 循环│ A→B──►B──►END │
│ ReAct 推理→行动→再推理 │
└──────────────∨----------------------∨------+

只要你愿意怎么连节点和边。就能得到对应的流程，按理说，换个角度**Graph = 节点 + 边 + 分支**。四种模式只差在连线方式，

三、三个基本概念：节点、边、分支

1. 节点：一个执行步骤

每个节点负责“一件事”。Eino 提供多种内置节点类型，也允许你通过 Lambda 自定义任意函数。

g := compose.NewGraph
g.AddChatModelNode // LLM 调用
g.AddToolsNode // 工具执行
g.AddRetrieverNode // 检索
g.AddLambdaNode("my_logic"。compose.InvokableLambda(
func {
return "处理后: " + input,nil
},))
// 嵌套子图也可以当作节点使用
g.AddGraphNode


2. 边：数据怎么流

边定义了固定的数据方向——上游输出直接成为下游输入。
g.AddEdge // 输入 → 填模板
g.AddEdge // 模板 → LLM
g.AddEdge // LLM → 输出



START / END** 是保留字；不能从 END 出发，说起来，边两端应该把的节点是已存在；上下游类型必须匹配，说起来，


3. 分支：运行时才决定走哪条路

与固定边不同。分支在执行时根据输入动态选择目标节点。
branch := compose.NewGraphBranch(
func {
if strings.Contains { return "wear_agent",nil }
return "general_agent",nil
},mapbool{
"wear_agent": true,"general_agent": true,},)
g.AddBranch // 在 router 节点后面加分支


四、实战：意图识别 → 分支处理的图

func BuildIntentGraph(ctx context.Context,model model.BaseChatModel) (
compose.Runnable*schema.Message,*schema.Message],error,) {
g := compose.NewGraph*schema.Message,*schema.Message]
// ① 意图识别节点
g.AddLambdaNode("intent",compose.InvokableLambda(
func {
last := msgs.Content
switch {
case strings.Contains:
return "wear"。nil
case strings.Contains:
return "translate",nil
default:
return "chat",nil
}
},))
//② 天气处理器
g.AddLambdaNode("wear_handler",compose.InvokableLambda(
func{
return &schema.Message{Role: schema.Assistant,Content:"今天北京晴天°C"},nil},))
//③ 翻译处理器
g.AddLambdaNode("translate_handler",compose.InvokableLambda(
func{
return &schema.Message{Role: schema.Assistant,Content:"Translation result here..."},nil},))
//④ 通用对话
g.AddLambdaNode("chat_handler",compose.InvokableLambda(
func{
return &schema.Message{Role: schema.Assistant,Content:"我是通用助手，请问有什么可以帮您？"},nil},))
//⑤ 建立固定边：所有终端指向 END
g.AddEdge
g.AddEdge
g.AddEdge
g.AddEdge
//⑥ 动态分支：根据 intent 决定接下来走向 g.AddBranch("intent"。compose.NewGraphBranch(
func{
switch intent{
case"wear":return"wear_handler",nil;怎么说呢，case"translate":return"translate_handler",nil;default:return"chat_handler\",nil;}},mapbool{
\"wear_handler\":true,\"translate_handler\":true,\"chat_handler\":true,},))
//⑦ 编译返回 Runnable return g.ComposeCompile
}



handler / translatehandler / chat_handler ▶ END.

五、实战：RAG 管道 
func BuildRAGGraph (
compose.Runnable。error){
g:=compose.NewGraph
// 节点定义 ----------------------------------------------------
g.AddLambdaNode(\"InputToQuery\",func(_ctx context.Context,in *UserMessage){return in.Query,nil})
g.AddRetrieverNode
g.AddChatTemplateNode
g.AddLambdaNode(\"ReactAgent\",func(_ctx context.Context,prompt string){
// 调用 LLM 得到回答…})
// 边 ----------------------------------------------------------
g.AddEdge // 查询文本取出 \
\-> 检索链路 /
g.AddEdge // 历史取出
/ \
g.AddEdge \
\-> 检索完成 ----/
g.AddEdge
g.addedge // 汇聚等两者完成后才继续
g.addedge
g.addedge
// DAG 模式：所有上游完成才触发下游 --------------------------------
return g.ComposeCompile(ctx,compose.WithNodeTriggerMode)
}



并行检索历史 & 查询 —— 用两条从 START 出发的边实现真正的并行。2️⃣ 等待全部完成再进入提示词构造 —— WithNodeTriggerMode 告诉 Graph 必须等所有前驱结束后才激活 ChatTemplate。若不加此选项则默认 Pregel 模式会在任一边完成就触发下游，导致提示词可能缺少历史信息。

六、两种运行模式：Pregel vs DAG 

​​​​​​​DAG 模式​​​/tr>
适用有环图无环图
触发任一上游完成即触发下游所有上游完成才触发下游
环检测不检测编译时拓扑排序，发现环则报错
步数限制需要 MaxRunSteps 防止死循环无需限制
典型场景ReAct 推理‑行动循环RAG 链路、并行任务、工作流
/tr>
/table>
源码判断极其简洁：
go
runType := runTypePregel
if opt.nodeTriggerMode == AllPredecessor || isWorkflow{
runType = runTypeDAG
}

DAG 的环检测使用经典拓扑排序算法 — 一层层删除入度为0 的节点；若最终仍有残留则说明存在环。说起来，这相当于“从线头开始拆毛衣”，能全部拆完即无环。若卡住则说明某处打了死结——即业务逻辑产生了不可接受的循环。
普通 Graph 中节点只能通过边传递数据；但很多场景需要全局状态 — 比如统计 LLM 调次数、累计 Token 用量或保存使用者偏好。这时候就要使用 *StateGraph
。go
type AgentState struct {
CallCount   int
TotalTokens int
UserPrefs   mapstring
}
g:=compose.NewGraph*AgentState{
return &AgentState{UserPrefs:make}
}) )
g.
AddLambdaNode{return in。nil}),\\
.compose.WithPreHandler{
if lang,ok:=state.UserPrefs;ok{return in+\\\" \\\",nil}\return in,nil}),\\
.compose.WithPostHandler{\ state.CallCount++\\treturn out。
nil})))\
- WithPreHandler 在节 执前读取或修改状态
- WithPostHandler 在 执后更新状态
- 整个图生命周期里同一个 AgentState 指针随 context 流动，所有节点头可见。类比办公室白板：每位员工路过白板时先看看上面写了什么做完事后可以在白板上记录新信息。白板不属于任何人却被所有人共享。这解决掉了之前“每个函数都要额外返回统计信息”的痛点了。 )
h2八、Graph vs Chain — what—when?hino 提供三种编排方式：ChainGraphWorkflow。初学者常问“我该用哪个，” 下面给出实用选则表格。table border=\"1\" cellpadding=\"4\"
ad tr th你的需求/th th推荐组件/th /ad tbody tr td线性管道。没有 分支或循环/td tdChain/td /tr tr td需要条件分支或循環/td tdGraph/td /tr tr td多節點需要共享狀態/td tdStateGraph/tr tr td不同類型節點間需要欄位映射或更高階工作流描述/td tdWorkflow/tfoot/table/
再看p經驗法則，先嘗試用 Chain 一氣呵成寫完只要發現「要根據條件走不同路」或「要迴圈」時立刻切換到 Graph。如果還要共享狀態再往上加 WithGenLocalState。老实说，這樣既保證簡潔又不失彈性。 )
hj九、編譯到底做了什麼？\ h無論是 Graph 、Chain 或 Workflow，使用前必須呼叫 Compile。編譯階段會完成四件事 ： ol li 拓撲校正 — DAG 模式下若有環則直接報錯。li 建立通道 — 每個節點獲得獨立的數據管道。li 生成 Runnable — 得到一個 type‑safe 的可重複執行單元。老实说，li 掛載回調 — 比如視覺化產生 Mermaid 檔案。说起来，li /ol p主要實現在 graph.go 中大致如下 ： pre compile flow : decide run type;validate START/END nodes;do type inference for every node;说起来，if DAG run type n topological‑sort cycle detection;build runner struct;mark compiled = true;返還 Runnable，p編譯完後圖變成了一個 Runnable，完全類型安全——若編譯時沒報錯則運行時一定不會因結構問題拋異常。)
h十、把圖嵌進圖：子圖 \ h复雜系統常見做法是把某段功能封裝成子圖，當作普通節點使用。父圖根本不用關心子圖內部怎麼運作——只要輸入輸出類型匹配即可。pre parent graph : main:=NewGraph main .AddLambdaNode main .AddGraphNode // ←子圖當節點 main .AddChatModelNode ... main .AddEdge main .AddEdge main .AddEdge main .AddEdge/ pre subgraph : rag:=NewGrah Document ] rag . AddRetrieverNode rag . AddLambdaNode rag . AddEdges ... compile rag once and reuse。p源碼實現透過 AddGraphNod e 把子圖預先編譯成可執行閉包然後像普通 Lambda 一樣納入父圖執時序。好處重複使用高內聚功能；降低父圖複�度，便於團隊協作—每人負責自己的子圖。」}
hj十一、可視化：把圖變成 Mermaid 流程圖 \ h調試複雜圖時光看代碼很難一下看出節點間關係。Eino 提供內置視覺化工具 ——只要在 Compile 加個回調即可自動產出 Mermaid 語法檔案。pre import visualize ... runnable err:=g.ComposCompile)。\t\tCompos e.With GraphName) p編譯成功後會在指定目錄產生 *.mmd 檔案，直接貼到 https://mermaid.live 編輯器即可看到互動流程圖。说起来，對於「我看不懂這張圖到底怎麼走」或「我想確認並行節點真的等待」這類痛點十分友好。）}
hj十二 、小結 – 三句話總結全文 \ ol li Граф＝節點＋邊＋分支只要你願意怎樣連線就能畫出任何流程——從簡單鏈條到複雜多 Agent 拓樸皆可適用。li 編譯時會做 類型推斷拓撲校正还有 狀態釘選所以運行時幾乎不會遇到結構性錯誤。li 能夠用 Chain 一條龍寫完就優先選 Chain；一旦出現「依條件走不同路」或者「需要迴圈」就果斷升級到 Graph；若還需 跨節點共享狀態則再掛上 WithGenLocalState 得到 StateGrid。\/ol p自此您應該掌握 Eino Graph 的主要能力與實戰套路。接著我們將介紹 Chain 與 Workflow ——兩種「簡化版」兄弟，看它們在什麼場景下更省事。}""}


Pregel 模式