AgentX

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

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

Event-driven Runtime · Simple Framework · Minimal UI · Ready-to-use Portal

事件驱动 · 简易开发 · 界面简约 · 开箱即用

English | 简体中文

---

🚀 Quick Start

Option 1: npx (One-liner)

Quick try with Node.js 20+:

LLM_PROVIDER_KEY=sk-ant-xxxxx \
LLM_PROVIDER_URL=https://api.anthropic.com \
npx @agentxjs/portagent

Option 2: Docker (Recommended for Production)

Stable, no compilation required:

docker run -d \
  --name portagent \
  -p 5200:5200 \
  -e LLM_PROVIDER_KEY=sk-ant-xxxxx \
  -e LLM_PROVIDER_URL=https://api.anthropic.com \
  -v ./data:/home/node/.agentx \
  deepracticexs/portagent:latest

Open http://localhost:5200 and start chatting!

What You Get

• Multi-User Support - User registration (invite code optional)
• Session Persistence - Resume conversations anytime
• Real-time Streaming - WebSocket-based communication
• Docker Ready - Production-ready with health checks

Tip: Add -e INVITE_CODE_REQUIRED=true to enable invite code protection.

👉 Full Portagent Documentation - Configuration, deployment, API reference

---

🛠️ Build with AgentX

AgentX is a TypeScript framework for building AI Agent applications with event-driven architecture.

Server-side (Node.js)

import { createServer } from "http";
import { createAgentX, defineAgent } from "agentxjs";

// Define your Agent
const MyAgent = defineAgent({
  name: "MyAgent",
  systemPrompt: "You are a helpful assistant.",
  mcpServers: {
    // Optional: Add MCP servers for tools
    filesystem: {
      command: "npx",
      args: ["-y", "@anthropic/mcp-server-filesystem", "/tmp"],
    },
  },
});

// Create HTTP server
const server = createServer();

// Create AgentX instance
const agentx = await createAgentX({
  llm: {
    apiKey: process.env.LLM_PROVIDER_KEY,
    baseUrl: process.env.LLM_PROVIDER_URL,
  },
  agentxDir: "~/.agentx", // Auto-configures SQLite storage
  server, // Attach WebSocket to HTTP server
  defaultAgent: MyAgent, // Default agent for new conversations
});

// Start server
server.listen(5200, () => {
  console.log("✓ Server running at http://localhost:5200");
  console.log("✓ WebSocket available at ws://localhost:5200/ws");
});

Client-side (Browser/React)

import { useAgentX, ResponsiveStudio } from "@agentxjs/ui";
import "@agentxjs/ui/styles.css";

function App() {
  const agentx = useAgentX("ws://localhost:5200/ws");

  if (!agentx) return <div>Connecting...</div>;

  return <ResponsiveStudio agentx={agentx} />;
}

👉 Full AgentX Documentation - Architecture, API reference, guides, and examples

---

🏗️ 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 → Claude SDK
  ← Output: SDK → BUS → AgentEngine → BUS → Client

---

💬 About

AgentX is in early development. We welcome your ideas, feedback, and feature requests!

🌐 Ecosystem

Part of the Deepractice AI development ecosystem:

• PromptX - Prompt engineering and management framework
• DPML - Deepractice Markup Language for AI workflows
• DARP - Deepractice Agent Runtime Protocol
• Lucid-UI - AI-powered UI component library

📞 Connect

Connect with the Founder

📧 sean@deepractice.ai

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

---

Built with ❤️ by Deepractice