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.
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
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
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
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
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
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
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
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.
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:
# 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
Developer Experience — CLI (agx with 20+ 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
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
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.
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:
This project is licensed under the Apache License, Version 2.0 — see the LICENSE file for details.
Star us on GitHub
If AgenticX is interesting/useful to you, please scroll up and give the repo a star (scroll to the top of this page -> click Star in top right). Stars are how most users hear about AgenticX because they move us up GitHub's search and trending pages.
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.
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 m