eino-guide

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 embeddings
• schema.ToolInfo -- Tool description with JSON schema parameters
• schema.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, 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)

Instructions to Agent

1. Route to the appropriate skill (/eino-component, /eino-compose, /eino-agent) when the question is specific. Consult the "Choosing Your Approach" table.
2. Always provide Go code examples using real import paths from github.com/cloudwego/eino and github.com/cloudwego/eino-ext.
3. For component implementation details, always read the provider's reference file before generating code. Do not assume constructor or config naming conventions.
4. 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.
5. When showing streaming code, always include defer stream.Close().