GitHub - DemonDamon/AgenticX: AgenticX is a unified, production-ready multi-agent platform — Python SDK + CLI (agx) + Studio server + Machi desktop app. Features Meta-Agent orchestration, 15+ LLM providers, MCP Hub, hierarchical memory, avatar & group chat, skill ecosystem, safety sandbox, and IM gateway (Feishu/WeChat).

A unified agent technology stack spanning the Python Agent Runtime, Near Desktop, and Enterprise

Product Architecture • Core Capabilities • 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 provides a unified, scalable, production-ready agent technology stack. Developers can build directly with the Python SDK and agx CLI, use Near Desktop as a local-first multi-agent workspace, or deploy AgenticX Enterprise for enterprise access, governance, compliance gateway, and audit capabilities.

System Architecture

The architecture consists of one shared capability core and two product forms:

AgenticX Core / Runtime: Python SDK, Studio Server, and Agent Runtime for orchestration, tools, MCP, memory, knowledge bases, Skills, Hooks, model adapters, secure sandboxes, observability, and evaluation.
Near Desktop: An Electron + React local-first workspace. Its default path connects to a local agx serve / agx-server, with multi-pane chat, avatars and group chat, workspaces, terminal, automation, Voice Focus, and an optional remote single-server backend.
AgenticX Enterprise: Web Portal, Admin Console, and Go AI Gateway for enterprise use. Employee chat passes through Portal BFF before the Gateway. The Gateway handles authentication, policy, quota, model relay, response governance, audit, and usage; it is not a full Agent Runtime.

Near and Enterprise share AgenticX abstractions and capabilities, but their current deployment paths are independent. Near defaults to the local Python Runtime; Enterprise uses the Go Gateway for its current online path. Enterprise Edge Agent is an MVP outside the default path, while Cluster Agent Runtime remains planned.

AgenticX Product and Technology Architecture — product entries, Studio / Agent / Core SDK Runtime, protocol ecosystem, and platform foundation

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 Entry Points

CLI Tools (agx): serve, studio, gateway, feishu, loop, project, agent, workflow, deploy, monitor, docs, mineru, sandbox, skills, hooks, config, cc-bridge, memory-graph, generate, and tools
Studio Server: FastAPI REST API + SSE backend wiring sessions, messages, avatars, group chat, MCP, Skills, Hooks, knowledge bases, and runtime execution
Embeddable SDK: Core Agent / Task / Tool / AgentExecutor plus an independent ReActAgent path that does not depend on the desktop app
Extension Protocols: A2A, MCP, AG-UI, OpenAPI, and remote tools

Near Desktop

Local-first: Electron + React + Zustand + Vite; Electron starts and manages local agx serve / agx-server over REST API + SSE
Multi-agent Workspace: Multi-pane chat, Meta-Agent, avatars, group chat, sub-agent status, session history, and per-pane model selection
Workspace and Execution: Working directories, file references, embedded terminal, Computer Use, MCP, Skills, Hooks, knowledge bases, and data sources
Extended Experiences: Automation, Voice Focus, Claude Code Bridge, and Feishu / personal WeChat sidecars
Optional Remote Mode: A single remote agx serve backend is implemented; Cluster / HA multi-replica runtime remains planned

AgenticX Enterprise

Enterprise Entry and Control Plane: Web Portal, Portal BFF, and Admin Console for identity, models and channels, policy, quota, audit, and operations
Go AI Gateway: JWT / PAT authentication, subject identity, cache, rate limiting, policy evaluation, model and channel routing, streaming response governance, audit chain, and token usage
Real Data Infrastructure: PostgreSQL by default, optional MySQL, Redis for cache and distributed limits, and a must-succeed append-only JSONL audit fallback
Runtime Boundary: The Gateway is an enterprise compliance and model relay, not the Python Agent Runtime. Enterprise Edge Agent is a non-default MVP; Cluster Runtime has not started

Security and Sandbox

Safety Building Blocks: Leak detection, sanitization, injection detection, policy engine, input validation, tool guardrails, approval, and audit. The Studio path combines hooks, permissions, and path protection; it does not yet route every operation through the complete SafetyLayer
Sandbox: Docker / Microsandbox / Subprocess / remote HTTP backends; Jupyter kernel manager, stateful code interpreter, sandbox templates, and JSONL execution audit
Session Persistence: Studio writes to the ~/.agenticx/sessions file tree by default, with an optional Redis session backend. The database session service is a separate SDK module, not the default Studio path

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

Default Persistence: The ~/.agenticx file tree stores configuration, sessions, and workspaces; SQLite powers session metadata / FTS, and Studio can optionally use Redis for sessions
Knowledge Base Vectors: Chroma is the default Desktop knowledge-base backend; Qdrant, Milvus, Faiss, PgVector, and others depend on optional packages and specific module wiring
Unified Storage Abstractions: Key-value, vector, graph, and object interfaces are available, but some third-party adapters remain placeholders or are not wired into the Studio main path

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

Project	Description	Path
Agent Skills	Skill discovery, matching, and SOP-driven skill execution for agents	examples/agenticx-for-agent-skills/
AgentKit	Volcengine AgentKit integration with Docker-ready agent deployment	examples/agenticx-for-agentkit/
ChatBI	Conversational BI — natural language to data insights	examples/agenticx-for-chatbi/
Deep Research	Multi-source deep research and report generation	examples/agenticx-for-deepresearch/
Doc Parser	Intelligent document parsing (PDF, Word, PPT)	examples/agenticx-for-docparser/
Finance	Financial news hunting and analysis	examples/agenticx-for-finance/
Future Prediction	Predictive analysis and forecasting	examples/agenticx-for-future-prediction/
GraphRAG	Knowledge graph-enhanced retrieval-augmented generation	examples/agenticx-for-graphrag/
Math Modeling	Mathematical modeling assistant	examples/agenticx-for-math-modeling/
Model Architecture Discovery	Automated model architecture search and discovery	examples/agenticx-for-modelarch-discovery/
Query Optimizer	SQL/query optimization agent	examples/agenticx-for-queryoptimizer/
Sandbox	Secure code execution sandbox	examples/agenticx-for-sandbox/
Spec Coding	Specification-driven code generation	examples/agenticx-for-spec-coding/
Vibe Coding	AI-assisted creative/vibe coding	examples/agenticx-for-vibecoding/

Technical Architecture

Product and Runtime Paths

flowchart TB
    subgraph Entry["Product and Developer Entry Points"]
        Near["Near Desktop<br/>Local-first Workspace"]
        Dev["Python SDK · agx CLI<br/>REST API + SSE"]
        Enterprise["AgenticX Enterprise<br/>Portal · Admin · Go Gateway"]
    end

    subgraph PythonRuntime["AgenticX Python Runtime"]
        Studio["Studio Server<br/>Sessions · Avatars · Group Chat"]
        Runtime["Agent Runtime<br/>Orchestration · Delegation · Events"]
        Capabilities["Tools · MCP · Memory · KB<br/>LLM · Skills · Hooks"]
        Studio <--> Runtime
        Runtime <--> Capabilities
    end

    subgraph EnterprisePath["Current Enterprise Online Path"]
        Portal["Web Portal"] --> BFF["Portal BFF"]
        BFF --> Gateway["Go AI Gateway<br/>Compliance · Routing · Audit"]
        Gateway --> Models["Compatible Model Services"]
    end

    Near <-->|"Local HTTP / SSE"| Studio
    Dev --> Studio
    Dev --> Runtime
    Enterprise --> Portal
    Gateway -.->|"Future capability reuse"| Runtime

Near defaults to the local Python Runtime. Enterprise currently uses an independent Go Gateway online path. The dashed line indicates evolution only, not a default production call.

Core Framework Internals

graph TD
    subgraph "User Interface Layer"
        Desktop["Near Desktop (Electron + React)"]
        CLI["CLI (agx serve / loop / run / project)"]
        SDK[Python SDK]
    end

    subgraph "Studio Runtime Layer"
        StudioServer["Studio Server (FastAPI)"]
        SessionMgr[Session Manager]
        MetaAgent["Meta-Agent (CEO Dispatcher)"]
        TeamMgr[Agent Team Manager]
        AvatarSys["Avatar & Group Chat"]
    end

    subgraph "Core Framework Layer"
        subgraph "Orchestration"
            WorkflowEngine[Workflow Engine]
            Flow["Flow System"]
        end
        subgraph "Execution"
            AgentRuntime["Agent Runtime (Studio)"]
            AgentExecutor["Agent Executor (Core)"]
            TaskValidator[Task Validator & Output Parser]
        end
        subgraph "Core Components"
            Agent[Agent]
            Task[Task]
            Tool[Tool System & MCP Hub]
            Memory["Memory (Mem0 / Short-term / Workspace)"]
            LLM["LLM Providers (OpenAI / Anthropic / Ollama / 10+)"]
        end
        Collaboration["Collaboration & Delegation"]
        Hooks["Hooks System"]
    end

    subgraph "Platform Services Layer"
        subgraph "Observability"
            Monitoring["Monitoring & Trajectory"]
            Prometheus[Prometheus / OpenTelemetry]
        end
        subgraph "Protocols"
            A2A["A2A Protocol"]
            MCP["MCP Protocol"]
        end
        subgraph "Security"
            Safety["Safety Layer (Leak Detection / Sanitizer / Policy)"]
            Sandbox["Execution Sandbox"]
        end
        subgraph "Storage"
            KVStore["Key-Value (SQLite / Redis)"]
            VectorStore["Vector (Milvus / Qdrant / Chroma)"]
            GraphStore["Graph (Neo4j / NetworkX)"]
        end
    end

    subgraph "Domain Extensions"
        Embodiment["GUI Agent / Embodiment"]
        Knowledge["Knowledge & GraphRAG"]
    end

    Desktop --> StudioServer
    CLI --> StudioServer
    SDK --> AgentExecutor

    StudioServer --> SessionMgr
    SessionMgr --> MetaAgent
    MetaAgent --> TeamMgr
    MetaAgent --> AvatarSys
    TeamMgr --> AgentRuntime

    AgentRuntime --> Agent
    AgentExecutor --> Agent
    WorkflowEngine --> AgentExecutor

    Agent --> Tool
    Agent --> Memory
    Agent --> LLM
    Agent --> Hooks

    AgentRuntime --> Monitoring
    AgentExecutor --> Monitoring
    Agent --> A2A
    Tool --> MCP

    Agent --> Safety
    Memory --> KVStore
    Memory --> VectorStore
    Knowledge --> GraphStore

Development Progress

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

Module	Status	Description
M1	✅	Core Abstraction Layer — Agent, Task, Tool, Workflow, Event Bus, Component, and Pydantic data contracts
M2	✅	LLM Service Layer — 15+ providers (OpenAI / Anthropic / Ollama / Gemini / Kimi / MiniMax / Ark / Zhipu / Qianfan / Bailian), response caching, failover routing
M3	✅	Tool System — Function decorators, MCP Hub, remote tools v2, OpenAPI toolset, sandbox tools, skill bundles, document routers
M4	✅	Memory System — Hierarchical (core / episodic / semantic), Mem0, workspace, short-term, memory decay, hybrid search, memory intelligence engine
M5	✅	Agent Core — Meta-Agent CEO dispatcher, think-act loop, event-driven architecture, self-repair, overflow recovery, reflection
M6	✅	Task Validation — Pydantic-based output parsing, auto-repair, guiderails
M7	✅	Orchestration Engine — Graph-based workflow engine + Flow system with decorators, execution plans, conditional routing, parallel execution
M8	✅	Communication Protocols — A2A (client / server / AgentCard / skill-as-tool), MCP resource access, AGUI protocol
M9	✅	Observability — Callbacks, real-time monitoring, trajectory analysis, span tree, WebSocket streaming, Prometheus / OpenTelemetry integration
M10	✅	Developer Experience — CLI (`agx` with 15+ commands), Studio Server (FastAPI REST + SSE), Near Desktop (Electron + React + Zustand, multi-pane)
M11	✅	Safety building blocks — Leak detection, sanitization, injection detection, policy, guardrails, hooks, approval, and multi-backend sandbox; Studio does not yet use one complete `SafetyLayer` pipeline
M13	✅	Knowledge & Retrieval — Knowledge base with document processing, chunkers, graphers (GraphRAG), readers; retrieval (vector / BM25 / graph / hybrid / auto); embeddings (OpenAI / Bailian / SiliconFlow / LiteLLM)
M14	✅	Avatar & Collaboration — Avatar registry, group chat (user-directed / meta-routed / round-robin), delegation, role-playing, conversation patterns, team management
M15	✅	Evaluation Framework — EvalSet, LLM judge, composite judge, span evaluator, trajectory matcher, trace converter
M16	✅	Embodiment — GUI Agent framework with action reflection, stuck detection, action caching, REACT parsing, device-cloud routing, DAG verification, human-in-the-loop
M17	✅	Storage abstractions and primary adapters — Default file / SQLite, optional Redis, Chroma knowledge base, and multiple vector / graph / object interfaces; some third-party adapters remain placeholders

🚧 Planned Modules

Module	Status	Description
M12	🚧	Agent Evolution — Architecture search, knowledge distillation, adaptive planning
M18	🚧	Core / Studio multi-tenancy and RBAC — Fine-grained `tenant_id` isolation is not wired into the Studio main path; Enterprise IAM is implemented on a separate product line

🆕 v0.5.0 Capability Snapshot

Capability	Status	Description
Skill Self-Evolution	✅	Runtime tool-call observation capture, auto-skill creation via session review, quality gate / usage stats / deprecation loop (`learning`)
Multi-Brain Knowledge	✅	Isolatable/mountable "doc brain + code brain" with cross-brain search (`brain`) + multi-codebase hybrid semantic index (`code_index`)
Long-Horizon Coding	✅	Long-run orchestration (multi-source / isolated workspaces / stall self-healing / continuation backoff, `longrun`) + disk-backed project state machine (`project_state`)
IM Channel Integration	✅	Remote command gateway for Feishu / WeCom / DingTalk / personal WeChat (iLink) (`gateway`)
Claude Code Bridge	✅	Token-protected local HTTP/NDJSON control plane, headless / visible TUI dual mode (`cc_bridge`)
Extension Ecosystem	✅	AGX Bundle definitions, local install/uninstall, multi-source registry aggregated search (`extensions`)
Embeddable ReActAgent	✅	Canonical async function-calling ReAct SDK primitive with typed event stream, multi-turn history, parallel tools, optional loop-detector / compactor / offloader, zero Studio/CLI coupling (`agents`)
Unified Offload & MCP Gateway	✅	`Offloader` protocol + `FileOffloader` for out-of-history large payloads, plus in-workspace MCP gateway (AgentScope v2 P0 internalization, `core.offload` / `sandbox.mcp_gateway`)

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 read CONTRIBUTING.md (中文：CONTRIBUTING_ZN.md) before opening a PR. In short:

Submit Issues to report bugs or request features
Fork the project and create a scoped feature branch (feat/ / fix/ / …)
Submit Pull Requests with Conventional Commits; run the relevant tests (and Desktop npm run build when UI changes)
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.

Citation

If you use AgenticX in your research, please cite:

@software{agenticx2026,
  author  = {{AgenticX Team}},
  title   = {AgenticX: Unified Multi-Agent Framework},
  year    = {2026},
  url     = {https://github.com/DemonDamon/AgenticX},
  license = {Apache-2.0}
}

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 — a few entries are external products rather than open-source repositories, where we studied their public documentation and design instead of their source. We are genuinely grateful to every author, contributor, and community behind them.

Project	Repository	What we learned
A2A	a2aproject/A2A	Agent-to-Agent protocol design
AgentCPM-GUI	OpenBMB/AgentCPM-GUI	Compact GUI action schema & RFT training
ADK Python	google/adk-python	Agent lifecycle, runner abstractions
ag-ui	ag-ui-protocol/ag-ui	Agent–UI streaming protocol
AgentKit SDK	volcengine/agentkit-sdk-python	Agent deployment & skill packaging
AgentRun SDK	Serverless-Devs/agentrun-sdk-python	Serverless agent runtime patterns
AgentScope	agentscope-ai/agentscope	Multi-agent communication & pipeline
Agno	agno-agi/agno	Lightweight agent framework design
Better Harness	QoderAI/better-harness	Evidence-graded session loop review (Present / Wired / Exercised / Outcome-supported)
Camel	camel-ai/camel	Role-playing agents & society simulation
Cherry Studio	CherryHQ/cherry-studio	Desktop UX, MCP integration, skill system
Claude Code	anthropics/claude-code	Agentic CLI UX & plugin architecture
CLI-Anything	HKUDS/CLI-Anything	CLI-native agent harness
ClawTeam	HKUDS/ClawTeam	Multi-agent team coordination
CodexMonitor	Dimillian/CodexMonitor	Desktop monitoring & Tauri app patterns
CrewAI	crewAIInc/crewAI	Crew orchestration, flow & memory system
Cumora	yetone/cumora	Team chat where agents are first-class teammates, plus human-agent group coordination
DeepSeek Harness	deepseek-ai/deepseek-harness	Long-run turn hardening: overflow retry, interrupted closers, fail-closed persist, context reset with bounded handoff
DeepWiki Open	AsyncFuncAI/deepwiki-open	Repository-level knowledge indexing
Deer Flow	bytedance/deer-flow	Deep research workflow & skill harness
Eigent	eigent-ai/eigent	Multi-agent workforce & SSE event spec
Grok Bot	docs.x.ai/grok-bot	Persistent named teammates, shared computer, independent coordination, and learn-from-demo workflows
Iron Claw	nearai/ironclaw	Agent evaluation & benchmark harness
JoyAgent / JD Genie	jd-opensource/joyagent-jdgenie	Enterprise agent orchestration
Khazix Skills	KKKKhazix/Khazix-Skills	Skill module structure & packaging
Lobe Icons	lobehub/lobe-icons	AI provider icon design system
LoongSuite Python Agent	alibaba/loongsuite-python-agent	OpenTelemetry GenAI instrumentation
MAI-UI	Tongyi-MAI/MAI-UI	Device-cloud collaboration & GUI grounding
Microsandbox	zerocore-ai/microsandbox	Lightweight sandboxed code execution
MobiAgent	IPADS-SAI/MobiAgent	Mobile multi-stage planning
MobileAgent	X-PLUG/MobileAgent	Multi-agent mobile GUI automation
Model Context Protocol	modelcontextprotocol/modelcontextprotocol	Standardized LLM tool/resource protocol
NVIDIA NemoClaw	NVIDIA/NemoClaw	GPU-accelerated agent plugin system
OpenClaw	openclaw/openclaw	Open desktop agent platform & extensions
OpenSandbox	alibaba/OpenSandbox	Container-based code sandbox
OpenShell	NVIDIA/OpenShell	Rust-based secure agent shell
OpenSkills	numman-ali/openskills	Skill registry & discovery
OWL	camel-ai/owl	Embodied multi-agent collaboration
PenguinHarness	Prism-Shadow/penguin-harness	Execution timeline (Trajectory) UX & tool-span observability
Pydantic AI	pydantic/pydantic-ai	Type-safe agent & eval framework
Refly	refly-ai/refly	AI-native knowledge canvas UX
Serverless Devs	Serverless-Devs/Serverless-Devs	Serverless agent deployment toolchain
Skills	anthropics/skills	Skill definition format & lifecycle
Spring AI	spring-projects/spring-ai	Enterprise AI abstraction patterns
SWE-agent	SWE-agent/SWE-agent	Software engineering agent & ACR loop
VE ADK	volcengine/veadk-python	Skills system & cloud-native A2A
ZeroBoot	zerobootdev/zeroboot	Zero-config agent bootstrapping

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

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.githooks		.githooks
.github		.github
agenticx		agenticx
assets		assets
conclusions		conclusions
deploy		deploy
desktop		desktop
docs		docs
enterprise		enterprise
examples		examples
packaging		packaging
research		research
scripts		scripts
tests		tests
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTING_ZN.md		CONTRIBUTING_ZN.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
README_ZN.md		README_ZN.md
install.sh		install.sh
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
requirements.lock		requirements.lock
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation

Security advisory

Vision

System Architecture

Core Features

Core Framework

Avatar & Team Collaboration

Knowledge & Retrieval

Skills & Self-Evolution

Long-Horizon Autonomous Coding

Developer Entry Points

Near Desktop

AgenticX Enterprise

Security and Sandbox

Observability & Evaluation

Storage Layer

GUI Agent / Embodiment

Quick Start

Installation

Option 1: Install from PyPI (Recommended)

Option 2: Install from Source (Development)

Environment Setup

CLI Quick Start

Create Your First Agent

Tool Usage Example

Complete Examples

Agent Core (M5)

Orchestration & Validation (M6 & M7)

Agent Communication (M8)

Observability Monitoring (M9)

Memory System

Human-in-the-Loop

LLM Integration

Security Sandbox

Intent Recognition Service

GUI Agent / Embodiment (M16)

More Application Examples

Technical Architecture

Product and Runtime Paths

Core Framework Internals

Development Progress

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

🚧 Planned Modules

🆕 v0.5.0 Capability Snapshot

Core Advantages

System Requirements

Contributing

Acknowledgements / Upstream Credits

Citation

License

Star History

Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages