AgenticX: Unified Multi-Agent Framework
Architecture • Features • Quick Start • Examples • Progress
Security advisory
LiteLLM (PyPI): Malicious releases litellm 1.82.7 and 1.82.8 were removed from PyPI after reports that they could exfiltrate API keys. If you ever installed either version, uninstall them, rotate any credentials that may have been exposed, and upgrade to a release the upstream project and PyPI list as safe (for example 1.82.9+, per current upstream guidance). Check your environment with pip show litellm.
Vision
AgenticX aims to create a unified, scalable, production-ready multi-agent application development framework, empowering developers to build everything from simple automation assistants to complex collaborative intelligent agent systems.
System Architecture
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
- Embeddable ReActAgent (SDK primitive): Canonical async function-calling ReAct loop (
ainvoke/astream) with a typedAgentEventstream, multi-turn history in/out, parallel tool execution, and optional loop-detector / compactor / offloader injection — zero Studio/CLI coupling (legacy text-JSONTextReActAgentfacade kept for compatibility) - Unified Offload:
Offloaderprotocol + filesystem-backedFileOffloaderkeep large tool results / compressed context out of live history (inline reference placeholders, retrieved on demand); plus an in-workspace MCP gateway that runs MCP servers inside the sandbox - 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)
- Multi-Brain Knowledge: Isolatable, per-avatar/session mountable "doc brain + code brain" architecture with cross-brain aggregated search
- Code Semantic Index: Hybrid (vector + BM25) retrieval across multiple codebases, wired into the "code brain"
- Retrieval System: Vector retriever, BM25 retriever, graph retriever, hybrid retriever, auto-retriever, and reranker
- Embeddings: OpenAI, Bailian, SiliconFlow, LiteLLM, with smart routing
Skills & Self-Evolution
- Skill System: Registration and full lifecycle management — dangerous-pattern security scan gate, 5-strategy fuzzy patch,
.changelogversioning, source tagging, and per-skill enable/disable - Skill Self-Evolution: Captures tool-call observations at runtime and auto-distills new skills via background LLM session review; quality gate, usage stats, and deprecation form the lifecycle loop
- Extension Ecosystem (AGX Bundle): Bundle definitions (skills / mcp_servers / avatars / memory_templates), local install/uninstall, multi-source registry aggregated search
Long-Horizon Autonomous Coding
- Long-Run Orchestration: Polls multiple task sources (manual queue / Cron / Linear / project features), per-task isolated workspaces, stall self-healing, continuation/failure dual-track backoff, incremental token accounting
- Project State Machine: Disk-backed single source of truth with a versioned feature state machine, file locks / atomic writes, powering an auditable "init → implement → verify → commit" loop
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
- IM Remote Gateway: Remote command relay and reply delivery for Feishu / WeCom / DingTalk / personal WeChat (iLink) → cloud → local Agent
- Claude Code Bridge: Token-protected local HTTP / NDJSON control plane driving local Claude Code in headless (stream-json) or visible TUI (PTY) modes
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 / Subprocess / remote HTTP backends (tiered factory auto-selection); Jupyter kernel manager, stateful code interpreter, sandbox templates, JSONL execution audit
- Session Security: Database-backed sessions, write locks, in-memory sessions, session-level multi-tenant (tenant_id) isolation
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]" # Da