Eino Component Guide

Component Selection Guide

ChatModel -- LLM inference (classic Message path)

AgenticModel -- LLM inference (AgenticMessage path)

AgenticModel operates on *schema.AgenticMessage with block-based content (reasoning, text, images, audio, video, tool calls/results). Tools are always passed at call time via model.WithTools option (no WithTools method).

Detailed configuration references:

• reference/model/agenticopenai.md
• reference/model/agenticgemini.md
• reference/model/agenticdeepseek.md
• reference/model/agenticark.md
• reference/model/agenticqwen.md

Embedding -- text to vector

Retriever -- vector/keyword search

Indexer -- store documents with vectors

Tools -- model-callable functions

Interface Quick Reference

// BaseModel (generic)
type BaseModel[M any] interface {
    Generate(ctx context.Context, input []M, opts ...Option) (M, error)
    Stream(ctx context.Context, input []M, opts ...Option) (*schema.StreamReader[M], error)
}

// Type aliases
type BaseChatModel = BaseModel[*schema.Message]       // classic path
type AgenticModel = BaseModel[*schema.AgenticMessage] // agentic path

// ToolCallingChatModel (classic path, adds WithTools)
type ToolCallingChatModel interface {
    BaseChatModel
    WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
}

// Embedding
type Embedder interface {
    EmbedStrings(ctx context.Context, texts []string, opts ...Option) ([][]float64, error)
}

// Retriever
type Retriever interface {
    Retrieve(ctx context.Context, query string, opts ...Option) ([]*schema.Document, error)
}

// Indexer
type Indexer interface {
    Store(ctx context.Context, docs []*schema.Document, opts ...Option) (ids []string, err error)
}

// Document
type Loader interface {
    Load(ctx context.Context, src Source, opts ...LoaderOption) ([]*schema.Document, error)
}
type Transformer interface {
    Transform(ctx context.Context, src []*schema.Document, opts ...TransformerOption) ([]*schema.Document, error)
}

// Tool
type BaseTool interface {
    Info(ctx context.Context) (*schema.ToolInfo, error)
}

type InvokableTool interface {
    BaseTool
    InvokableRun(ctx context.Context, argumentsInJSON string, opts ...Option) (string, error)
}

// Prompt
type ChatTemplate interface {
    Format(ctx context.Context, vs map[string]any, opts ...Option) ([]*schema.Message, error)
}

Installation

go get github.com/cloudwego/eino-ext/components/{type}/{impl}@latest
# Examples:
go get github.com/cloudwego/eino-ext/components/model/openai@latest
go get github.com/cloudwego/eino-ext/components/model/agenticopenai@latest
go get github.com/cloudwego/eino-ext/components/retriever/milvus2@latest
go get github.com/cloudwego/eino-ext/components/tool/mcp@latest

ChatModel Usage (Classic Path)

Generate

resp, err := chatModel.Generate(ctx, []*schema.Message{
    {Role: schema.User, Content: "Hello"},
})
fmt.Println(resp.Content)

Stream

reader, err := chatModel.Stream(ctx, messages)
defer reader.Close()
for {
    chunk, err := reader.Recv()
    if errors.Is(err, io.EOF) { break }
    if err != nil { return err }
    fmt.Print(chunk.Content)
}

Tool Calling

withTools, err := chatModel.WithTools([]*schema.ToolInfo{toolInfo})
resp, err := withTools.Generate(ctx, messages)
// resp.ToolCalls contains model's tool invocations

AgenticModel Usage

import (
    "github.com/cloudwego/eino-ext/components/model/agenticopenai"
    "github.com/cloudwego/eino/components/model"
    "github.com/cloudwego/eino/schema"
)

// Create agentic model
am, _ := agenticopenai.New(ctx, &agenticopenai.Config{
    Model:  "gpt-4o",
    APIKey: "your-key",
})

// Tools passed at call time via option for AgenticModel-interface code
resp, err := am.Generate(ctx,
    []*schema.AgenticMessage{schema.UserAgenticMessage("Search for Go tutorials")},
    model.WithTools(toolInfos),
)

// Response contains typed ContentBlocks
for _, block := range resp.ContentBlocks {
    switch block.Type {
    case schema.ContentBlockTypeAssistantGenText:
        fmt.Println(block.AssistantGenText.Text)
    case schema.ContentBlockTypeFunctionToolCall:
        fmt.Printf("Tool call: %s(%s)\n", block.FunctionToolCall.Name, block.FunctionToolCall.Arguments)
    case schema.ContentBlockTypeReasoning:
        fmt.Printf("Reasoning: %s\n", block.Reasoning.Text)
    }
}

RAG Components

Embedding + Indexer + Retriever form the RAG pipeline:

// 1. Embed and store documents
indexer, _ := redisIndexer.NewIndexer(ctx, &redisIndexer.IndexerConfig{
    Client: redisClient, KeyPrefix: "doc:", Embedding: embedder,
})
ids, _ := indexer.Store(ctx, docs)

// 2. Retrieve relevant documents
retriever, _ := redisRetriever.NewRetriever(ctx, &redisRetriever.RetrieverConfig{
    Client: redisClient, Index: "my_index", Embedding: embedder,
})
docs, _ := retriever.Retrieve(ctx, "user query", retriever.WithTopK(5))

Tool Usage

MCP Tools

import mcpp "github.com/cloudwego/eino-ext/components/tool/mcp"

tools, err := mcpp.GetTools(ctx, &mcpp.Config{Cli: mcpClient})

Custom InvokableTool

Implement Info() and InvokableRun() to create a custom tool.

Instructions to Agent

• Constructor signatures and Config struct names vary across implementations. Always read the provider's reference file in reference/{type}/{impl}.md before generating initialization code.
• Use BaseChatModel (classic path) or AgenticModel (agentic path) based on the user's needs.
• model.AgenticModel does not add a WithTools method to the interface. Prefer model.WithTools(...) at call time for interface-oriented code.
• For ADK agents, the ChatModelAgentConfig.Model field accepts model.BaseModel[M] -- both paths work seamlessly.
• For RAG, ensure the same Embedder model is used for both indexing and retrieval.
• See reference files for detailed per-component documentation.

Reference Files

Read files on-demand for detailed API, config, and examples. Each {type}/ directory contains an overview.md (interfaces + common patterns) and per-implementation files:

• reference/model/*.md -- ChatModel and AgenticModel interfaces, tool binding, streaming, and per-provider config (openai, claude, gemini, ark, ollama, deepseek, qwen, qianfan, openrouter)
• reference/embedding/*.md -- Embedder interface and per-provider config (openai, ark, ollama, etc.)
• reference/retriever/*.md -- Retriever interface, RAG example, and per-backend config (redis, milvus2, es8)
• reference/indexer/*.md -- Indexer interface, indexing pipeline, and per-backend config (redis, milvus2, es8, qdrant)
• reference/tool/*.md -- Tool interfaces, custom tool creation, MCP integration, search tools, utility tools
• reference/document/pipeline.md -- Loader, Parser, Transformer interfaces and full pipeline example
• reference/prompt.md -- ChatTemplate, FString/GoTemplate/Jinja2 formats, message helpers
• reference/callback/*.md -- Callback handler interface, registration patterns, and per-provider config (cozeloop, apmplus, langfuse, langsmith)