eino-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eino Framework Guide

Eino框架指南

Eino (pronounced "i know") is a Go framework for building LLM applications.

Eino（发音为"i know"）是一款用于构建LLM应用的Go框架。

Core Concepts

核心概念

Component

组件

Standardized interfaces for AI capabilities. Each interface has multiple interchangeable implementations.

Component	What It Does	Key Interface
ChatModel	LLM inference (generate / stream)	`model.BaseChatModel` , `model.ToolCallingChatModel`
Tool	Functions the model can call	`tool.InvokableTool` , `tool.EnhancedInvokableTool`
Embedding	Text to vector	`embedding.Embedder`
Retriever	Vector/keyword search	`retriever.Retriever`
Indexer	Store documents with vectors	`indexer.Indexer`
ChatTemplate	Prompt formatting with variables	`prompt.ChatTemplate`
Document Loader/Transformer	Load and process documents	`document.Loader` , `document.Transformer`
Callback Handler	Observability and tracing	`callbacks.Handler`

Implementations live in

eino-ext

(OpenAI, Claude, Gemini, Ark, Ollama, Milvus, Redis, Elasticsearch, etc.).

-> Use

/eino-component

for selecting, configuring, and using components.

AI能力的标准化接口。每个接口都有多个可互换的实现。

组件	功能	核心接口
ChatModel	LLM推理（生成/流式输出）	`model.BaseChatModel` , `model.ToolCallingChatModel`
Tool	模型可调用的函数	`tool.InvokableTool` , `tool.EnhancedInvokableTool`
Embedding	文本转向量	`embedding.Embedder`
Retriever	向量/关键词搜索	`retriever.Retriever`
Indexer	存储带向量的文档	`indexer.Indexer`
ChatTemplate	带变量的Prompt格式化	`prompt.ChatTemplate`
Document Loader/Transformer	加载和处理文档	`document.Loader` , `document.Transformer`
Callback Handler	可观测性与链路追踪	`callbacks.Handler`

实现代码位于

eino-ext

中（支持OpenAI、Claude、Gemini、Ark、Ollama、Milvus、Redis、Elasticsearch等）。

-> 如需选择、配置和使用组件，请使用

/eino-component

。

Orchestration (Compose)

编排（Compose）

Three APIs for wiring components into executable pipelines. All compile to a

Runnable[I, O]

with four execution modes (Invoke, Stream, Collect, Transform).

API	Topology	When to Use
Graph	Directed graph, supports cycles	Complex flows with branching, loops (e.g., ReAct pattern)
Chain	Linear sequential	Simple pipelines (e.g., template -> model)
Workflow	DAG with field-level mapping	Parallel branches with struct field routing

The compose layer handles type checking, stream conversion between nodes, concurrency, callback injection, and option distribution automatically.

-> Use

/eino-compose

for building graphs, chains, workflows, streaming, callbacks, and state management.

三个用于将组件组装为可执行流水线的API。全部会编译为

Runnable[I, O]

，支持四种执行模式（Invoke、Stream、Collect、Transform）。

API	拓扑结构	使用场景
Graph	有向图，支持循环	含分支、循环的复杂流程（例如ReAct模式）
Chain	线性顺序	简单流水线（例如模板 -> 模型）
Workflow	支持字段级映射的DAG	带结构体字段路由的并行分支

编排层会自动处理类型检查、节点间的流转换、并发、回调注入和选项分发。

-> 如需构建图、链、工作流、流式处理、回调和状态管理，请使用

/eino-compose

。

ADK (Agent Development Kit)

ADK（Agent开发套件）

High-level abstractions for building AI agents. Encapsulates the model-tool-loop pattern.

Concept	What It Does
ChatModelAgent	ReAct-style agent: model generates, calls tools, loops until done
DeepAgent	Pre-built agent with filesystem backend, tool search, summarization
Runner	Executes agents, manages checkpoints, emits event streams
Middleware (Handlers)	Intercept and extend agent behavior (filesystem, summarization, plan-task, etc.)
Interrupt/Resume	Human-in-the-loop: pause agent, get user input, resume from checkpoint
AgentAsTool	Wrap an agent as a tool callable by another agent

-> Use

/eino-agent

for building agents, configuring middleware, runners, and human-in-the-loop.

用于构建AI Agent的高层抽象，封装了模型-工具-循环模式。

概念	功能
ChatModelAgent	ReAct风格Agent：模型生成内容、调用工具、循环直到任务完成
DeepAgent	预构建Agent，支持文件系统后端、工具搜索、摘要生成
Runner	执行Agent、管理检查点、输出事件流
Middleware (Handlers)	拦截并扩展Agent行为（文件系统、摘要、规划任务等）
Interrupt/Resume	人在回路：暂停Agent、获取用户输入、从检查点恢复执行
AgentAsTool	将Agent包装为工具，可供其他Agent调用

-> 如需构建Agent、配置中间件、运行器和人在回路能力，请使用

/eino-agent

。

Schema

Shared data types used across all layers:

```
schema.Message
```
-- Conversation message (system/user/assistant/tool roles, content, tool calls)
```
schema.Document
```
-- Document with content, metadata, and vector embeddings
```
schema.ToolInfo
```
-- Tool description with JSON schema parameters

schema.StreamReader[T]

-- Generic streaming reader (always

defer stream.Close()

)

所有层共用的共享数据类型：

```
schema.Message
```
-- 会话消息（系统/用户/助手/工具角色、内容、工具调用）
```
schema.Document
```
-- 包含内容、元数据和向量嵌入的文档
```
schema.ToolInfo
```
-- 带JSON schema参数的工具描述

schema.StreamReader[T]

-- 通用流式读取器（始终执行

defer stream.Close()

）

Repositories

代码仓库

Repository	Role
`github.com/cloudwego/eino`	Core: interfaces, schema, compose engine, ADK, callbacks
`github.com/cloudwego/eino-ext`	Implementations: model providers, vector stores, tools, callback handlers

仓库	作用
`github.com/cloudwego/eino`	核心库：接口、Schema、编排引擎、ADK、回调
`github.com/cloudwego/eino-ext`	实现库：模型提供商、向量存储、工具、回调处理器

Packages at a Glance

包速览

eino (core):

Package	Contains
`schema`	Message, Document, ToolInfo, StreamReader
`components/model`	ChatModel interfaces
`components/tool`	Tool interfaces (BaseTool, InvokableTool, StreamableTool, Enhanced variants)
`components/embedding`	Embedder interface
`components/retriever`	Retriever interface
`components/indexer`	Indexer interface
`components/document`	Loader, Transformer interfaces
`components/prompt`	ChatTemplate interface
`compose`	Graph, Chain, Workflow, ToolsNode, Runnable, state, checkpoint
`callbacks`	Handler interface, global/per-run registration
`adk`	Agent, Runner, ChatModelAgent, middleware, interrupt/resume
`adk/prebuilt/deep`	DeepAgent preset

eino-ext (implementations):

Package	Contains
`components/model/{provider}`	ChatModel implementations (openai, claude, gemini, ark, ollama, deepseek, qwen, etc.)
`components/embedding/{provider}`	Embedding implementations (openai, ark, ollama, etc.)
`components/retriever/{backend}`	Retriever implementations (redis, milvus2, es8, qdrant)
`components/indexer/{backend}`	Indexer implementations (redis, milvus2, es8, qdrant)
`components/tool/{type}`	Tool implementations (mcp, googlesearch, duckduckgo, bingsearch, etc.)
`callbacks/{provider}`	Callback handlers (cozeloop, apmplus, langfuse, langsmith)
`adk/backend/local`	Local filesystem Backend for DeepAgent

eino（核心库）：

包	包含内容
`schema`	Message、Document、ToolInfo、StreamReader
`components/model`	ChatModel 接口
`components/tool`	Tool 接口（BaseTool、InvokableTool、StreamableTool、增强变体）
`components/embedding`	Embedder 接口
`components/retriever`	Retriever 接口
`components/indexer`	Indexer 接口
`components/document`	Loader、Transformer 接口
`components/prompt`	ChatTemplate 接口
`compose`	Graph、Chain、Workflow、ToolsNode、Runnable、状态、检查点
`callbacks`	Handler 接口、全局/单次运行注册
`adk`	Agent、Runner、ChatModelAgent、中间件、中断/恢复
`adk/prebuilt/deep`	DeepAgent 预设

eino-ext（实现库）：

包	包含内容
`components/model/{provider}`	ChatModel 实现（openai、claude、gemini、ark、ollama、deepseek、qwen等）
`components/embedding/{provider}`	Embedding 实现（openai、ark、ollama等）
`components/retriever/{backend}`	Retriever 实现（redis、milvus2、es8、qdrant）
`components/indexer/{backend}`	Indexer 实现（redis、milvus2、es8、qdrant）
`components/tool/{type}`	Tool 实现（mcp、googlesearch、duckduckgo、bingsearch等）
`callbacks/{provider}`	回调处理器（cozeloop、apmplus、langfuse、langsmith）
`adk/backend/local`	DeepAgent 用的本地文件系统后端

Choosing Your Approach

方案选择

Scenario	Approach	Skill
Single model call (generate or stream)	Use ChatModel directly	`/eino-component`
Multi-turn agent with tools	ChatModelAgent + Runner	`/eino-agent`
Production agent with filesystem, tool search	DeepAgent	`/eino-agent`
Linear pipeline (template -> model)	Chain	`/eino-compose`
Complex flow with branching or loops	Graph	`/eino-compose`
Parallel branches with field mapping	Workflow	`/eino-compose`
RAG (embed + index + retrieve)	Indexer + Retriever + Embedding	`/eino-component`
Agent with human approval	Interrupt/Resume + Runner	`/eino-agent`
Observability and tracing	Callback handlers	`/eino-component`

场景	方案	技能
单次模型调用（生成或流式输出）	直接使用ChatModel	`/eino-component`
带工具的多轮Agent	ChatModelAgent + Runner	`/eino-agent`
带文件系统、工具搜索的生产级Agent	DeepAgent	`/eino-agent`
线性流水线（模板 -> 模型）	Chain	`/eino-compose`
带分支或循环的复杂流程	Graph	`/eino-compose`
带字段映射的并行分支	Workflow	`/eino-compose`
RAG（嵌入 + 索引 + 检索）	Indexer + Retriever + Embedding	`/eino-component`
需人工审批的Agent	Interrupt/Resume + Runner	`/eino-agent`
可观测性与链路追踪	回调处理器	`/eino-component`

Reference Files

参考文件

```
reference/schema.md
```
-- Core data types shared across all layers: Message, Document, ToolInfo, StreamReader
```
reference/runnable.md
```
-- Runnable[I, O] interface, four execution modes, runtime options
```
reference/quick-start.md
```
-- Three complete working examples (ChatModel, Agent+Runner, Chain)

```
reference/schema.md
```
-- 所有层共用的核心数据类型：Message、Document、ToolInfo、StreamReader
```
reference/runnable.md
```
-- Runnable[I, O]接口、四种执行模式、运行时选项
```
reference/quick-start.md
```
-- 三个完整可运行示例（ChatModel、Agent+Runner、Chain）

Instructions to Agent

给Agent的指令

Route to the appropriate skill (
```
/eino-component
```
,
```
/eino-compose
```
,
```
/eino-agent
```
) when the question is specific. Consult the "Choosing Your Approach" table.
Always provide Go code examples using real import paths from
```
github.com/cloudwego/eino
```
and
```
github.com/cloudwego/eino-ext
```
.
For component implementation details, always read the provider's reference file before generating code. Do not assume constructor or config naming conventions.
Prefer ADK (ChatModelAgent + Runner) for agent use cases over manually building ReAct loops with compose graphs.
When showing streaming code, always include
```
defer stream.Close()
```
.

当问题具体时，路由到合适的技能（
```
/eino-component
```
、
```
/eino-compose
```
、
```
/eino-agent
```
），请参考“方案选择”表格。
始终提供使用
```
github.com/cloudwego/eino
```
和
```
github.com/cloudwego/eino-ext
```
真实导入路径的Go代码示例。
对于组件实现细节，生成代码前请务必阅读提供商的参考文件，不要假设构造函数或配置的命名规则。
Agent使用场景优先选择ADK（ChatModelAgent + Runner），而不是用编排图手动构建ReAct循环。
展示流式代码时，始终包含
```
defer stream.Close()
```
。