AgentX

Next-generation open-source AI agent development framework and runtime platform

下一代开源 AI 智能体开发框架与运行时平台

Event-driven Runtime · Multi-provider LLM · RoleX Integration · TypeScript First

English | 简体中文

---

🚀 Quick Start

Local Mode (Embedded)

Build an AI agent in a few lines of TypeScript:

import{createAgentX}from"agentxjs";import{nodePlatform}from"@agentxjs/node-platform";import{createMonoDriver}from"@agentxjs/mono-driver";constcreateDriver=(config)=>createMonoDriver({
...config,apiKey: process.env.ANTHROPIC_API_KEY,provider: "anthropic",});constplatform=awaitnodePlatform({ createDriver }).resolve();constax=createAgentX({ platform, createDriver });// Create a conversation and chatconstagent=awaitax.chat.create({name: "My Assistant",systemPrompt: "You are a helpful assistant.",});ax.on("text_delta",(e)=>process.stdout.write(e.data.text));awaitagent.send("Hello!");

Server Mode

Expose your agent as a WebSocket server:

constax=createAgentX({ platform, createDriver });constserver=awaitax.serve({port: 5200});

Remote Mode (WebSocket Client)

Connect to a running AgentX server:

import{createAgentX}from"agentxjs";constax=createAgentX();constclient=awaitax.connect("ws://localhost:5200");// Same API as local modeconstagent=awaitclient.chat.create({name: "My Assistant"});awaitagent.send("Hello!");

CLI

Interactive terminal chat:

cd apps/cli
cp .env.example .env.local # Set DEEPRACTICE_API_KEY
bun run dev

---

🧩 Core Concepts

AgentX uses a layered concept model inspired by container runtimes:

Prototype (template) → Image (persistent) → Agent (runtime)
↓ ↓ ↓
Reusable definition Stored in DB Running in memory
Registered once Has session Has lifecycle
Like Dockerfile Like Docker image Like container

• Image — persistent agent record with flat config (model, systemPrompt, mcpServers, etc.)
• Chat — a conversation backed by an Image, accessed via AgentHandle
• AgentContext — merged runtime configuration passed from Runtime to Driver
• SendOptions — per-request overrides (model, thinking, providerOptions)

API Architecture

ax.chat.*// Conversation management (create, list, get → AgentHandle)ax.provider.*// LLM provider configurationax.runtime.*// Low-level subsystems (image, session, container)

Per-Request Overrides with SendOptions

Override model, thinking, or provider options on each send:

// Create with default configconstagent=awaitax.chat.create({name: "Code Reviewer",model: "claude-sonnet-4-6",systemPrompt: "You are a code review assistant.",});// Override per-requestawaitagent.send("Review this PR...",{thinking: "high"});awaitagent.send("Quick question",{model: "claude-haiku-4-5"});

---

🛠️ Packages

Package	Description
agentxjs	Client SDK — local, remote, and server modes
@agentxjs/core	Core abstractions — Container, Image, Session, Driver
@agentxjs/node-platform	Node.js platform — SQLite persistence, WebSocket
@agentxjs/mono-driver	Multi-provider LLM driver (Anthropic, OpenAI, Google, etc.)
@agentxjs/claude-driver	Claude-specific driver with extended features
@agentxjs/devtools	BDD testing tools — MockDriver, RecordingDriver, Fixtures

Multi-Provider Support

MonoDriver supports multiple LLM providers via Vercel AI SDK:

• Anthropic (Claude) — provider: "anthropic"
• OpenAI (GPT) — provider: "openai"
• Google (Gemini) — provider: "google"
• DeepSeek — provider: "deepseek"
• Mistral — provider: "mistral"
• xAI (Grok) — provider: "xai"
• OpenAI-compatible — provider: "openai-compatible"

RoleX Integration

MonoDriver integrates with RoleX for AI role management — identity, goals, knowledge, and cognitive growth cycles:

import{localPlatform}from"@rolexjs/local-platform";constdriver=createMonoDriver({
...config,rolex: {platform: localPlatform(),roleId: "my-role",},});

---

🏗️ Architecture

Event-driven architecture with layered design:

SERVER SIDE SYSTEMBUS CLIENT SIDE
═══════════════════════════════════════════════════════════════════════════
║
┌─────────────────┐ ║
│ Environment │ ║
│ • LLMProvider │ emit ║
│ • Sandbox │─────────────────>║
└─────────────────┘ ║
║
║
┌─────────────────┐ subscribe ║
│ Agent Layer │<─────────────────║
│ • AgentEngine │ ║
│ • Agent │ emit ║
│ │─────────────────>║ ┌─────────────────┐
│ 4-Layer Events │ ║ │ │
│ • Stream │ ║ broadcast │ WebSocket │
│ • State │ ║════════>│ (Event Stream) │
│ • Message │ ║<════════│ │
│ • Turn │ ║ input │ AgentX API │
└─────────────────┘ ║ └─────────────────┘
║
║
┌─────────────────┐ ║
│ Runtime Layer │ ║
│ │ emit ║
│ • Persistence │─────────────────>║
│ • Container │ ║
│ • WebSocket │<─────────────────╫
│ │─────────────────>║
└─────────────────┘ ║
║
[ Event Bus ]
[ RxJS Pub/Sub ]
Event Flow:
→ Input: Client → WebSocket → BUS → LLM Driver
← Output: Driver → BUS → AgentEngine → BUS → Client

---

💬 About

AgentX is in active development. We welcome your ideas, feedback, and contributions!

🌐 Ecosystem

Part of the Deepractice AI infrastructure:

• RoleX — AI role management system (identity, cognition, growth)
• ResourceX — Unified resource manager
• IssueX — Structured issue tracking for AI collaboration

📞 Connect

Connect with the Founder

📧 sean@deepractice.ai

Scan to connect with Sean (Founder & CEO) on WeChat

---

Built with ❤️ by Deepractice