The framework is organized into 5 tiers: User Interface (Desktop / CLI / SDK) → Studio Runtime (Session Manager, Meta-Agent, Team Manager, Avatar & Group Chat) → Core Framework (Orchestration, Execution, Agent, Memory, Tools, LLM Providers, Hooks) → Platform Services (Observability, Protocols, Security, Storage) → Domain Extensions (GUI Agent, Knowledge & GraphRAG, AgentKit Integration).

Core Features

Core Framework

• Agent Core: Agent execution engine based on 12-Factor Agents methodology, with Meta-Agent CEO dispatcher, agent team management, think-act loop, event-driven architecture, self-repair, and overflow recovery
• Orchestration Engine: Graph-based workflow engine + Flow system with decorators, execution plans, conditional routing, and parallel execution
• Tool System: Unified tool interface with function decorators, MCP Hub (multi-server aggregation), remote tools v2, OpenAPI toolset, sandbox tools, skill bundles, and document routers
• Memory System: Hierarchical memory (core / episodic / semantic), Mem0 deep integration, workspace memory, short-term memory, memory decay, hybrid search, compaction flush, MCP memory, and memory intelligence engine
• LLM Providers: 15+ providers — OpenAI, Anthropic, Ollama, Gemini, Kimi/Moonshot, MiniMax, Ark/VolcEngine, Zhipu, Qianfan, Bailian/Dashscope — with response caching, transcript sanitizer, and failover routing
• Communication Protocols: A2A inter-agent protocol (client / server / AgentCard / skill-as-tool), MCP resource access protocol
• Task Validation: Pydantic-based output parsing, auto-repair, and guiderails

Avatar & Team Collaboration

• Avatar System: Avatar registry (CRUD), group chat with multiple routing strategies (user-directed / meta-routed / round-robin)
• Meta-Agent Runtime: CEO dispatcher with dynamic sub-agent orchestration, team management with concurrency limits, archived snapshots, and session isolation
• Collaboration Patterns: Delegation, role-playing, conversation management, task locks, and collaboration metrics

Knowledge & Retrieval

• Knowledge Base: Document processing pipeline with chunkers, readers, extractors, and graph builders (GraphRAG)
• Retrieval System: Vector retriever, BM25 retriever, graph retriever, hybrid retriever, auto-retriever, and reranker
• Embeddings: OpenAI, Bailian, SiliconFlow, LiteLLM, with smart routing

Developer Experience

• CLI Tools (agx): serve, studio, loop, run, project, deploy, codegen, docs, skills, hooks, debug, scaffold, and config management
• Web UI (Studio): FastAPI-based management server with session management, real-time WebSocket, and protocol support
• Desktop App: Electron + React + Zustand + Vite, Pro/Lite dual mode (multi-pane / single-pane), command palette, settings panel, avatar sidebar, sub-agent panel, session history, and workspace panel

Enterprise Security

• Safety Layer: Leak detection, input sanitizer, advanced injection detector, policy engine (rules / severity / actions), input validator, sandbox policy, and audit logging
• Sandbox: Docker, Microsandbox, and Subprocess backends; Jupyter kernel manager, stateful code interpreter, sandbox templates
• Session Security: Database-backed sessions, write locks, in-memory sessions

Observability & Evaluation

• Monitoring: Complete callback system, real-time metrics, Prometheus/OpenTelemetry integration, trajectory analysis, span tree, WebSocket streaming
• Evaluation Framework: EvalSet-based evaluation, LLM judge, composite judge, span evaluator, trajectory matcher, trace-to-evalset converter
• Data Export: Multi-format export (JSON / CSV / Prometheus), time series analysis

Storage Layer

• Key-Value: SQLite, Redis, PostgreSQL, MongoDB, InMemory
• Vector: Milvus, Qdrant, Chroma, Faiss, PgVector, Pinecone, Weaviate
• Graph: Neo4j, Nebula
• Object: S3, GCS, Azure
• Unified Manager: Storage router, migration support, unified storage interface

GUI Agent / Embodiment

• Action Reflection: A/B/C result classification with heuristic and VLM reflection modes
• Stuck Detection & Recovery: Consecutive failure detection, repeat pattern recognition, intelligent recovery strategy recommendation
• Action Caching: Action-tree-based trajectory caching with exact and fuzzy matching (up to 9x speedup)
• REACT Output Parsing: Standardized REACT format parsing with compact action schema
• Device-Cloud Routing: Dynamic selection of on-device or cloud model based on task complexity and sensitivity
• DAG Task Verification: DAG-based multi-path task verification with dual semantic dependencies
• Human-in-the-Loop: Collector, component, and event model for human oversight

Quick Start

Installation

Option 1: Install from PyPI (Recommended)

# Core install (lightweight, no torch, installs in seconds)
pip install agenticx

# Install optional features as needed
pip install "agenticx[memory]"      # Memory: mem0, chromadb, qdrant, redis, milvus
pip install "agenticx[document]"    # Document processing: PDF, Word, PPT parsing
pip install "agenticx[graph]"       # Knowledge graph: networkx, neo4j, community detection
pip install "agenticx[llm]"         # Extra LLMs: anthropic, ollama
pip install "agenticx[monitoring]"  # Observability: prometheus, opentelemetry
pip install "agenticx[mcp]"         # MCP protocol
pip install "agenticx[database]"    # Database backends: postgres, SQLAlchemy
pip install "agenticx[data]"        # Data analysis: pandas, scikit-learn, matplotlib
pip install "agenticx[ocr]"         # OCR (pulls in torch ~2GB): easyocr
pip install "agenticx[volcengine]"  # Volcengine AgentKit
pip install "agenticx[all]"         # Everything

Tip: The core package includes only ~27 lightweight dependencies and installs in seconds. Heavy dependencies (torch, pandas, etc.) are optional extras - install only what you need.

Browser automation: To run browser-use as an MCP server from AgenticX (mcp_connect / mcp_call), see examples/browser-use-mcp.md.

Desktop MCP upgrades (2026-04): Machi Settings now supports MCP brand auto-discovery (Cursor / Trae / Claude / OpenClaw / Hermes / Codex), built-in Monaco JSON editor with schema validation, and one-click install from ModelScope MCP marketplace.

Option 2: Install from Source (Development)

# Clone repository
git clone https://github.com/DemonDamon/AgenticX.git
cd AgenticX

# Using uv (recommended, 10-100x faster than pip)
pip install uv
uv pip install -e .                  # Core install
uv pip install -e ".[memory,graph]"  # Add optional features
uv pip install -e ".[all]"           # Everything
uv pip install -e ".[dev]"           # Development tools

# Or using pip
pip install -e .
pip install -e ".[all]"

Environment Setup

# Set environment variables
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"  # Optional

Complete Installation Guide: For system dependencies (antiword, tesseract) and advanced document processing features, see INSTALL.md

CLI Quick Start

After installation, the agx command-line tool is available:

# View version
agx --version

# Create a new project
agx project create my-agent --template basic

# Start the API server
agx serve --port 8000

# Parse documents (PDF/PPT/Word etc.)
agx mineru parse report.pdf --output ./parsed

Full CLI Reference: See docs/cli.md for complete command documentation.

Create Your First Agent

from agenticx import Agent, Task, AgentExecutor
from agenticx.llms import OpenAIProvider

# Create agent
agent = Agent(
    id="data-analyst",
    name="Data Analyst",
    role="Data Analysis Expert", 
    goal="Help