A unified agent technology stack spanning the Python Agent Runtime, Near Desktop, and Enterprise
Product Architecture • Core Capabilities • 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 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 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 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/AgentExecutorplus an independentReActAgentpath 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-serverover 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 servebackend 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 - **Sandb