eino-guide

Eino フレームワークガイド

Eino（「アイノー」と発音します）は、LLM アプリケーションを構築するための Go フレームワークです。

コアコンセプト

コンポーネント

AI の機能を提供する標準化されたインターフェースです。各インターフェースには、相互に置き換え可能な実装が複数あります。

コンポーネント	機能	主なインターフェース
ChatModel	LLM 推論（生成／ストリーミング）	model.BaseChatModel、model.ToolCallingChatModel
Tool	モデルが呼び出せる関数	tool.InvokableTool、tool.EnhancedInvokableTool
Embedding	テキストからベクトルへの変換	embedding.Embedder
Retriever	ベクトル／キーワード検索	retriever.Retriever
Indexer	ベクトル付きドキュメントの保存	indexer.Indexer
ChatTemplate	変数を使ったプロンプトのフォーマット	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 を使用してください。

オーケストレーション（Compose）

コンポーネントを実行可能なパイプラインにつなぐための 3 つの API です。すべて Runnable[I, O] にコンパイルされ、4 つの実行モード（Invoke、Stream、Collect、Transform）を備えています。

API	トポロジー	使用場面
Graph	循環をサポートする有向グラフ	分岐やループを含む複雑なフロー（例：ReAct パターン）
Chain	線形の逐次処理	シンプルなパイプライン（例：テンプレート -> モデル）
Workflow	フィールド単位のマッピングを行う DAG	構造体のフィールドに基づいて分岐を並列実行する場合

Compose レイヤーは、型チェック、ノード間のストリーム変換、並行処理、コールバックの注入、オプションの配布を自動的に処理します。

-> グラフ、チェーン、ワークフロー、ストリーミング、コールバック、状態管理の構築には /eino-compose を使用してください。

ADK（Agent Development Kit）

AI エージェントを構築するための高レベルな抽象化です。モデルとツールを組み合わせたループのパターンをカプセル化します。

概念	機能
ChatModelAgent	ReAct スタイルのエージェント：モデルが生成し、ツールを呼び出し、完了するまでループします
DeepAgent	ファイルシステムバックエンド、ツール検索、要約機能を備えた事前構築済みエージェント
Runner	エージェントを実行し、チェックポイントを管理し、イベントストリームを出力します
Middleware (Handlers)	エージェントの動作をインターセプトして拡張します（ファイルシステム、要約、計画・タスクなど）
Interrupt/Resume	人間参加型の処理：エージェントを一時停止し、ユーザー入力を受け取り、チェックポイントから再開します
AgentTool	エージェントを、別のエージェントが呼び出せるツールとしてラップします

-> エージェントの構築、ミドルウェアやランナーの設定、人間参加型の処理には /eino-agent を使用してください。

スキーマ

すべてのレイヤーで共有されるデータ型です。

• schema.Message -- 会話メッセージ（system/user/assistant/tool の各ロール、コンテンツ、ツール呼び出し）
• schema.Document -- コンテンツ、メタデータ、ベクトル埋め込みを含むドキュメント
• schema.ToolInfo -- JSON スキーマ形式のパラメーターを含むツールの説明
• schema.StreamReader[T] -- 汎用ストリーミングリーダー（必ず defer stream.Close() を使用してください）

リポジトリ

リポジトリ	役割
github.com/cloudwego/eino	コア：インターフェース、スキーマ、Compose エンジン、ADK、コールバック
github.com/cloudwego/eino-ext	実装：モデルプロバイダー、ベクトルストア、ツール、コールバックハンドラー

パッケージの概要

eino（コア）：

パッケージ	含まれるもの
schema	Message、Document、ToolInfo、StreamReader
components/model	ChatModel および AgenticModel インターフェース
components/tool	Tool インターフェース（BaseTool、InvokableTool、StreamableTool、Enhanced 系）
components/embedding	Embedder インターフェース
components/retriever	Retriever インターフェース
components/indexer	Indexer インターフェース
components/document	Loader、Transformer インターフェース
components/prompt	ChatTemplate インターフェース
compose	Graph、Chain、Workflow、ToolsNode、Runnable、state、checkpoint
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}	Callback ハンドラー（cozeloop、apmplus、langfuse、langsmith）
adk/backend/local	DeepAgent 向けローカルファイルシステム Backend

アプローチの選択

シナリオ	アプローチ	スキル
単一のモデル呼び出し（生成またはストリーミング）	ChatModel を直接使用	/eino-component
ツールを使う複数ターンのエージェント	ChatModelAgent + Runner	/eino-agent
ファイルシステムやツール検索を使う本番向けエージェント	DeepAgent	/eino-agent
直線的なパイプライン（template -> model）	Chain	/eino-compose
分岐やループを含む複雑なフロー	Graph	/eino-compose
フィールドマッピングを使う並列分岐	Workflow	/eino-compose
RAG（埋め込み + インデックス作成 + 検索）	Indexer + Retriever + Embedding	/eino-component
人間による承認が必要なエージェント	Interrupt/Resume + Runner	/eino-agent
可観測性とトレーシング	Callback ハンドラー	/eino-component

参考ファイル

• reference/schema.md -- すべてのレイヤーで共有されるコアデータ型：Message、Document、ToolInfo、StreamReader
• reference/runnable.md -- Runnable[I, O] インターフェース、4 つの実行モード、ランタイムオプション
• reference/quick-start.md -- 3 つの完全な動作例（ChatModel、Agent+Runner、Chain）

エージェントへの指示

1. 質問が具体的な場合は、適切なスキル（/eino-component、/eino-compose、/eino-agent）に誘導してください。「アプローチの選択」テーブルを参照してください。
2. github.com/cloudwego/eino および github.com/cloudwego/eino-ext の実際のインポートパスを使った Go コード例を必ず提示してください。
3. コンポーネントの実装詳細についてコードを生成する前に、必ずプロバイダーの参考ファイルを読んでください。コンストラクターや設定の命名規則を推測しないでください。
4. エージェントのユースケースでは、compose グラフを使って ReAct ループを手動で構築するより、ADK（ChatModelAgent + Runner）を優先してください。プリエンプションとライフサイクル管理が必要な、対話型の複数ターンアプリケーションには TurnLoop を推奨してください。
5. ストリーミングコードを示す場合は、必ず defer stream.Close() を含めてください。