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.ToolCallingChatModel
|
| Tool | Functions the model can call | , tool.EnhancedInvokableTool
|
| Embedding | Text to vector | |
| Retriever | Vector/keyword search | |
| Indexer | Store documents with vectors | |
| ChatTemplate | Prompt formatting with variables | |
| Document Loader/Transformer | Load and process documents | , |
| Callback Handler | Observability and tracing | |
Implementations live in
(OpenAI, Claude, Gemini, Ark, Ollama, Milvus, Redis, Elasticsearch, etc.).
-> Use
for selecting, configuring, and using components.
Orchestration (Compose)
Three APIs for wiring components into executable pipelines. All compile to a
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
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 |
| AgentAsTool | Wrap an agent as a tool callable by another agent |
-> Use
for building agents, configuring middleware, runners, and human-in-the-loop.
Schema
Shared data types used across all layers:
- -- Conversation message (system/user/assistant/tool roles, content, tool calls)
- -- Document with content, metadata, and vector embeddings
- -- Tool description with JSON schema parameters
- -- Generic streaming reader (always )
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 |
|---|
| Message, Document, ToolInfo, StreamReader |
| ChatModel interfaces |
| Tool interfaces (BaseTool, InvokableTool, StreamableTool, Enhanced variants) |
| Embedder interface |
| Retriever interface |
| Indexer interface |
| Loader, Transformer interfaces |
| ChatTemplate interface |
| Graph, Chain, Workflow, ToolsNode, Runnable, state, checkpoint |
| Handler interface, global/per-run registration |
| Agent, Runner, ChatModelAgent, middleware, interrupt/resume |
| 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) |
| Tool implementations (mcp, googlesearch, duckduckgo, bingsearch, etc.) |
| Callback handlers (cozeloop, apmplus, langfuse, langsmith) |
| Local filesystem Backend for DeepAgent |
Choosing Your Approach
| Scenario | Approach | Skill |
|---|
| Single model call (generate or stream) | Use ChatModel directly | |
| Multi-turn agent with tools | ChatModelAgent + Runner | |
| Production agent with filesystem, tool search | DeepAgent | |
| Linear pipeline (template -> model) | Chain | |
| Complex flow with branching or loops | Graph | |
| Parallel branches with field mapping | Workflow | |
| RAG (embed + index + retrieve) | Indexer + Retriever + Embedding | |
| Agent with human approval | Interrupt/Resume + Runner | |
| Observability and tracing | Callback handlers | |
Reference Files
- -- Core data types shared across all layers: Message, Document, ToolInfo, StreamReader
- -- Runnable[I, O] interface, four execution modes, runtime options
- -- Three complete working examples (ChatModel, Agent+Runner, Chain)
Instructions to Agent
- Route to the appropriate skill (, , ) 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
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 .