# anative-lab/evoagentx architecture

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

- Interactive diagram: https://gitdiagram.com/anative-lab/evoagentx
- Repository: https://github.com/anative-lab/evoagentx

## Overview

EvoAgentX is a framework for constructing and running LLM-based agent workflows, evaluating them, and iteratively optimizing them. A user describes a goal; workflow generation assembles agents and actions, which execute with model and tool support, optionally using memory and human review. Evaluation and optimizers provide the documented improvement loop. The graph also shows RAG as a supporting retrieval layer. Relationships are limited to README statements and the supplied SOURCE INDEX references; unsampled modules are represented at their exact paths, and their internal behavior is not inferred.

Main entry points: [`evoagentx/agents/agent_manager.py`](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent_manager.py) (Agent manager), [`evoagentx/agents/agent.py`](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent.py) (Agent runtime), [`evoagentx/optimizers/mipro_optimizer.py`](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/optimizers/mipro_optimizer.py) (MIPRO optimizer), [`evoagentx/workflow/workflow_manager.py`](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_manager.py) (Workflow manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow orchestration"]
  node_workflow_gen["Workflow generation"]
  node_workflow_manager["Workflow manager"]
  node_workflow_graph["Workflow graph<br/>[workflow_graph.py]"]
  node_controller["Execution controller<br/>[controller.py]"]
end

subgraph group_agent["Agents and tools"]
  node_agent_manager["Agent manager<br/>[agent_manager.py]"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_tools["Built-in tools<br/>[tool.py]"]
  node_hitl["Human review<br/>[hitl.py]"]
end

subgraph group_evolution["Evaluation and evolution"]
  node_evaluator["Workflow evaluator<br/>[evaluator.py]"]
  node_optimizer["Workflow optimizer<br/>[optimizer.py]"]
  node_mipro["MIPRO optimizer<br/>[mipro_optimizer.py]"]
end

subgraph group_support["Model and memory"]
  node_models["LLM providers<br/>[base_model.py]"]
  node_model_config["Model configuration<br/>[model_configs.py]"]
  node_memory["Short- and long-term memory<br/>[memory_manager.py]"]
  node_storage[("Agent and memory storage<br/>[base.py]")]
end

subgraph group_retrieval["Retrieval"]
  node_rag["RAG pipeline<br/>[rag.py]"]
  node_rag_schema["Retrieval data schema<br/>[schema.py]"]
  node_rag_config["RAG configuration<br/>[rag_config.py]"]
end

node_user(("User or developer"))

node_user -->|"describes goal"| node_workflow_gen
node_workflow_gen -.->|"assembles workflow"| node_workflow_manager
node_workflow_manager -->|"manages agents"| node_agent_manager
node_workflow_manager -->|"uses graph"| node_workflow_graph
node_controller -->|"manages agents"| node_agent_manager
node_controller -->|"invokes optimizer"| node_optimizer
node_controller -->|"runs workflow"| node_workflow_manager
node_agent_manager -->|"creates agents"| node_agent
node_agent_manager -->|"attaches tools"| node_tools
node_agent -->|"uses model"| node_models
node_agent -->|"uses memory"| node_memory
node_agent -->|"uses storage"| node_storage
node_agent -.->|"calls tools"| node_tools
node_workflow_graph -->|"loads agents"| node_agent_manager
node_workflow_graph -.->|"supports review"| node_hitl
node_mipro -->|"optimizes agents"| node_agent_manager
node_mipro -->|"optimizes graph"| node_workflow_graph
node_mipro -->|"evaluates candidates"| node_evaluator
node_optimizer -.->|"specializes optimizer"| node_mipro
node_memory -.->|"persists memories"| node_storage
node_rag -->|"builds corpus"| node_rag_schema
node_rag -->|"uses configuration"| node_rag_config
node_rag -->|"uses stores"| node_storage
node_models -->|"uses configuration"| node_model_config
node_user -->|"reviews workflow"| node_hitl

click node_workflow_gen "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_generator.py"
click node_workflow_manager "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_manager.py"
click node_workflow_graph "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_graph.py"
click node_controller "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/controller.py"
click node_agent_manager "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent_manager.py"
click node_agent "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent.py"
click node_tools "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/tools/tool.py"
click node_hitl "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/hitl/hitl.py"
click node_evaluator "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/evaluators/evaluator.py"
click node_optimizer "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/optimizers/optimizer.py"
click node_mipro "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/optimizers/mipro_optimizer.py"
click node_models "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/models/base_model.py"
click node_model_config "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/models/model_configs.py"
click node_memory "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/memory/memory_manager.py"
click node_storage "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/storages/base.py"
click node_rag "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/rag.py"
click node_rag_schema "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/schema.py"
click node_rag_config "https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/rag_config.py"

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_workflow_gen,node_workflow_manager,node_workflow_graph,node_controller,node_user toneBlue
class node_agent_manager,node_agent,node_tools,node_hitl toneAmber
class node_evaluator,node_optimizer,node_mipro toneMint
class node_models,node_model_config,node_memory,node_storage toneRose
class node_rag,node_rag_schema,node_rag_config toneIndigo
```

## Components

### Workflow orchestration

- [Workflow generation](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_generator.py): `evoagentx/workflow/workflow_generator.py`
- [Workflow manager](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_manager.py): `evoagentx/workflow/workflow_manager.py`
- [Workflow graph](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/workflow_graph.py): `evoagentx/workflow/workflow_graph.py`
- [Execution controller](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/workflow/controller.py): `evoagentx/workflow/controller.py`

### Agents and tools

- [Agent manager](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent_manager.py): `evoagentx/agents/agent_manager.py`
- [Agent runtime](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/agents/agent.py): `evoagentx/agents/agent.py`
- [Built-in tools](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/tools/tool.py): `evoagentx/tools/tool.py`
- [Human review](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/hitl/hitl.py): `evoagentx/hitl/hitl.py`

### Evaluation and evolution

- [Workflow evaluator](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/evaluators/evaluator.py): `evoagentx/evaluators/evaluator.py`
- [Workflow optimizer](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/optimizers/optimizer.py): `evoagentx/optimizers/optimizer.py`
- [MIPRO optimizer](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/optimizers/mipro_optimizer.py): `evoagentx/optimizers/mipro_optimizer.py`

### Model and memory

- [LLM providers](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/models/base_model.py): `evoagentx/models/base_model.py`
- [Model configuration](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/models/model_configs.py): `evoagentx/models/model_configs.py`
- [Short- and long-term memory](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/memory/memory_manager.py): `evoagentx/memory/memory_manager.py`
- [Agent and memory storage](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/storages/base.py): `evoagentx/storages/base.py`

### Retrieval

- [RAG pipeline](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/rag.py): `evoagentx/rag/rag.py`
- [Retrieval data schema](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/schema.py): `evoagentx/rag/schema.py`
- [RAG configuration](https://github.com/anative-lab/evoagentx/blob/main/evoagentx/rag/rag_config.py): `evoagentx/rag/rag_config.py`

### Other components

- **User or developer**

## Connections

- User or developer → Workflow generation: describes goal (evidence: `README.md`)
- Workflow generation → Workflow manager: assembles workflow
- Workflow manager → Agent manager: manages agents (evidence: `evoagentx/workflow/workflow_manager.py`)
- Workflow manager → Workflow graph: uses graph (evidence: `evoagentx/workflow/workflow_manager.py`)
- Execution controller → Agent manager: manages agents (evidence: `evoagentx/workflow/controller.py`)
- Execution controller → Workflow optimizer: invokes optimizer (evidence: `evoagentx/workflow/controller.py`)
- Execution controller → Workflow manager: runs workflow (evidence: `evoagentx/workflow/controller.py`)
- Agent manager → Agent runtime: creates agents (evidence: `evoagentx/agents/agent_manager.py`)
- Agent manager → Built-in tools: attaches tools (evidence: `evoagentx/agents/agent_manager.py`)
- Agent runtime → LLM providers: uses model (evidence: `evoagentx/agents/agent.py`)
- Agent runtime → Short- and long-term memory: uses memory (evidence: `evoagentx/agents/agent.py`)
- Agent runtime → Agent and memory storage: uses storage (evidence: `evoagentx/agents/agent.py`)
- Agent runtime → Built-in tools: calls tools
- Workflow graph → Agent manager: loads agents (evidence: `evoagentx/workflow/workflow_graph.py`)
- Workflow graph → Human review: supports review
- MIPRO optimizer → Agent manager: optimizes agents (evidence: `evoagentx/optimizers/mipro_optimizer.py`)
- MIPRO optimizer → Workflow graph: optimizes graph (evidence: `evoagentx/optimizers/mipro_optimizer.py`)
- MIPRO optimizer → Workflow evaluator: evaluates candidates (evidence: `evoagentx/optimizers/mipro_optimizer.py`)
- Workflow optimizer → MIPRO optimizer: specializes optimizer
- Short- and long-term memory → Agent and memory storage: persists memories
- RAG pipeline → Retrieval data schema: builds corpus (evidence: `evoagentx/rag/rag.py`)
- RAG pipeline → RAG configuration: uses configuration (evidence: `evoagentx/rag/rag.py`)
- RAG pipeline → Agent and memory storage: uses stores (evidence: `evoagentx/rag/rag.py`)
- LLM providers → Model configuration: uses configuration (evidence: `evoagentx/models/base_model.py`)
- User or developer → Human review: reviews workflow (evidence: `README.md`)