Eino Framework Guide
Eino (pronounced "i know") is a Go framework for building LLM applications.
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.
Orchestration (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.
ADK (Agent Development Kit)
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 |
| AgentTool |
Wrap an agent as a tool callable by another agent |
-> Use /eino-agent for building agents, configuring middleware, runners, and human-in-the-loop.
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 embeddingsschema.ToolInfo -- Tool description with JSON schema parametersschema.StreamReader[T] -- Generic streaming reader (always 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 |
Packages at a Glance
eino (core):
| Package |
Contains |
schema |
Message, Document, ToolInfo, StreamReader |
components/model |
ChatModel and AgenticModel 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 |
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 |
Reference Files
reference/schema.md -- Core data types shared across all layers: Message, Document, ToolInfo, StreamReaderreference/runnable.md -- Runnable[I, O] interface, four execution modes, runtime optionsreference/quick-start.md -- Three complete working examples (ChatModel, Agent+Runner, Chain)
Instructions to 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. For interactive multi-turn applications needing preemption and lifecycle management, recommend TurnLoop.
- When showing streaming code, always include
defer stream.Close().
1---2name: eino-guide3description: Eino framework overview, concepts, and navigation. Use when a user asks general questions about Eino, needs help getting started, wants to understand the architecture, or is unsure which Eino skill to use. Eino is a Go framework for building LLM applications with components, orchestration graphs, and an agent development kit.4---56# Eino Framework Guide78Eino (pronounced "i know") is a Go framework for building LLM applications.910## Core Concepts1112### Component1314Standardized interfaces for AI capabilities. Each interface has multiple interchangeable implementations.1516| Component | What It Does | Key Interface |17|-----------|-------------|---------------|18| ChatModel | LLM inference (generate / stream) | `model.BaseChatModel`, `model.ToolCallingChatModel` |19| Tool | Functions the model can call | `tool.InvokableTool`, `tool.EnhancedInvokableTool` |20| Embedding | Text to vector | `embedding.Embedder` |21| Retriever | Vector/keyword search | `retriever.Retriever` |22| Indexer | Store documents with vectors | `indexer.Indexer` |23| ChatTemplate | Prompt formatting with variables | `prompt.ChatTemplate` |24| Document Loader/Transformer | Load and process documents | `document.Loader`, `document.Transformer` |25| Callback Handler | Observability and tracing | `callbacks.Handler` |2627Implementations live in `eino-ext` (OpenAI, Claude, Gemini, Ark, Ollama, Milvus, Redis, Elasticsearch, etc.).2829-> Use `/eino-component` for selecting, configuring, and using components.3031### Orchestration (Compose)3233Three APIs for wiring components into executable pipelines. All compile to a `Runnable[I, O]` with four execution modes (Invoke, Stream, Collect, Transform).3435| API | Topology | When to Use |36|-----|----------|-------------|37| **Graph** | Directed graph, supports cycles | Complex flows with branching, loops (e.g., ReAct pattern) |38| **Chain** | Linear sequential | Simple pipelines (e.g., template -> model) |39| **Workflow** | DAG with field-level mapping | Parallel branches with struct field routing |4041The compose layer handles type checking, stream conversion between nodes, concurrency, callback injection, and option distribution automatically.4243-> Use `/eino-compose` for building graphs, chains, workflows, streaming, callbacks, and state management.4445### ADK (Agent Development Kit)4647High-level abstractions for building AI agents. Encapsulates the model-tool-loop pattern.4849| Concept | What It Does |50|---------|-------------|51| **ChatModelAgent** | ReAct-style agent: model generates, calls tools, loops until done |52| **DeepAgent** | Pre-built agent with filesystem backend, tool search, summarization |53| **Runner** | Executes agents, manages checkpoints, emits event streams |54| **Middleware (Handlers)** | Intercept and extend agent behavior (filesystem, summarization, plan-task, etc.) |55| **Interrupt/Resume** | Human-in-the-loop: pause agent, get user input, resume from checkpoint |56| **AgentTool** | Wrap an agent as a tool callable by another agent |5758-> Use `/eino-agent` for building agents, configuring middleware, runners, and human-in-the-loop.5960### Schema6162Shared data types used across all layers:6364- `schema.Message` -- Conversation message (system/user/assistant/tool roles, content, tool calls)65- `schema.Document` -- Document with content, metadata, and vector embeddings66- `schema.ToolInfo` -- Tool description with JSON schema parameters67- `schema.StreamReader[T]` -- Generic streaming reader (always `defer stream.Close()`)6869## Repositories7071| Repository | Role |72|---|---|73| `github.com/cloudwego/eino` | Core: interfaces, schema, compose engine, ADK, callbacks |74| `github.com/cloudwego/eino-ext` | Implementations: model providers, vector stores, tools, callback handlers |7576## Packages at a Glance7778**eino (core):**7980| Package | Contains |81|---------|----------|82| `schema` | Message, Document, ToolInfo, StreamReader |83| `components/model` | ChatModel and AgenticModel interfaces |84| `components/tool` | Tool interfaces (BaseTool, InvokableTool, StreamableTool, Enhanced variants) |85| `components/embedding` | Embedder interface |86| `components/retriever` | Retriever interface |87| `components/indexer` | Indexer interface |88| `components/document` | Loader, Transformer interfaces |89| `components/prompt` | ChatTemplate interface |90| `compose` | Graph, Chain, Workflow, ToolsNode, Runnable, state, checkpoint |91| `callbacks` | Handler interface, global/per-run registration |92| `adk` | Agent, Runner, ChatModelAgent, middleware, interrupt/resume |93| `adk/prebuilt/deep` | DeepAgent preset |9495**eino-ext (implementations):**9697| Package | Contains |98|---------|----------|99| `components/model/{provider}` | ChatModel implementations (openai, claude, gemini, ark, ollama, deepseek, qwen, etc.) |100| `components/embedding/{provider}` | Embedding implementations (openai, ark, ollama, etc.) |101| `components/retriever/{backend}` | Retriever implementations (redis, milvus2, es8, qdrant) |102| `components/indexer/{backend}` | Indexer implementations (redis, milvus2, es8, qdrant) |103| `components/tool/{type}` | Tool implementations (mcp, googlesearch, duckduckgo, bingsearch, etc.) |104| `callbacks/{provider}` | Callback handlers (cozeloop, apmplus, langfuse, langsmith) |105| `adk/backend/local` | Local filesystem Backend for DeepAgent |106107## Choosing Your Approach108109| Scenario | Approach | Skill |110|----------|----------|-------|111| Single model call (generate or stream) | Use ChatModel directly | `/eino-component` |112| Multi-turn agent with tools | ChatModelAgent + Runner | `/eino-agent` |113| Production agent with filesystem, tool search | DeepAgent | `/eino-agent` |114| Linear pipeline (template -> model) | Chain | `/eino-compose` |115| Complex flow with branching or loops | Graph | `/eino-compose` |116| Parallel branches with field mapping | Workflow | `/eino-compose` |117| RAG (embed + index + retrieve) | Indexer + Retriever + Embedding | `/eino-component` |118| Agent with human approval | Interrupt/Resume + Runner | `/eino-agent` |119| Observability and tracing | Callback handlers | `/eino-component` |120121## Reference Files122123- `reference/schema.md` -- Core data types shared across all layers: Message, Document, ToolInfo, StreamReader124- `reference/runnable.md` -- Runnable[I, O] interface, four execution modes, runtime options125- `reference/quick-start.md` -- Three complete working examples (ChatModel, Agent+Runner, Chain)126127## Instructions to Agent1281291. Route to the appropriate skill (`/eino-component`, `/eino-compose`, `/eino-agent`) when the question is specific. Consult the "Choosing Your Approach" table.1302. Always provide Go code examples using real import paths from `github.com/cloudwego/eino` and `github.com/cloudwego/eino-ext`.1313. For component implementation details, always read the provider's reference file before generating code. Do not assume constructor or config naming conventions.1324. Prefer ADK (ChatModelAgent + Runner) for agent use cases over manually building ReAct loops with compose graphs. For interactive multi-turn applications needing preemption and lifecycle management, recommend TurnLoop.1335. When showing streaming code, always include `defer stream.Close()`.
cloudwego