AgenticX

What is AgenticX about?

AgenticX provides a complete stack for building, deploying, and operating collaborative AI agents. It combines a Python SDK, a command‑line interface (agx), a FastAPI‑based Studio server, and an Electron‑powered desktop client to let developers create anything from simple assistants to complex, multi‑agent enterprises.

How to use AgenticX?

1. Install the core package (recommended):

   pip install agenticx
   

   Optional extras add memory, document processing, graph, monitoring, MCP protocol, etc.
2. Create a project with the CLI:

   agx project create my-agent --template basic
   

3. Run the Studio server (or the desktop app) to manage sessions, avatars, and workflows:

   agx serve --port 8000
   

4. Write agents using the SDK:

   from agenticx import Agent, Task, AgentExecutor
   from agenticx.llms import OpenAIProvider
   
   agent = Agent(id="data-analyst", name="Data Analyst", role="Data Analysis Expert")
   task = Task(id="analysis-task", description="Analyze sales data trends")
   llm = OpenAIProvider(model="gpt-4")
   result = AgentExecutor(agent=agent, llm=llm).run(task)
   print(result)
   

5. Add tools with the @tool decorator; agents will invoke them automatically.
6. Monitor execution via built‑in observability (Prometheus/OpenTelemetry, real‑time WebSocket streams) or the Studio UI.

Key Features of AgenticX

• Meta‑Agent orchestration – CEO‑style dispatcher that creates and manages sub‑agents dynamically.
• 15+ LLM providers – OpenAI, Anthropic, Ollama, Gemini, Kimi, MiniMax, Ark, Zhipu, Qianfan, Ba­ilian, etc., with caching and fail‑over.
• Hierarchical memory – Core, episodic, semantic layers; Mem0 integration; off‑loading of large tool results.
• Avatar & group chat – Multi‑avatar registry, routing strategies, and collaborative sessions.
• Skill ecosystem – Register, version, self‑evolve, and safe‑gate skills; AGX bundles for easy distribution.
• Safety sandbox – Docker / microsandbox / subprocess isolation, leak detection, policy engine, audit logs.
• IM gateway – Feishu, WeChat, DingTalk integration for remote command‑relay.
• Observability – Real‑time metrics, Prometheus, OpenTelemetry, trajectory analysis, export to JSON/CSV.
• Storage abstraction – Unified manager for KV (SQLite, Redis, PostgreSQL), vector (Milvus, Qdrant, Chroma, etc.), graph (Neo4j, Nebula), and object stores (S3, GCS, Azure).
• Desktop application – Electron + React UI with Pro/Lite modes, command palette, session/history panels.
• Workflow engine – Graph‑based orchestration, conditional routing, parallel execution, flow decorators.

Use Cases of AgenticX

• Enterprise assistants – Customer‑service bots that coordinate multiple specialized agents (FAQ, order lookup, escalation).
• Data‑analytics copilots – Agents that ingest spreadsheets, run queries, generate reports, and visualize results.
• Knowledge‑augmented RAG – Document parsing, GraphRAG, multi‑brain retrieval for research or compliance.
• Software development automation – Long‑horizon coding agents that plan, implement, test, and commit code.
• Intent‑recognition services – Hierarchical intent classifiers with hybrid entity extraction.
• GUI automation – Desktop‑agent that performs UI actions, detects failures, and caches trajectories.
• Financial news hunting – Agents that monitor markets, aggregate reports, and produce alerts.

FAQ from AgenticX

Q: Do I need to install heavy libraries like torch? A: No. The core package is lightweight (~27 deps). Heavy libraries are optional extras (e.g., agenticx[ocr] pulls in torch).

Q: How can I add a new LLM provider? A: Implement a subclass of the provider interface and register it via the SDK; the built‑in routing will automatically include it.

Q: Is the platform production‑ready? A: Yes. It includes safety sandboxes, multi‑tenant session isolation, observability, and failsafe orchestration.

Q: Can I run AgenticX on Windows/macOS/Linux? A: Supported on all three; the desktop app is cross‑platform, and the server runs on any Python 3.10+ environment.

Q: How do I enable monitoring with Prometheus? A: Install the monitoring extra (pip install "agenticx[monitoring]") and configure the Prometheus exporter; metrics are exposed via the Studio server.

AgenticX: Unified Multi-Agent Framework

Architecture • Features • Quick Start • Examples • Progress

Language / 语言: English | 中文

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 typed AgentEvent stream, multi-turn history in/out, parallel tool execution, and optional loop-detector / compactor / offloader injection — zero Studio/CLI coupling (legacy text-JSON TextReActAgent facade kept for compatibility)
• Unified Offload: Offloader protocol + filesystem-backed FileOffloader keep 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, .changelog versioning, 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]"        # 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): Near 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 users analyze and understand data",
    organization_id="my-org"
)

# Create task
task = Task(
    id="analysis-task",
    description="Analyze sales data trends",
    expected_output="Detailed analysis report"
)

# Configure LLM
llm = OpenAIProvider(model="gpt-4")

# Execute task
executor = AgentExecutor(agent=agent, llm=llm)
result = executor.run(task)
print(result)

Tool Usage Example

from agenticx.tools import tool

@tool
def calculate_sum(x: int, y: int) -> int:
    """Calculate the sum of two numbers"""
    return x + y

@tool  
def search_web(query: str) -> str:
    """Search web information"""
    return f"Search results: {query}"

# Agents will automatically invoke these tools

Complete Examples

We provide rich examples demonstrating various framework capabilities:

Agent Core (M5)

Single Agent Example

# Basic agent usage
python examples/m5_agent_demo.py

• Demonstrates basic agent creation and execution
• Tool invocation and error handling
• Event-driven execution flow

Multi-Agent Collaboration

# Multi-agent collaboration example
python examples/m5_multi_agent_demo.py

• Multi-agent collaboration patterns
• Task distribution and result aggregation
• Inter-agent communication

Orchestration & Validation (M6 & M7)

Simple Workflow

# Basic workflow orchestration
python examples/m6_m7_simple_demo.py

• Workflow creation and execution
• Task output parsing and validation
• Conditional routing and error handling

Complex Workflow

# Complex workflow orchestration
python examples/m6_m7_comprehensive_demo.py

• Complex workflow graph structures
• Parallel execution and conditional branching
• Complete lifecycle management

Agent Communication (M8)

A2A Protocol Demo

# Inter-agent communication protocol
python examples/m8_a2a_demo.py

• Agent-to-Agent communication protocol
• Distributed agent systems
• Service discovery and skill invocation

Observability Monitoring (M9)

Complete Monitoring Demo

# Observability module demo
python examples/m9_observability_demo.py

• Real-time performance monitoring
• Execution trajectory analysis
• Failure analysis and recovery recommendations
• Data export and report generation

Memory System

Basic Memory Usage

# Memory system example
python examples/memory_example.py

• Long-term memory storage and retrieval
• Context memory management

Healthcare Scenario

# Healthcare memory scenario
python examples/mem0_healthcare_example.py  

• Medical knowledge memory and application
• Personalized patient information management

Human-in-the-Loop

Human Intervention Flow

# Human-in-the-loop example
python examples/human_in_the_loop_example.py

• Human approval workflows
• Human-machine collaboration patterns
• Risk control mechanisms

Detailed documentation: examples/README_HITL.md

LLM Integration

Chatbot

# LLM chat example
python examples/llm_chat_example.py

• Multi-model support demonstration
• Streaming response handling
• Cost control and monitoring

Security Sandbox

Code Execution Sandbox

# Micro-sandbox example
python examples/microsandbox_example.py

• Secure code execution environment
• Resource limits and isolation

Technical blog: examples/microsandbox_blog.md

Intent Recognition Service

Intelligent Intent Recognition System

# Intent recognition service example
python examples/agenticx-for-intent-recognition/main.py

A production-grade, layered intent recognition service built entirely on the AgenticX framework, demonstrating real-world usage of Agents, Workflows, Tools, and Storage systems.

Architecture:

• Agent Layer: Hierarchical agent design — a base IntentRecognitionAgent (LLM-powered) with specialized agents (GeneralIntentAgent, SearchIntentAgent, FunctionIntentAgent) for fine-grained classification
• Workflow Engine: Pipeline-based orchestration — preprocessing → intent classification → entity extraction → rule matching → post-processing; plus dedicated workflows for each intent type
• Tool System: Hybrid entity extraction (UIE + LLM + Rule extractors with confidence-weighted fusion), regex/full-text matching, and a full post-processing suite (confidence adjustment, conflict resolution, entity optimization, intent refinement)
• API Gateway: Async service layer with rate limiting, concurrent control, batch processing, health checks, and performance metrics
• Storage: SQLite-backed data persistence for training data management via UnifiedStorageManager
• Data Models: Pydantic-based type-safe data contracts for API requests/responses and domain objects

Key capabilities:

• Three-tier Intent Classification: General dialogue (greetings, chitchat), information search (factual/how-to/comparison queries), and function/tool invocation
• Hybrid Entity Extraction: Combines UIE models, LLM, and rule-based extractors with intelligent fusion strategies
• Full Post-processing Pipeline: Confidence adjustment, conflict resolution, entity optimization, and intent refinement
• Extensible Design: Add new intent types by simply creating a new agent and workflow — zero changes to existing code

See: examples/agenticx-for-intent-recognition/

GUI Agent / Embodiment (M16)

GUI Automation Agent

# GUI Agent example
python examples/agenticx-for-guiagent/AgenticX-GUIAgent/main.py

• Complete GUI automation framework with human-aligned learning
• Action reflection (A/B/C classification) and stuck detection
• Action caching system for performance optimization
• REACT output parsing and compact action schema
• Device-Cloud routing for intelligent model selection
• DAG-based task verification

Key capabilities:

• Action Reflection: Automatic action result classification (success/wrong_state/no_change)
• Stuck Detection: Continuous failure detection and recovery strategy recommendation
• Action Caching: Trajectory caching with exact and fuzzy matching (up to 9x speedup)
• REACT Parsing: Standardized REACT format output parsing
• Smart Routing: Dynamic device-cloud model selection based on task complexity and sensitivity
• DAG Verification: Multi-path task verification with dual-semantic dependencies

See: examples/agenticx-for-guiagent/

More Application Examples

Technical Architecture

Development Progress

✅ Completed Modules (M1-M11, M13-M17)

🚧 Planned Modules

🆕 Recent Capability Additions (H1 2026)

Core Advantages

• Unified Abstraction: Clear and consistent core abstractions, avoiding conceptual confusion
• Pluggable Architecture: All components are replaceable, avoiding vendor lock-in
• Enterprise-Grade Monitoring: Complete observability, production-ready
• Security First: Built-in security mechanisms and multi-tenant support
• High Performance: Optimized execution engine and concurrent processing
• Rich Ecosystem: Complete toolset and example library

System Requirements

• Python: 3.10+
• Memory: 4GB+ RAM recommended
• System: Windows / Linux / macOS
• Core Dependencies: ~27 lightweight packages, installs in seconds (see pyproject.toml)
• Optional Dependencies: 15 feature groups available via pip install "agenticx[xxx]"

Contributing

We welcome community contributions! Please refer to:

1. Submit Issues to report bugs or request features
2. Fork the project and create feature branches
3. Submit Pull Requests, ensuring all tests pass
4. Participate in code reviews and discussions

Acknowledgements / Upstream Credits

The personal WeChat (iLink) channel integration in AgenticX was built on top of the openilink-sdk-go library from OpeniLink Hub. We specifically relied on:

• QR code binding flow — FetchQRCode / PollQRStatus APIs for the scan-to-bind UX
• Message monitoring — client.Monitor() for real-time inbound message streaming
• Outbound messaging — SendText / Push for reply delivery with context_token routing
• CDN media handling — DownloadMedia / DownloadVoice for encrypted WeChat media

OpeniLink Hub's OpenClaw App also demonstrated an AI Agent gateway integration pattern that informed our adapter architecture.

We did not include OpeniLink Hub's web console, App Marketplace, or multi-bot management features. AgenticX's core multi-agent runtime, session management, and Desktop UI remain fully independent implementations.

OpeniLink Hub — MIT License — github.com/openilink/openilink-hub

Additional reference: WorkBuddy — WeixinBot Guide for iLink protocol usage patterns.

Desktop development: The iLink Go sidecar binary is not committed to this repository. Before using the personal WeChat bridge locally, run make build in packaging/wechat-sidecar/ (requires Go 1.22+). See packaging/wechat-sidecar/README.md.

License

This project is licensed under the Apache License, Version 2.0 — see the LICENSE file for details.

Star History

Acknowledgments

AgenticX would not exist in its current form without the inspiration, architectural ideas, and engineering wisdom we drew from the open-source community. We have studied the following projects in depth, and we are genuinely grateful to every author, contributor, and community behind them.

Thank you for building in the open. Your work has been a constant source of insight and motivation for the AgenticX team.

If AgenticX helps you, please give us a Star!

GitHub • Documentation • Examples • Discussions