# cloudwego/eino architecture

> Architecture diagram of the GitHub repository cloudwego/eino, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudwego/eino
- Repository: https://github.com/cloudwego/eino

## Overview

1. **What this repo is**
   Eino is a Go LLM application framework, not an app. Its architecture is layered: stable domain types at the bottom, reusable component abstractions above that, then orchestration/composition, then agent frameworks and prebuilt agent patterns on top.

2. **Core data model lives in `schema/`**
   `schema` defines the shared language of the framework: messages, documents, tools, and streams, plus serialization helpers. Most higher-level packages pass these types around, so this is the main boundary between framework logic and concrete model/provider implementations.

3. **Component abstraction layer is in `components/`**
   This package family defines interfaces and options for `model`, `tool`, `retriever`, `embedding`, `prompt`, `document`, and `indexer`. These are the pluggable building blocks that external provider packages implement. The repo itself mostly defines contracts and callback hooks, while actual provider implementations are expected to come from `eino-ext`.

4. **Orchestration engine is in `compose/`**
   `compose` is the graph/workflow runtime. It provides nodes, edges, branching, parallel execution, DAGs, state, checkpoints, resume, interrupts, and stream concatenation/copying. This is the deterministic execution layer that can run standalone or be wrapped as a tool for an agent.

5. **Agent runtime is in `adk/`**
   `adk` is the agent development kit. It wires models, tools, flows, and callbacks into executable agents and runners. This is where you find chat-model agents, ReAct execution, retry logic, interrupt/resume support, deterministic transfer, and the runner/handler entry points used to drive agent queries.

6. **Prebuilt agent patterns are in `adk/prebuilt/`**
   The repo ships opinionated higher-level agents such as `deep`, `planexecute`, and `supervisor`. These compose lower-level agent/tool primitives into ready-made patterns for multi-step reasoning, planning, and delegation. They are built on top of `adk` and `compose`, not separate systems.

7. **`flow/` contains specialized application flows**
   `flow/agent` packages agent-specific orchestration helpers, including ReAct and multi-agent host coordination. `flow/retriever` and `flow/indexer` provide retrieval/indexing workflows like parent retrieval, router-based retrieval, and multi-query retrieval. This layer sits between generic composition and concrete application patterns.

8. **Callbacks are a cross-cutting subsystem**
   `callbacks/`, `utils/callbacks/`, and `internal/callbacks/` implement aspect-style injection for start/end/error and stream events. These hooks are used across components, graphs, and agents for logging, tracing, metrics, and other observability behavior without coupling it into business logic.

9. **Persistence and human-in-the-loop support**
   Checkpointing, interrupt, and resume are first-class in `compose` and `adk`, with storage/backends under `adk/filesystem` and related middleware. This is the stateful boundary that enables pausing execution, storing progress, and continuing later with preserved context.

10. **Middlewares extend agent/component behavior**
   `adk/middlewares/` contains reusable behavior modifiers such as filesystem handling, tool-call patching, dynamic tool search, task planning, reduction, skill injection, and summarization. These sit between the agent loop and underlying tools/models, usually transforming prompts, tool results, or task state.

11. **Internal packages hold shared engine utilities**
   `internal/` contains concurrency-safe helpers, serialization, generic utilities, stream/channel primitives, panic protection, and mocks. These packages are intentionally not part of the public architecture; they support the framework internals and tests.

12. **Overall data flow**
   Typical execution starts with a `schema` input, flows through a `components` implementation such as a chat model or retriever, is orchestrated by `compose` or `adk`, and is observed by callbacks. If the path includes tools or multi-step reasoning, the same flow may branch into subgraphs, task middleware, checkpoints, and resume points before producing a final `schema` output or stream.

13. **Repository boundary**
   This repo defines the framework, contracts, orchestration, and built-in agent patterns. Provider integrations, concrete LLM/tool backends, and many real-world examples are intentionally externalized to companion repos such as `eino-ext` and `eino-examples`.

Main entry points: [`compose/graph.go`](https://github.com/cloudwego/eino/blob/main/compose/graph.go) (Graph runtime), [`adk/react.go`](https://github.com/cloudwego/eino/blob/main/adk/react.go) (Agent runtime), [`schema`](https://github.com/cloudwego/eino/tree/main/schema) (Schema), [`callbacks`](https://github.com/cloudwego/eino/tree/main/callbacks) (Callbacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core model"]
  node_schema["Schema<br/>domain types"]
end

subgraph group_components["Components"]
  node_components_model["Model<br/>LLM contract"]
  node_components_tool["Tool"]
  node_components_retriever["Retriever<br/>retrieval contract"]
  node_components_embedding["Embedding<br/>vector contract"]
  node_components_prompt["Prompt<br/>template contract"]
  node_components_document["Document"]
  node_components_indexer["Indexer<br/>indexing contract"]
end

subgraph group_compose["Orchestration"]
  node_compose_graph["Graph runtime<br/>workflow engine<br/>[graph.go]"]
  node_compose_state["State & resume<br/>stateful runtime<br/>[state.go]"]
  node_compose_workflow["Workflow<br/>composition API<br/>[workflow.go]"]
  node_compose_stream["Streams<br/>stream plumbing<br/>[stream_concat.go]"]
end

subgraph group_adk["Agents"]
  node_adk_agent["Agent runtime<br/>agent loop<br/>[react.go]"]
  node_adk_runner["Runner<br/>execution entrypoint<br/>[runner.go]"]
  node_adk_middlewares["Middlewares<br/>behavior modifiers"]
  node_adk_prebuilt["Prebuilt agents<br/>opinionated patterns"]
end

subgraph group_flow["Specialized flows"]
  node_flow_agent["Agent flows<br/>flow helpers"]
  node_flow_retriever["Retriever flows<br/>retrieval flow"]
  node_flow_indexer["Indexer flows<br/>indexing flow"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_callbacks["Callbacks<br/>observability hooks"]
end

subgraph group_internal["Internal"]
  node_internal["Internal utils<br/>private support"]
end

node_schema -->|"types"| node_components_model
node_schema -->|"types"| node_components_tool
node_schema -->|"types"| node_components_retriever
node_schema -->|"types"| node_components_document
node_components_model -->|"run"| node_compose_graph
node_components_tool -->|"tool nodes"| node_compose_graph
node_components_retriever -->|"source"| node_flow_retriever
node_components_embedding -->|"embed"| node_flow_indexer
node_components_document -->|"parse"| node_flow_indexer
node_components_indexer -->|"index"| node_flow_indexer
node_compose_graph -->|"checkpoint"| node_compose_state
node_compose_graph -->|"stream"| node_compose_stream
node_compose_workflow -->|"builds on"| node_compose_graph
node_adk_agent -->|"calls"| node_components_model
node_adk_agent -->|"uses"| node_components_tool
node_adk_agent -->|"orchestrates"| node_compose_graph
node_adk_runner -->|"drives"| node_adk_agent
node_adk_agent -->|"extends"| node_adk_middlewares
node_adk_prebuilt -->|"packages"| node_adk_agent
node_adk_prebuilt -->|"composes"| node_compose_graph
node_flow_agent -->|"supports"| node_adk_agent
node_flow_agent -->|"coordinates"| node_compose_graph
node_flow_retriever -->|"wraps"| node_components_retriever
node_flow_indexer -->|"wraps"| node_components_indexer
node_callbacks -->|"observes"| node_components_model
node_callbacks -->|"observes"| node_compose_graph
node_callbacks -->|"observes"| node_adk_agent
node_internal -->|"supports"| node_callbacks
node_internal -->|"supports"| node_compose_state
node_internal -->|"supports"| node_adk_runner

click node_schema "https://github.com/cloudwego/eino/tree/main/schema"
click node_components_model "https://github.com/cloudwego/eino/tree/main/components/model"
click node_components_tool "https://github.com/cloudwego/eino/tree/main/components/tool"
click node_components_retriever "https://github.com/cloudwego/eino/tree/main/components/retriever"
click node_components_embedding "https://github.com/cloudwego/eino/tree/main/components/embedding"
click node_components_prompt "https://github.com/cloudwego/eino/tree/main/components/prompt"
click node_components_document "https://github.com/cloudwego/eino/tree/main/components/document"
click node_components_indexer "https://github.com/cloudwego/eino/tree/main/components/indexer"
click node_compose_graph "https://github.com/cloudwego/eino/blob/main/compose/graph.go"
click node_compose_state "https://github.com/cloudwego/eino/blob/main/compose/state.go"
click node_compose_workflow "https://github.com/cloudwego/eino/blob/main/compose/workflow.go"
click node_compose_stream "https://github.com/cloudwego/eino/blob/main/compose/stream_concat.go"
click node_adk_agent "https://github.com/cloudwego/eino/blob/main/adk/react.go"
click node_adk_runner "https://github.com/cloudwego/eino/blob/main/adk/runner.go"
click node_adk_middlewares "https://github.com/cloudwego/eino/tree/main/adk/middlewares"
click node_adk_prebuilt "https://github.com/cloudwego/eino/tree/main/adk/prebuilt"
click node_flow_agent "https://github.com/cloudwego/eino/tree/main/flow/agent"
click node_flow_retriever "https://github.com/cloudwego/eino/tree/main/flow/retriever"
click node_flow_indexer "https://github.com/cloudwego/eino/tree/main/flow/indexer"
click node_callbacks "https://github.com/cloudwego/eino/tree/main/callbacks"
click node_internal "https://github.com/cloudwego/eino/tree/main/internal"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema,node_internal toneBlue
class node_components_model,node_components_tool,node_components_retriever,node_components_embedding,node_components_prompt,node_components_document,node_components_indexer toneAmber
class node_compose_graph,node_compose_state,node_compose_workflow,node_compose_stream toneMint
class node_adk_agent,node_adk_runner,node_adk_middlewares,node_adk_prebuilt toneRose
class node_flow_agent,node_flow_retriever,node_flow_indexer toneIndigo
class node_callbacks toneTeal
```

## Components

### Core model

Shared framework types and serialization boundary

- [Schema](https://github.com/cloudwego/eino/tree/main/schema): domain types · Shared messages, documents, tools, streams, and serialization helpers · `schema`

### Components

Pluggable contracts for providers and adapters

- [Model](https://github.com/cloudwego/eino/tree/main/components/model): LLM contract · Chat-model interfaces, options, and callback hooks · `components/model`
- [Tool](https://github.com/cloudwego/eino/tree/main/components/tool): tool contract · Tool interfaces, interrupt handling, and tool options · `components/tool`
- [Retriever](https://github.com/cloudwego/eino/tree/main/components/retriever): retrieval contract · Retriever interfaces and configuration for pluggable backends · `components/retriever`
- [Embedding](https://github.com/cloudwego/eino/tree/main/components/embedding): vector contract · Embedding interfaces and options · `components/embedding`
- [Prompt](https://github.com/cloudwego/eino/tree/main/components/prompt): template contract · Prompt and chat-template interfaces and options · `components/prompt`
- [Document](https://github.com/cloudwego/eino/tree/main/components/document): document contract · Document parsing and transformation interfaces · `components/document`
- [Indexer](https://github.com/cloudwego/eino/tree/main/components/indexer): indexing contract · Indexing interfaces and configuration · `components/indexer`

### Orchestration

Graph and workflow runtime

- [Graph runtime](https://github.com/cloudwego/eino/blob/main/compose/graph.go): workflow engine · Nodes, edges, branching, parallel execution, and graph execution · `compose/graph.go`
- [State & resume](https://github.com/cloudwego/eino/blob/main/compose/state.go): stateful runtime · Checkpointing, interrupts, resume, and mutable execution state · `compose/state.go`
- [Workflow](https://github.com/cloudwego/eino/blob/main/compose/workflow.go): composition API · Higher-level workflow composition over the graph runtime · `compose/workflow.go`
- [Streams](https://github.com/cloudwego/eino/blob/main/compose/stream_concat.go): stream plumbing · Stream concatenation, readers, and copy helpers · `compose/stream_concat.go`

### Agents

Agent runtime, runners, middlewares, and built-ins

- [Agent runtime](https://github.com/cloudwego/eino/blob/main/adk/react.go): agent loop · Chat-model agents, ReAct execution, retries, and transfer logic · `adk/react.go`
- [Runner](https://github.com/cloudwego/eino/blob/main/adk/runner.go): execution entrypoint · Handlers and runner entry points for driving agent queries · `adk/runner.go`
- [Middlewares](https://github.com/cloudwego/eino/tree/main/adk/middlewares): behavior modifiers · Filesystem, tool patching, planning, reduction, skill, and summarization layers · `adk/middlewares`
- [Prebuilt agents](https://github.com/cloudwego/eino/tree/main/adk/prebuilt): opinionated patterns · Deep, plan-execute, and supervisor agent compositions · `adk/prebuilt`

### Specialized flows

Higher-level retrieval, indexing, and agent flow helpers

- [Agent flows](https://github.com/cloudwego/eino/tree/main/flow/agent): flow helpers · Reusable orchestration helpers for agent execution patterns · `flow/agent`
- [Retriever flows](https://github.com/cloudwego/eino/tree/main/flow/retriever): retrieval flow · Parent, router, and multi-query retrieval workflows · `flow/retriever`
- [Indexer flows](https://github.com/cloudwego/eino/tree/main/flow/indexer): indexing flow · Higher-level indexing workflow helpers · `flow/indexer`

### Cross-cutting

Callbacks and observability hooks

- [Callbacks](https://github.com/cloudwego/eino/tree/main/callbacks): observability hooks · Aspect-style start, end, error, and stream event injection · `callbacks`

### Internal

Private engine utilities and support code

- [Internal utils](https://github.com/cloudwego/eino/tree/main/internal): private support · Concurrency, serialization, safety, and mock support for framework internals · `internal`

## Connections

- Schema → Model: types · Shared message and stream types underpin model contracts
- Schema → Tool: types · Tool calls and tool results use the shared schema language
- Schema → Retriever: types · Retriever inputs and outputs are built on shared schema types
- Schema → Document: types · Document abstractions reuse the schema data model
- Model → Graph runtime: run · Model invocations are orchestrated through graph nodes
- Tool → Graph runtime: tool nodes · Tools can be embedded into composed execution graphs
- Retriever → Retriever flows: source · Retriever implementations feed retrieval workflows
- Embedding → Indexer flows: embed · Embedding backends support indexing workflows
- Document → Indexer flows: parse · Document parsing feeds indexing pipelines
- Indexer → Indexer flows: index · Indexer contracts are used by indexing flows
- Graph runtime → State & resume: checkpoint · Graph execution can pause, resume, and persist state
- Graph runtime → Streams: stream · Graph runtime moves streaming values through the pipeline
- Workflow → Graph runtime: builds on · Workflows compile down to the graph runtime
- Agent runtime → Model: calls · Agents drive chat-model execution through component contracts
- Agent runtime → Tool: uses · Agent loops invoke tools through the tool abstraction
- Agent runtime → Graph runtime: orchestrates · Agents can delegate multi-step execution to composition graphs
- Runner → Agent runtime: drives · Runners and handlers are the outer execution entrypoints
- Agent runtime → Middlewares: extends · Middleware modifies prompts, tools, tasks, and outputs
- Prebuilt agents → Agent runtime: packages · Prebuilt patterns are assembled from the core agent runtime
- Prebuilt agents → Graph runtime: composes · Built-in agent patterns rely on graph/workflow composition
- Agent flows → Agent runtime: supports · Agent flow helpers layer on the agent runtime
- Agent flows → Graph runtime: coordinates · Agent flows coordinate execution with graphs and branches
- Retriever flows → Retriever: wraps · Retrieval flows wrap retriever contracts into application patterns
- Indexer flows → Indexer: wraps · Indexing flows wrap indexer contracts into application patterns
- Callbacks → Model: observes · Callbacks attach to model lifecycle events
- Callbacks → Graph runtime: observes · Callbacks instrument graph execution and streaming
- Callbacks → Agent runtime: observes · Callbacks instrument agent execution and tool use
- Internal utils → Callbacks: supports · Internal callback infrastructure powers shared hook management
- Internal utils → State & resume: supports · Private helpers back interrupts, resume, and concurrency safety
- Internal utils → Runner: supports · Runner and framework internals rely on private utilities
