Related Pages

Related topics: System Architecture, Quick Start Guide

Introduction to AgenticX

Overview

AgenticX is a comprehensive multi-platform AI agent framework designed to enable intelligent autonomous agents ("分身", "avatars") capable of executing complex tasks across enterprise and desktop environments. The framework provides a unified architecture for building, deploying, and managing AI agents with built-in support for skill management, task automation, knowledge bases, and enterprise identity & access management (IAM).

Sources: enterprise/features/agents/README.md:1 Sources: examples/agenticx-for-agentkit/README.md:1

Platform Architecture

AgenticX consists of three primary deployment surfaces:

Sources: enterprise/apps/admin-console/src/app/audit/page.tsx:1 Sources: enterprise/apps/web-portal/src/app/auth/page.tsx:1 Sources: desktop/src/components/SettingsPanel.tsx:1

Architecture Diagram

graph TD
    subgraph Enterprise["Enterprise Layer"]
        A[Admin Console] --> B[IAM System]
        A --> C[Audit Logs]
        A --> D[Model Management]
        B --> E[Users]
        B --> F[Roles]
        B --> G[Departments]
    end
    
    subgraph Desktop["Desktop Layer"]
        H[Desktop App] --> I[Skill Manager]
        H --> J[Task Automation]
        H --> K[Settings Panel]
        H --> L[WeChat Integration]
    end
    
    subgraph Integration["External Integrations"]
        M[Volcano Engine]
        N[AgentKit]
        O[Knowledge Base]
    end
    
    Desktop --> Integration
    Enterprise --> Desktop

Core Components

1. Agent Feature Module

The agent feature (@agenticx/feature-agents) provides the core agentic capabilities for creating intelligent avatars ("分身") that can autonomously execute tasks.

Sources: enterprise/features/agents/README.md:5

2. Knowledge Base Feature

The knowledge base module (@agenticx/feature-knowledge-base) enables agents to access and utilize structured information repositories for enhanced decision-making.

Sources: enterprise/features/knowledge-base/README.md:1

3. Task Automation System

The desktop application supports automated task execution with configurable prompts, workspace assignments, and model selection.

Sources: desktop/src/components/automation/TaskList.tsx:10

4. Settings Management

The desktop application provides comprehensive settings management including:

• Provider Configuration: API keys and model selection
• Environment Dependencies: External executable management with installation states (installed, installing, manual_required, not_installed)
• Global Tool Paths: Third-party tool scanning configuration
• WeChat Integration: Personal WeChat binding via iLink protocol
• GWS Studio Configuration: Gateway studio base URL settings

Sources: desktop/src/components/SettingsPanel.tsx:1 Sources: desktop/src/store.ts:1

Enterprise Identity & Access Management (IAM)

User Management

The admin console provides comprehensive user management with the following capabilities:

• User search by email, name, or ID
• Status filtering (active/inactive/all)
• Department filtering
• Pagination with configurable page size
• User detail drawer with edit capabilities

Sources: enterprise/apps/admin-console/src/app/iam/users/page.tsx:1

Role Management

Role-based access control with scope matrix editor for granular permission configuration:

graph LR
    A[Role] --> B[Code]
    A --> C[Display Name]
    A --> D[Permissions/Scopes]
    D --> E[audit:read]
    D --> F[users:manage]
    D --> G[models:configure]
    D --> H[roles:admin]

Sources: enterprise/apps/admin-console/src/app/iam/roles/page.tsx:1

Department Hierarchy

Hierarchical organizational structure with the following features:

• Tree-based department navigation
• Drill-down navigation with breadcrumb trail
• Export department structure functionality
• Refresh capabilities for real-time updates

Sources: enterprise/apps/admin-console/src/app/iam/departments/page.tsx:1

Bulk Import

CSV-based bulk user provisioning with a 5-step workflow:

1. Upload CSV - Drag & drop or paste CSV content
2. Column Mapping - Map CSV columns to system fields
3. Pre-check - Validate data integrity and constraints
4. Server Write - Batch write to backend with transaction support
5. Results - Success/failure reporting with downloadable failure CSV

Sources: enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx:1

Audit & Compliance

Audit Log System

Comprehensive audit logging with table chain verification:

• Event type filtering
• User and model search
• Full table chain validation status
• Chain integrity indicators (complete/failed)
• Scanned row counts

Sources: enterprise/apps/admin-console/src/app/audit/page.tsx:1

Security Compliance

The enterprise portal demonstrates commitment to security standards:

• Apache 2.0 License
• ISO27001 Certification
• SOC2 Compliance

Sources: enterprise/apps/web-portal/src/app/auth/page.tsx:1

Model Management

The admin console provides centralized model configuration:

• Provider Management: Add/remove AI providers
• Model Registration: Add models with custom IDs and display labels
• Provider Templates: Pre-configured provider templates for quick setup

Sources: enterprise/apps/admin-console/src/app/admin/models/page.tsx:1

External Integrations

AgentKit Integration

AgenticX supports integration with LangChain's AgentKit framework for Volcano Engine deployment:

# Deployment workflow
agx volcengine deploy --region <region> --app-name <name>
agx volcengine logs [--follow]
agx volcengine destroy

The integration includes:

• Complete agent definition templates
• Docker deployment configurations
• Synchronous and asynchronous testing support
• Tool definition examples

Sources: examples/agenticx-for-agentkit/README.md:1

WeChat Integration

Desktop application supports personal WeChat binding via the official iLink protocol:

• QR code scanning for account binding
• Automatic sidecar service management
• Message relay to Machi agent for agent execution

Sources: desktop/src/components/SettingsPanel.tsx:1

Skill Management

Skills extend agent capabilities through modular configurations:

Sources: desktop/src/components/SettingsPanel.tsx:1 Sources: desktop/src/components/automation/TaskList.tsx:1

State Management

The desktop application uses a centralized store architecture:

graph TD
    A[Global Store] --> B[Chat Panes]
    A --> C[Agent Management]
    A --> D[Settings State]
    A --> E[Token Dashboard]
    A --> F[Confirmation Dialogs]
    
    B --> B1[Messages]
    B --> B2[Session History]
    B --> B3[Context Inheritance]
    
    C --> C1[Sub Agents]
    C --> C2[Selected Agent]
    
    D --> D1[Provider Config]
    D --> D2[Model Config]
    D --> D3[API Keys]

Key store functions:

• addSubAgent / removeSubAgent - Agent lifecycle management
• setSelectedSubAgent - Active agent switching
• openSettings / updateSettings - Configuration management
• openTokenDashboard - Usage monitoring
• openConfirm / closeConfirm - User confirmation workflow

Sources: desktop/src/store.ts:1

Related Pages

Related topics: Installation Guide, Agent Core System

Quick Start Guide

AgenticX is a multi-agent collaboration framework that enables intelligent agents (referred to as "分神" or avatars) to work together using various collaboration patterns. This guide provides a streamlined path to getting started with AgenticX for development and deployment.

Prerequisites

Before you begin, ensure your environment meets the following requirements:

Sources: examples/agenticx-for-intent-recognition/README.md

Installation

Core Package

Install the AgenticX core package using pip:

pip install agenticx

Sources: examples/agenticx-for-agentkit/README.md

Example Dependencies

For specific integrations, install example-specific requirements:

pip install -r requirements.txt

Project Structure

A typical AgenticX project follows this structure:

agenticx-for-intent-recognition/
├── main.py              # Main entry point
├── config.yaml          # Configuration file
├── requirements.txt     # Python dependencies
├── agents/              # Agent definitions
├── workflows/           # Workflow definitions
├── tools/               # Tool implementations
└── tests/               # Test suite

Sources: examples/agenticx-for-intent-recognition/README.md

Configuration

Step 1: Create Configuration File

Copy the config.yaml template and configure your API keys:

# Example config.yaml structure
provider: openai
model: gpt-4o-mini
api_key: your-api-key-here

Step 2: Adjust Settings

Modify configuration parameters based on your requirements:

• Model Selection: Choose appropriate models for your use case
• API Endpoint: Configure provider-specific endpoints if needed
• Timeout Settings: Adjust request timeouts for long-running tasks

Sources: examples/agenticx-for-intent-recognition/README.md

Building Your First Agent

Basic Agent Creation

Create a simple agent using the AgenticX core API:

from agenticx import Agent, AgentConfig

config = AgentConfig(
    name="demo_agent",
    model="gpt-4o-mini",
    tools=["bash_exec", "file_read"]
)

agent = Agent(config)

Agent Patterns

AgenticX supports multiple collaboration patterns. Register custom patterns in the manager:

from agenticx.collaboration import CollaborationMode, CustomPattern

pattern_classes = {
    CollaborationMode.CUSTOM_PATTERN: CustomPattern,
}

Sources: agenticx/collaboration/README.md

Collaboration Patterns

AgenticX provides built-in collaboration modes for multi-agent scenarios:

graph TD
    A[User Request] --> B[Manager Agent]
    B --> C[Sub-Agent 1]
    B --> D[Sub-Agent 2]
    B --> E[Sub-Agent N]
    C --> F[Result Aggregation]
    D --> F
    E --> F
    F --> G[Final Response]
    
    style B fill:#e1f5fe
    style F fill:#fff3e0

Available Patterns

Sources: agenticx/collaboration/README.md

Enterprise Features

The enterprise edition extends AgenticX with additional capabilities:

Available Feature Modules

Sources: enterprise/features/agents/README.md, enterprise/features/knowledge-base/README.md, enterprise/features/iam/README.md, enterprise/features/tools-mcp/README.md

Feature Module Usage

import { featureName } from "@agenticx/feature-agents";

CLI Commands

AgenticX provides a command-line interface for common operations:

Deployment Example (Volcengine)

agx volcengine deploy    # Deploy to Volcengine
agx logs --follow        # Monitor deployment
agx volcengine destroy   # Clean up resources

Sources: examples/agenticx-for-agentkit/README.md

Running the Project

Execute your AgenticX application:

python main.py

Sources: examples/agenticx-for-intent-recognition/README.md

Testing

Running Tests

Execute the test suite to validate your implementation:

pytest tests/

Test Structure

Organize tests following the project structure:

tests/
├── test_agents.py       # Agent behavior tests
├── test_workflows.py    # Workflow execution tests
└── test_integration.py  # End-to-end integration tests

Deployment

Docker Deployment

The project includes Dockerfile support for containerized deployment:

# Refer to examples/agenticx-for-agentkit/hi-agent/Dockerfile

Cloud Deployment

``bash agx volcengine deploy ``

``bash agx logs --follow ``

1. Configure cloud provider credentials
2. Run deployment command:
3. Monitor logs:

Sources: examples/agenticx-for-agentkit/README.md

Next Steps

Troubleshooting

Common Issues

Getting Help

For additional support:

• Open an issue on GitHub
• Consult the project documentation
• Review the collaboration patterns academic paper

Related Pages

Related topics: Quick Start Guide

Installation Guide

Overview

The Installation Guide provides comprehensive instructions for setting up the AgenticX environment across different deployment scenarios. AgenticX is a monorepo containing enterprise applications, desktop clients, and backend services that require specific configuration and dependency management.

System Architecture Overview

    A[AgenticX Monorepo] --> B[Python Backend Core]
    A --> C[Enterprise Applications]
    A --> D[Desktop Client]
    B --> E[API Services]
    B --> F[Agent Engine]
    C --> G[Admin Console]
    C --> H[Web Portal]
    D --> I[Settings Panel]
    D --> J[ChatPane Interface]

Prerequisites

System Requirements

External Dependencies

The desktop application requires several external executable dependencies that can be installed globally once and shared across all instances.

    A[External Tools] --> B[Python Packages]
    A --> C[Node.js Packages]
    A --> D[System Binaries]
    B --> E[adalflow]
    B --> F[agenticx-core]
    D --> G[agx CLI Tool]

Sources: pyproject.toml

Python Package Installation

Project Structure

The Python backend uses Poetry for dependency management with the following key packages:

Installation Commands

# Clone the repository
git clone https://github.com/DemonDamon/AgenticX.git
cd AgenticX

# Install backend dependencies using Poetry
poetry install

# Or using pip with pyproject.toml
pip install -e .

Sources: INSTALL.md

Environment Variables

The application requires specific environment variables for configuration:

Enterprise Applications

Admin Console Setup

The enterprise admin console is a Next.js application located in enterprise/apps/admin-console/.

graph LR
    A[Admin Console] --> B[IAM Module]
    A --> C[Models Module]
    A --> D[Audit Module]
    B --> E[Roles Management]
    B --> F[User Bulk Import]

Sources: enterprise/apps/admin-console/src/app/iam/roles/page.tsx

Installation Steps

cd enterprise/apps/admin-console

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local

# Start development server
npm run dev

Web Portal Setup

The web portal application provides the public-facing interface.

Sources: enterprise/apps/web-portal/src/app/auth/page.tsx

Desktop Application

Architecture

The desktop client provides a native interface for the AgenticX system with the following key components:

    A[Desktop Client] --> B[Settings Panel]
    A --> C[ChatPane]
    A --> D[Task Automation]
    A --> E[Skills Manager]
    A --> F[Token Dashboard]
    
    B --> G[Provider Configuration]
    B --> H[API Base Settings]
    B --> I[Theme Settings]
    
    C --> J[Sub Agents]
    C --> K[History Panel]
    C --> L[Spawns Column]

Sources: desktop/src/components/SettingsPanel.tsx

Desktop-Specific Installation

The desktop application requires additional native dependencies and configurations:

#### WeChat Integration Setup

The desktop client supports WeChat integration via the iLink protocol:

interface WeChatStatus {
  port: number;
  running: boolean;
}

// Initialize WeChat sidecar
const { port, running } = await window.agenticxDesktop.wechatSidecarPort();
if (!running) {
  const startRes = await window.agenticxDesktop.wechatSidecarStart();
  sidecarPort = startRes.port;
}

Sources: desktop/src/components/SettingsPanel.tsx

#### Skills Management

The desktop application includes a skills management system that scans multiple locations:

Sources: desktop/src/components/SettingsPanel.tsx

Desktop IPC API

The desktop client exposes a comprehensive IPC API for configuration and skill management:

interface AgenticXDesktopAPI {
  getSkillSettings(): Promise<SkillSettingsResult>;
  putSkillSettings(payload: SkillSettingsPayload): Promise<SkillSettingsResult>;
  refreshSkills(): Promise<SkillRefreshResult>;
  
  installBundle(args: BundleInstallArgs): Promise<BundleInstallResult>;
  uninstallBundle(args: { name: string }): Promise<BundleUninstallResult>;
  
  installFromRegistry(args: RegistryInstallArgs): Promise<RegistryInstallResult>;
  searchRegistry(args: { q: string }): Promise<RegistrySearchResult>;
}

Sources: desktop/src/global.d.ts

Advanced Configuration

Token Dashboard

The desktop client includes a token usage dashboard with configurable date ranges:

type TokenDashboardRange = '7d' | '30d' | '90d' | 'custom';

interface TokenDashboardState {
  range: TokenDashboardRange;
  customFrom?: string;
  customTo?: string;
}

Sources: desktop/src/store.ts

Model Provider Configuration

Support for multiple LLM providers with per-provider configuration:

Theme and UI Settings

Verification and Testing

Post-Installation Checks

After installation, verify the setup using these checks:

1. Backend Connectivity: Confirm API base URL is accessible
2. Authentication: Verify token is valid and has required permissions
3. Skills Scanning: Check that skill locations are properly configured
4. Bundle Installation: Test bundle install/uninstall operations

Common Issues

Repository Structure Summary

AgenticX/
├── enterprise/
│   ├── apps/
│   │   ├── admin-console/    # IAM, Models, Audit
│   │   └── web-portal/       # Public portal
│   └── ...
├── desktop/
│   ├── src/
│   │   ├── components/       # UI components
│   │   ├── store.ts          # State management
│   │   └── global.d.ts       # Type definitions
│   └── ...
├── pyproject.toml            # Python dependencies
└── INSTALL.md               # Installation instructions

Sources: pyproject.toml, INSTALL.md

Related Pages

Related topics: Core Abstractions, Agent Core System

System Architecture

Overview

AgenticX is a comprehensive multi-component AI agent platform designed to enable intelligent automation, multi-agent collaboration, and enterprise-grade management. The system architecture follows a modular design pattern with clear separation between core processing engines, enterprise management interfaces, and client applications.

Sources: enterprise/features/agents/README.md

High-Level Architecture

The AgenticX platform comprises three primary layers:

1. Core Engine Layer — Python-based agent runtime with workflow orchestration
2. Enterprise Management Layer — Web-based admin console and web portal
3. Client Application Layer — Desktop client application

graph TB
    subgraph Core["Core Engine Layer"]
        WF["Workflow Engine"]
        AG["Agent Core"]
        MEM["Memory System"]
        KNOW["Knowledge Base"]
    end
    
    subgraph Enterprise["Enterprise Management Layer"]
        AC["Admin Console"]
        WP["Web Portal"]
        IAM["IAM System"]
    end
    
    subgraph Client["Client Application Layer"]
        DESK["Desktop App"]
        UI["React Components"]
    end
    
    DESK --> WF
    AC --> IAM
    WP --> IAM
    WF --> AG
    WF --> MEM
    WF --> KNOW

Component Architecture

Core Engine Layer

The core engine provides the foundational AI agent capabilities including tool execution, memory management, and knowledge retrieval.

Sources: examples/agenticx-for-agentkit/README.md

#### Agent Core

The Agent Core handles fundamental agent operations:

#### Workflow Engine

The workflow engine orchestrates multi-step agent tasks with support for both synchronous and asynchronous execution patterns.

Sources: desktop/src/store.ts

Enterprise Management Layer

The enterprise layer provides centralized management capabilities for users, roles, and system configuration.

#### Admin Console

The Admin Console (enterprise/apps/admin-console/) is a Next.js application that provides administrative functions:

• User Management — Create, edit, and manage user accounts with search and filtering capabilities
• Role Management — Define roles with granular permission scopes
• Audit Logs — Track system events with chain verification for data integrity
• Model Management — Configure AI provider models
• Bulk Operations — CSV-based bulk user import with pre-validation

Sources: enterprise/apps/admin-console/src/app/iam/users/page.tsx

graph LR
    subgraph AdminConsole["Admin Console"]
        US["Users Module"]
        RL["Roles Module"]
        AU["Audit Module"]
        MD["Models Module"]
        BI["Bulk Import Module"]
    end
    
    US --> IAM["IAM Backend"]
    RL --> IAM
    AU --> IAM
    MD --> IAM
    BI --> IAM

#### Web Portal

The Web Portal (enterprise/apps/web-portal/) serves as the main user interface for end users, providing:

• Authentication services
• Workspace management
• Theme and preference settings
• Multi-language support (Chinese and English)
• Admin console navigation integration

Sources: enterprise/apps/web-portal/src/app/auth/page.tsx

#### Identity and Access Management (IAM)

The IAM system manages authentication and authorization across the platform:

Sources: enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx

The bulk import workflow follows a step-based process:

1. Upload CSV — File upload or text paste with automatic parsing
2. Column Mapping — Map CSV columns to system fields
3. Pre-check — Validate all rows before submission
4. Execute Import — Server-side batch write with failure tracking
5. Results — Display success/failure counts with downloadable failure report

Client Application Layer

#### Desktop Application

The Desktop Application (desktop/) is a React-based client with the following key components:

Sources: desktop/src/components/SettingsPanel.tsx

graph TD
    ST["Store (Zustand)"]
    SP["SettingsPanel"]
    TL["TaskList"]
    CP["ChatPane"]
    
    ST --> SP
    ST --> TL
    ST --> CP
    
    SP --> |"provider/model"| ST
    TL --> |"task toggle"| ST
    CP --> |"messages"| ST

#### State Management

The desktop application uses Zustand for centralized state management with the following store structure:

Sources: desktop/src/store.ts

#### Task Automation

Tasks support the following configuration options:

Sources: desktop/src/components/automation/TaskList.tsx

Feature Modules

Enterprise features are implemented as standalone modules under enterprise/features/:

Sources: enterprise/features/agents/README.md

Integration Architecture

AgentKit Integration

AgenticX integrates with Volcano Engine's AgentKit for enhanced capabilities:

┌────────────────────────────────────────────────────┐
│                  AgenticX 框架                       │
├─────────────┬────────────┬───────────┬─────────────┤
│ Agent Core  │  Tools     │  Memory   │  Knowledge  │
└─────────────┴────────────┴───────────┴─────────────┘
                     │
          ┌──────────┴───────────┐
          │ AgentKit Integration │
          └──────────┬───────────┘
                     │
    ┌────────────────┼────────────────┐
    ▼                ▼                ▼
┌──────────┐  ┌───────────┐  ┌────────────┐
│ Ark LLM  │  │ Runtime   │  │ Bridges &  │
│ Provider  │  │ Client    │  │ Adapters   │
└──────────┘  └───────────┘  └────────────┘

Sources: examples/agenticx-for-agentkit/README.md

WeChat Integration

The desktop application supports WeChat integration via the iLink protocol:

graph LR
    WC["WeChat Client"]
    SD["Desktop Sidecar"]
    AG["AgenticX Desktop"]
    
    WC --> |"iLink Protocol"| SD
    SD --> AG
    AG --> |"Agent Execution"| SD

The sidecar service manages the WeChat connection with states:

• idle — No active binding
• binding — QR code scanning in progress
• connected — Active WeChat session

Sources: desktop/src/components/SettingsPanel.tsx

Security Architecture

Audit Chain Verification

The audit system implements chain verification to ensure log integrity:

Each audit log entry includes a chain signature that can be verified against the full table state.

Sources: enterprise/apps/admin-console/src/app/audit/page.tsx

Role-Based Permissions

Roles use a scope matrix for fine-grained permission control:

• Roles can be assigned multiple permission scopes
• Users can have multiple roles (role code aggregation)
• Role membership changes use PATCH operations for atomic updates

Sources: enterprise/apps/admin-console/src/app/iam/roles/page.tsx

Deployment Architecture

Project Templates

AgenticX provides deployment templates for different use cases:

Sources: examples/agenticx-for-agentkit/README.md

CLI Commands

Data Flow

Bulk Import Flow

sequenceDiagram
    participant U as User
    participant AC as Admin Console
    participant BE as Backend API
    
    U->>AC: Upload CSV
    AC->>AC: Parse & Display Preview
    U->>AC: Map Columns
    AC->>BE: Pre-check Request
    BE-->>AC: Validation Results
    alt Has Failures
        AC->>U: Display Failure Table
        U->>AC: Fix CSV / Remap
    else All Valid
        AC->>BE: Execute Import
        BE-->>AC: Success/Failure Report
        AC->>U: Show Results
    end

Task Execution Flow

graph TD
    START["Task Triggered"]
    CHECK{"Task Enabled?"}
    LOAD["Load Task Config"]
    EXEC["Execute Agent"]
    SUCCESS{"Success?"}
    LOG["Log Result"]
    ERR["Log Error"]
    END["Complete"]
    
    START --> CHECK
    CHECK --> |"No"| END
    CHECK --> |"Yes"| LOAD
    LOAD --> EXEC
    EXEC --> SUCCESS
    SUCCESS --> |"Yes"| LOG
    SUCCESS --> |"No"| ERR
    LOG --> END
    ERR --> END

Configuration Management

Environment Tools

The system supports external executable dependencies:

Sources: desktop/src/components/SettingsPanel.tsx

Theme and Localization

The platform supports dynamic theme switching:

Supported locales: zh (Chinese), en (English)

Sources: enterprise/apps/web-portal/src/components/WorkspaceShell.tsx

Related Pages

Related topics: System Architecture, Agent Core System, Tool System and MCP Hub

Core Abstractions

The Core Abstractions layer is the foundational component system underlying AgenticX's agent framework. It provides the essential building blocks—Agent, Task, Tool, Component, EventBus, and Message—that enable developers to construct autonomous AI agents with configurable behaviors, tool integration, and event-driven communication.

Related Pages

Related topics: Meta-Agent and Team Management, Tool System and MCP Hub, Memory System

Agent Core System

The Agent Core System is the central orchestration engine of AgenticX, responsible for executing AI agent tasks, managing execution lifecycle, ensuring safety through guardrails, validating task outputs, handling memory overflow scenarios, enabling self-repair capabilities, and providing reflective analysis of agent behavior.

Architecture Overview

graph TD
    subgraph "Agent Core System"
        A[Agent Executor] --> B[Task Validator]
        A --> C[Guiderails]
        A --> D[Overflow Recovery]
        A --> E[Self Repair]
        A --> F[Reflector]
    end
    
    G[Agent Input] --> A
    A --> H[Tool Execution]
    A --> I[Output]
    
    B -.->|Validation Result| A
    C -.->|Safety Check| A
    D -.->|Memory State| A
    E -.->|Repair Action| A
    F -.->|Reflection| A

The Agent Core System coordinates multiple subsystems to ensure reliable and safe agent execution while maintaining context awareness and self-healing capabilities.

Core Components

Agent Executor

The AgentExecutor serves as the central orchestrator that manages the complete lifecycle of agent task execution. It coordinates between various subsystems including validation, safety checks, memory management, and self-repair mechanisms.

Key Responsibilities:

• Task dispatch and execution orchestration
• State management across execution phases
• Coordination with external tool systems
• Integration with the broader AgenticX framework

Source: agenticx/core/agent_executor.py

Task Validator

The TaskValidator ensures that agent-generated outputs meet quality and correctness standards before being considered final results. It performs structural validation, semantic checks, and format verification.

Validation Criteria:

Source: agenticx/core/task_validator.py

Guiderails

The Guiderails module implements safety mechanisms that constrain agent behavior within defined boundaries. It monitors inputs, outputs, and tool invocations to prevent unintended or harmful actions.

Safety Features:

• Input sanitization and validation
• Output filtering and content moderation
• Tool usage policy enforcement
• Behavioral boundary enforcement

Source: agenticx/core/guiderails.py

Overflow Recovery

The OverflowRecovery system manages memory and context overflow scenarios that occur during extended agent sessions. It implements strategies to preserve critical context while managing resource constraints.

Recovery Strategies:

Source: agenticx/core/overflow_recovery.py

Self Repair

The SelfRepair module enables the agent to detect, diagnose, and correct its own errors without external intervention. It provides automated error recovery and behavioral correction capabilities.

Repair Mechanisms:

• Error detection and classification
• Root cause analysis
• Automatic correction application
• Repair history tracking

Source: agenticx/core/self_repair.py

Reflector

The Reflector provides introspective capabilities that allow the agent to analyze its own reasoning, decisions, and execution patterns. It generates insights about agent behavior and enables continuous improvement.

Reflection Capabilities:

• Reasoning path analysis
• Decision audit trails
• Performance metrics generation
• Behavioral pattern identification

Source: agenticx/core/reflector.py

Execution Flow

sequenceDiagram
    participant Input as Agent Input
    participant Executor as Agent Executor
    participant Validator as Task Validator
    participant Rails as Guiderails
    participant Overflow as Overflow Recovery
    participant Repair as Self Repair
    participant Reflect as Reflector
    participant Output as Final Output

    Input->>Executor: Task Request
    Executor->>Rails: Safety Check
    Rails-->>Executor: Approved/Blocked
    Executor->>Validator: Validate Task
    Validator-->>Executor: Validation Result
    Executor->>Overflow: Check Memory State
    Overflow-->>Executor: Memory Status
    Executor->>Executor: Execute Task
    Executor->>Repair: Error Detected?
    alt Error Detected
        Repair->>Repair: Analyze Error
        Repair->>Executor: Apply Fix
        Executor->>Executor: Retry
    end
    Executor->>Reflect: Log Execution
    Reflect-->>Executor: Reflection Complete
    Executor->>Output: Return Result

Integration with AgenticX Framework

The Agent Core System integrates with multiple parts of the AgenticX ecosystem:

Desktop Integration

The desktop application (desktop/) provides UI components that interact with the core system through a store-based state management architecture. Settings panels allow configuration of agent parameters, and task automation components interface with the executor for scheduled task execution.

Related Files:

• desktop/src/store.ts - State management
• desktop/src/components/SettingsPanel.tsx - Configuration UI
• desktop/src/components/automation/TaskList.tsx - Task automation

Enterprise Features

Enterprise features build upon the core system to provide additional capabilities:

Related Files:

• enterprise/features/knowledge-base/README.md
• enterprise/features/agents/README.md
• enterprise/features/iam/README.md

Admin Console

The enterprise admin console provides monitoring and management capabilities for the core system through audit logging and operational dashboards.

Related Files:

• enterprise/apps/admin-console/src/app/audit/page.tsx - Audit logging interface
• enterprise/apps/admin-console/src/app/admin/models/page.tsx - Model management

Configuration Options

The Agent Core System supports various configuration parameters:

Error Handling

The core system implements a hierarchical error handling approach:

1. Guiderails Prevention - Blocks known dangerous patterns
2. Validation Failure - Rejects invalid outputs with feedback
3. Self Repair Attempt - Automatic correction of recoverable errors
4. Overflow Recovery - Memory-related issue resolution
5. Reflector Documentation - Error logging for analysis

Related Documentation

• Sandbox System - Isolated execution environment
• Collaboration Mode - Multi-agent cooperation
• AgentKit Integration - External framework integration

Related Pages

Related topics: Agent Core System, Avatar and Group Chat

Meta-Agent and Team Management

Overview

Meta-Agent and Team Management in AgenticX refers to the system for orchestrating multiple AI agents ("分身", literally "avatars" or "clones") that can collaborate to accomplish complex tasks. The system provides a hierarchical management structure where a meta-agent coordinates teams of specialized agents, each with distinct capabilities, prompts, and tool configurations.

The architecture supports:

• Agent Lifecycle Management — creation, configuration, enabling/disabling of individual agents
• Team Coordination — grouping agents into collaborative units with shared context
• Skill Assignment — attaching modular skills to specific agents or globally
• Meta-Tool Orchestration — meta-agents that can delegate tasks to subordinate agents
• Execution Monitoring — tracking task runs, statuses, and error handling

Sources: enterprise/features/agents/README.md

Architecture

The system follows a layered architecture:

    User[User Interface]
    UI[SettingsPanel / AvatarCreateDialog]
    MetaAgent[Meta-Agent]
    TeamManager[Team Manager]
    Agents[Agent Clones / Avatars]
    Skills[Skills System]
    Tools[Tool Registry]
    
    User --> UI
    UI --> MetaAgent
    MetaAgent --> TeamManager
    TeamManager --> Agents
    Agents --> Skills
    Agents --> Tools

Core Components

Sources: desktop/src/components/AvatarCreateDialog.tsx

Agent Creation and Configuration

Avatar (Agent Clone) Structure

Each agent clone is configured with:

• Name/Identifier — unique agent name
• System Prompt — base instructions and persona
• Workspace — isolated working directory (optional)
• Model Configuration — provider and model selection
• Enabled Skills — list of skills this agent can use
• Active State — can be toggled on/off

// Avatar configuration interface (simplified)
interface AgentClone {
  id: string;
  name: string;
  prompt: string;
  workspace?: string;
  provider?: string;
  model?: string;
  enabledSkills: string[];
  enabled: boolean;
}

Sources: desktop/src/components/AvatarCreateDialog.tsx

Skills Configuration

Skills can be assigned to agents with fine-grained control:

// Skills UI state management
const [skillsEnabledDraft, setSkillsEnabledDraft] = useState<Record<string, boolean>>({});
const [preferredSkillSources, setPreferredSkillSources] = useState<Record<string, string>>({});

Sources: desktop/src/components/AvatarCreateDialog.tsx

Team Management

Team Structure

Agents are organized into teams with coordinated behavior:

    Meta[Meta-Agent] --> Coordinator[Coordinator Agent]
    Coordinator --> AgentA[Specialist Agent A]
    Coordinator --> AgentB[Specialist Agent B]
    Coordinator --> AgentC[Specialist Agent C]
    
    AgentA --> Tool1[Tool Access]
    AgentB --> Tool2[Tool Access]
    AgentC --> Tool3[Tool Access]
    
    Coordinator --> SharedContext[Shared Context]
    AgentA --> SharedContext
    AgentB --> SharedContext
    AgentC --> SharedContext

Collaboration Modes

The collaboration system supports multiple coordination patterns:

# Pattern registration in manager
pattern_classes = {
    CollaborationMode.CUSTOM_PATTERN: CustomPattern,
    # ... other modes
}

Sources: agenticx/collaboration/README.md

Task Automation

Task Configuration

Automated tasks can be assigned to agents with scheduling and execution parameters:

Task Execution States

    A[Scheduled] --> B{Running}
    B -->|Success| C[Completed]
    B -->|Error| D[Failed]
    D -->|Retry| B
    C --> E[Update Status]
    E --> F[Ready for Next]

Sources: desktop/src/components/automation/TaskList.tsx

Tool Registry and Permissions

Tool Management

Tools are registered centrally and can be:

Denied Tools

Specific tools can be explicitly denied for security:

{deniedTools.map((toolPat, idx) => (
  <input
    value={toolPat}
    placeholder="bash_exec"
    list="agx-studio-tool-names-datalist"
    disabled={busy}
  />
))}

Sources: desktop/src/components/SettingsPanel.tsx

Role-Based Access Control

Role Permissions for Agents

Agent operations are governed by role-based permissions:

Role Management UI

The admin console provides role management with scope matrix editing:

<Dialog open={editOpen} onOpenChange={setEditOpen}>
  <div>
    <Label>权限</Label>
    <ScopeMatrixEditor value={editScopes} onChange={setEditScopes} />
  </div>
</Dialog>

Sources: enterprise/apps/admin-console/src/app/iam/roles/page.tsx

Environment Dependencies

External Tool Installation

The system manages external executable dependencies:

• Global Installation — Tools installed once, shared across all agents
• Per-Team Installation — Team-specific tool configurations
• Manual Installation Mode — Flagged tools requiring user intervention
• Sidecar Services — Background services (e.g., WeChat integration)

const wechatStatus = await window.agenticxDesktop.wechatSidecarPort();
if (!running) {
  const startRes = await window.agenticxDesktop.wechatSidecarStart();
}

Sources: desktop/src/components/SettingsPanel.tsx

Workflow Summary

Creating and Managing Agents

1. Define Agent Persona — Set name, prompt, and model configuration
2. Assign Skills — Enable/disable skills from global pool or add custom paths
3. Configure Tools — Grant/revoke tool access, manage denied tools
4. Set Up Team — Group agents under a meta-agent or coordinator
5. Define Tasks — Create automated tasks with scheduling
6. Monitor Execution — Track runs, statuses, and errors
7. Adjust Permissions — Update role-based access as needed

Multi-Agent Coordination Flow

    Request[User Request] --> Meta[Meta-Agent]
    Meta --> Decompose[Decompose Task]
    Decompose --> Assign[Assign to Team Members]
    Assign --> ExecuteA[Agent A Execute]
    Assign --> ExecuteB[Agent B Execute]
    Assign --> ExecuteC[Agent C Execute]
    ExecuteA --> ResultsA[Results A]
    ExecuteB --> ResultsB[Results B]
    ExecuteC --> ResultsC[Results C]
    ResultsA --> Aggregate[Aggregate Results]
    ResultsB --> Aggregate
    ResultsC --> Aggregate
    Aggregate --> Response[Final Response]

Integration with Enterprise Features

Feature Modules

AgenticX uses a modular feature system:

import { featureName } from "@agenticx/feature-agents";

Sources: enterprise/features/agents/README.md

Admin Console Integration

The enterprise admin console provides:

• Audit Logging — Track all agent operations with chain validation
• Bulk Import — Batch create agents from CSV templates
• Role Management — Define and assign permission scopes
• Model Configuration — Manage available AI providers and models

description={`共 ${items.length} 条记录 · ${
  chainFull?.valid ? "全表链校验通过" : "全表链校验失败"
}`}

Sources: enterprise/apps/admin-console/src/app/audit/page.tsx

Summary

The Meta-Agent and Team Management system provides a comprehensive framework for orchestrating multiple AI agents within AgenticX. Key capabilities include:

• Hierarchical Agent Structure — Meta-agents coordinate specialist agents
• Flexible Skill System — Modular capabilities with per-agent enablement
• Team-Based Collaboration — Multiple coordination patterns (sequential, parallel, hierarchical)
• Automated Task Execution — Scheduled tasks with status tracking
• Tool Registry — Centralized tool management with permission controls
• Role-Based Security — Enterprise-grade IAM integration
• Environment Management — External dependency handling

The system is designed for both single-user desktop scenarios (via SettingsPanel) and enterprise deployments (via Admin Console), supporting use cases from personal automation to complex multi-agent workflows.

Related Pages

Related topics: Agent Core System

Tool System and MCP Hub

Overview

The AgenticX Tool System provides a comprehensive framework for extending agent capabilities through function tools, MCP (Model Context Protocol) integration, remote tools, OpenAPI-based tool sets, sandboxed execution, and built-in guardrails. This architecture enables agents to interact with external systems, execute code safely, and enforce security policies while maintaining a unified tool invocation interface.

Architecture Overview

The tool system is organized into a layered architecture where different tool implementations share common interfaces while providing specialized functionality:

graph TD
    A[Agent Core] --> B[Tool Registry]
    B --> C[Function Tool]
    B --> D[MCP Hub]
    B --> E[Remote Tools v2]
    B --> F[OpenAPI Toolset]
    B --> G[Sandbox Tools]
    B --> H[Guardrails]
    
    D --> I[MCP Servers]
    D --> J[MCP Client]
    
    G --> K[Sandbox Runtime]
    H --> L[Built-in Validators]

Function Tool

Function tools provide the foundational mechanism for wrapping Python functions as agent-callable tools. They encapsulate function metadata, parameter schemas, and execution logic within a standardized interface.

Core Implementation

Function tools are defined through decorators or class-based configurations that specify the tool's name, description, parameters, and return type. The system uses type hints to automatically generate JSON Schema for parameter validation.

from agenticx.tools.function_tool import FunctionTool

@FunctionTool.register(
    name="web_search",
    description="Search the web for information",
    parameters={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"},
            "limit": {"type": "integer", "description": "Max results", "default": 5}
        },
        "required": ["query"]
    }
)
def search_web(query: str, limit: int = 5) -> dict:
    # Implementation
    return {"results": []}

Tool Execution Flow

sequenceDiagram
    participant Agent
    participant Registry
    participant FunctionTool
    participant Executor
    
    Agent->>Registry: InvokeTool(name, parameters)
    Registry->>FunctionTool: Locate tool by name
    FunctionTool->>Executor: Execute(parameters)
    Executor->>FunctionTool: Result
    FunctionTool->>Registry: Wrapped response
    Registry->>Agent: ToolResult

Sources: agenticx/tools/function_tool.py

MCP Hub

The MCP Hub serves as the central integration point for Model Context Protocol servers, enabling agents to discover and utilize tools exposed by external MCP-compliant services.

MCP Architecture

graph LR
    A[AgenticX Agent] --> B[MCP Hub]
    B --> C[MCP Client Pool]
    C --> D[MCP Server 1]
    C --> E[MCP Server 2]
    C --> F[MCP Server N]
    
    D --> G[File System Tools]
    E --> H[API Tools]
    F --> I[Custom Tools]

MCP Hub Features

The MCP Hub provides the following capabilities:

Sources: agenticx/tools/mcp_hub.py

Usage Pattern

from agenticx.tools.mcp_hub import MCPHub

hub = MCPHub()

# Connect to an MCP server
await hub.connect("file-server", server_config)

# List available tools
tools = await hub.list_tools()

# Invoke a tool
result = await hub.invoke("file-server", "read_file", {"path": "/data/file.txt"})

Remote Tools v2

The remote tools module provides a robust mechanism for calling external APIs and services. Version 2 introduces improved connection handling, request pooling, and authentication support.

Architecture

graph TD
    A[Tool Request] --> B[RemoteTool Client]
    B --> C[Request Queue]
    C --> D[Connection Pool]
    D --> E[External API]
    E --> D
    D --> F[Response Handler]
    F --> G[Tool Result]
    
    B --> H[Auth Manager]
    H --> I[Token Store]

Configuration Options

Sources: agenticx/tools/remote_v2.py

Implementation

from agenticx.tools.remote_v2 import RemoteTool

tool = RemoteTool(
    name="external_api",
    base_url="https://api.example.com",
    auth_type="bearer",
    token="your-token",
    timeout=60,
    max_retries=3
)

result = await tool.invoke("endpoint", {"param": "value"})

OpenAPI Toolset

The OpenAPI toolset enables automatic generation of tool interfaces from OpenAPI specifications. This allows agents to interact with any REST API documented using the OpenAPI standard.

Auto-Discovery Process

graph TD
    A[OpenAPI Spec] --> B[OpenAPI Parser]
    B --> C[Endpoint Mappings]
    C --> D[Tool Generator]
    D --> E[Tool Instances]
    E --> F[Tool Registry]

Supported Features

Sources: agenticx/tools/openapi_toolset.py

Usage Example

from agenticx.tools.openapi_toolset import OpenAPIToolset

# Generate tools from OpenAPI spec
toolset = OpenAPIToolset.from_spec(
    spec_url="https://api.example.com/openapi.json",
    auth={"type": "bearer", "token": "..."}
)

# Tools are automatically registered
results = await toolset.invoke("get_user", {"id": "123"})

Sandbox Tools

Sandbox tools provide secure code execution environments for agent operations that require running untrusted or dynamically generated code.

Sandbox Architecture

graph TD
    A[Code Execution Request] --> B[Sandbox Manager]
    B --> C{Backend Type}
    C -->|micro-sandbox| D[Lightweight Container]
    C -->|docker| E[Docker Container]
    C -->|remote| F[Remote Sandbox Service]
    
    D --> G[Execution Engine]
    E --> G
    F --> G
    
    G --> H[Result Collector]
    H --> I[Output/Side Effects]
    H --> J[Error Handler]

Sandbox Templates

Error Handling

The sandbox module defines specific exception types for different failure scenarios:

from agenticx.tools.sandbox_tools import (
    SandboxError,
    SandboxTimeoutError,
    SandboxExecutionError,
    SandboxNotReadyError,
    SandboxBackendError,
)

try:
    async with Sandbox.create() as sb:
        result = await sb.execute(code, timeout=60)
except SandboxTimeoutError:
    print("Execution exceeded time limit")
except SandboxExecutionError as e:
    print(f"Runtime error: {e.stderr}")
except SandboxBackendError as e:
    print(f"Backend failure: {e.backend}")

Sources: agenticx/tools/sandbox_tools.py

Guardrails (Built-in)

Guardrails provide security and policy enforcement for tool execution, ensuring that agent operations comply with defined constraints and safety policies.

Guardrail Architecture

graph LR
    A[Tool Request] --> B[Guardrail Chain]
    B --> C[Input Validator]
    B --> D[Rate Limiter]
    B --> E[Content Filter]
    B --> F[Output Sanitizer]
    
    C --> G{Allowed?}
    D --> G
    E --> G
    F --> G
    
    G -->|Yes| H[Tool Executor]
    G -->|No| I[Rejection Response]

Built-in Guardrail Types

Sources: agenticx/tools/guardrails/builtin.py

Implementation Pattern

from agenticx.tools.guardrails.builtin import (
    InputValidationGuardrail,
    RateLimitGuardrail,
)

# Configure guardrails
guardrails = [
    InputValidationGuardrail(schema=param_schema),
    RateLimitGuardrail(max_calls=100, window_seconds=60),
]

# Apply to tool
secure_tool = Tool.with_guardrails(tool_instance, guardrails)

Integration with Agentic Agents

Tools integrate seamlessly with the AgenticX agent framework through the tool registry and invocation system.

graph TD
    A[Agent Task] --> B[Planner]
    B --> C[Tool Selection]
    C --> D[Tool Registry]
    D --> E[Tool Invocation]
    E --> F{Guardrail Check}
    F -->|Pass| G[Execute Tool]
    F -->|Fail| H[Reject]
    G --> I[Result Processing]
    I --> J[Response to Agent]

Tool Selection Criteria

Summary

The AgenticX Tool System provides a flexible, extensible framework for extending agent capabilities through multiple integration patterns:

• Function Tools: Direct Python function wrapping
• MCP Hub: Model Context Protocol integration for external tool servers
• Remote Tools v2: External API invocation with connection pooling
• OpenAPI Toolset: Automatic tool generation from API specifications
• Sandbox Tools: Secure code execution environments
• Guardrails: Security and policy enforcement layers

This architecture enables developers to extend agent capabilities while maintaining consistent interfaces, security boundaries, and operational monitoring across all tool integrations.

The Memory System in AgenticX provides persistent and intelligent memory capabilities for AI agents, enabling them to retain information across sessions, manage knowledge bases, and perform semantic searches. This system is fundamental for building stateful, context-aware agentic applications.

Architecture Overview

The memory system follows a layered architecture that separates storage backends from intelligent processing components.

┌─────────────────────────────────────────────────────────┐
│                    AgenticX Memory System                 │
├─────────────────────────────────────────────────────────┤
│  ┌───────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │ MemoryComponent│  │ KnowledgeBase│  │   MemoryClient│ │
│  │  (Intelligence) │  │ (Organization)│  │  (API Layer)  │ │
│  └───────┬───────┘  └──────┬───────┘  └───────┬───────┘ │
│          │                 │                   │         │
│  ┌───────┴─────────────────┴───────────────────┴───────┐ │
│  │              Memory Backend Implementations          │ │
│  ├─────────────┬───────────────┬───────────────────────┤ │
│  │ShortTermMemory│ EpisodicMemory│ SemanticMemory      │ │
│  ├─────────────┼───────────────┼───────────────────────┤ │
│  │ Hierarchical │  Mem0Memory   │  MCP Integration     │ │
│  └─────────────┴───────────────┴───────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Sources: agenticx/memory/README.md

Core Components

1. ShortTermMemory

Short-term memory provides transient storage for current conversation context and immediate agent state. It is designed for high-throughput operations within a tenant's scope.

from agenticx.memory import ShortTermMemory

# Create memory backend
backend = ShortTermMemory(tenant_id="user_123")

# Add persistent memory with metadata
memory_id = await backend.add(
    "Important project information",
    metadata={"project": "agenticx", "importance": "high"}
)

# Search across all memories
results = await backend.search("project information")

Sources: agenticx/memory/README.md

2. KnowledgeBase

KnowledgeBase enables organization of content into specialized domains with content-type filtering.

from agenticx.memory import KnowledgeBase, ShortTermMemory

# Create memory backend
backend = ShortTermMemory(tenant_id="kb_demo")

# Create specialized knowledge bases
docs_kb = KnowledgeBase(
    name="documentation",
    memory_backend=backend,
    allowed_content_types={"tutorial", "guide", "faq"}
)

code_kb = KnowledgeBase(
    name="code_examples", 
    memory_backend=backend,
    allowed_content_types={"code", "snippet"}
)

# Add content with content type
await docs_kb.add(
    "How to create an agent",
    content_type="tutorial",
    metadata={"difficulty": "beginner"}
)

# Search within specific knowledge base
doc_results = await docs_kb.search("agent creation")

Sources: agenticx/memory/README.md

3. MemoryComponent

The MemoryComponent provides intelligent memory operations with automatic cleanup and advanced retrieval capabilities.

from agenticx.memory import MemoryComponent, ShortTermMemory

# Create memory component with primary storage
primary_memory = ShortTermMemory(tenant_id="demo")
component = MemoryComponent(
    primary_memory=primary_memory,
    enable_ranking=True,
    enable_deduplication=True
)

# Use with context manager for automatic cleanup
async with component as mem:
    memory_id = await mem.add(
        "Context-aware information",
        metadata={"context": "agent_session"}
    )

Sources: agenticx/memory/README.md

Memory Backend Types

MCP Integration

The Memory System supports Model Context Protocol (MCP) for external memory service integration.

from agenticx.memory import MemoryClient
from agenticx.mcp import MCPServer, MCPTools

# Configure MCP server for memory
mcp_config = MCPTools(
    port=3000,
    server_config={
        "memory_service": "mem0",
        "api_endpoint": "http://localhost:8000"
    }
)

# Create memory client with MCP backend
memory = MemoryClient(
    tenant_id="mcp_tenant",
    server_config=mcp_config
)

# Async usage with automatic resource management
async with memory:
    memory_id = await memory.add(
        "Important project information",
        metadata={"project": "agenticx", "importance": "high"}
    )
    results = await memory.search("project information")

Sources: agenticx/memory/README.md

Healthcare Memory Scenario

The Mem0 memory backend is specifically designed for healthcare applications, providing medical knowledge memory and personalized patient information management.

# Run healthcare memory example
python examples/mem0_healthcare_example.py

Sources: README.md

Key Features for Healthcare

• Medical Knowledge Memory: Structured storage for medical concepts, diagnoses, and treatment protocols
• Patient Information Management: Secure, tenant-isolated storage for patient-specific data
• Privacy Compliance: Built-in data handling safeguards for sensitive medical information
• Semantic Search: Fast retrieval of relevant medical information using embeddings

Desktop Application Integration

The Memory System is accessible through the AgenticX Desktop application, providing a graphical interface for memory management.

// SettingsPanel.tsx integration
import { useAgenticxDesktop } from "@agenticx/desktop";

const memorySettings = {
  enableMemorySync: true,
  syncInterval: 30000, // ms
  maxMemorySize: "100MB"
};

Sources: desktop/src/components/SettingsPanel.tsx

Skill Scanning with Memory

The desktop application uses memory-backed skill scanning to discover and manage agent capabilities:

• Global Skills: System-wide shared skills stored in memory
• Project Skills: Per-project skills located in .agents/skills/
• Marketplace Skills: Third-party skills fetched and cached
• Custom Paths: User-defined skill directories

Sources: desktop/src/components/SettingsPanel.tsx

Intent Recognition with Memory

The intent recognition service leverages the Memory System for storing and retrieving classification patterns and entity mappings.

# Run intent recognition example
python examples/agenticx-for-intent-recognition/main.py

Sources: examples/agenticx-for-intent-recognition/README.md

Architecture Pattern

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Intent Agent   │────▶│  Memory System   │◀────│  Knowledge Base │
│   (Classifier)  │     │  (Storage/Lookup)│     │   (Patterns)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                      │
         ▼                      ▼
┌─────────────────┐     ┌──────────────────┐
│  Workflow Engine│     │  Semantic Search │
│ (Orchestration) │     │   (Retrieval)    │
└─────────────────┘     └──────────────────┘

Memory Operations API

Add Memory

memory_id = await memory.add(
    content: str,
    metadata: Optional[dict] = None,
    content_type: Optional[str] = None,
    embedding: Optional[list[float]] = None
) -> str

Search Memory

results = await memory.search(
    query: str,
    limit: int = 10,
    content_type: Optional[str] = None,
    filters: Optional[dict] = None
) -> list[MemoryResult]

Delete Memory

await memory.delete(memory_id: str) -> bool

Update Memory

await memory.update(
    memory_id: str,
    content: Optional[str] = None,
    metadata: Optional[dict] = None
) -> bool

Best Practices

Tenant Isolation

Always specify a unique tenant_id when creating memory backends to ensure data isolation:

# Good: Isolated memory per tenant
user_memory = ShortTermMemory(tenant_id="user_abc123")

# Avoid: Shared memory across tenants
shared_memory = ShortTermMemory(tenant_id="shared")  # Not recommended

Content Type Organization

Use content types consistently for better organization and filtering:

Metadata Usage

Leverage metadata for enhanced search and filtering:

await memory.add(
    "Agent configuration guide",
    metadata={
        "category": "documentation",
        "difficulty": "intermediate",
        "version": "1.0",
        "tags": ["agent", "setup", "configuration"]
    }
)

Dependencies

The Memory System requires the following core dependencies:

Summary

The AgenticX Memory System provides a comprehensive, multi-layered approach to agent memory management:

1. ShortTermMemory for immediate session context
2. KnowledgeBase for domain-specific content organization
3. MemoryComponent for intelligent operations
4. MCP Integration for external memory services
5. Specialized Backends (Mem0) for domain-specific applications

This architecture enables agents to maintain persistent context, perform semantic retrieval, and scale across enterprise deployments with full tenant isolation.

Overview

The Avatar and Group Chat system in AgenticX enables multi-agent collaboration through configurable digital personas called "Avatars" (also referred to as "分身" in Chinese). Each Avatar represents an autonomous agent with a distinct role, system prompts, and behavioral preferences that can interact with users and other agents in group conversations.

The system architecture consists of:

• Avatar Registry: Manages the lifecycle of all avatars, including creation, persistence, and configuration storage
• Avatar Settings: UI layer for configuring avatar properties including name, role, appearance (avatar image), and skill associations
• Group Chat: Enables multiple avatars to participate in collaborative conversations, facilitating multi-agent workflows
• Group Context & Routing: Handles message routing between avatars in group conversations and maintains conversational context

Sources: desktop/src/components/AvatarSettingsPanel.tsx, enterprise/features/agents/README.md, agenticx/collaboration/README.md

Avatar System Architecture

Avatar Configuration Model

Each Avatar is defined by a configuration that includes:

Sources: desktop/src/components/AvatarSettingsPanel.tsx, desktop/src/components/SettingsPanel.tsx

Avatar Persistence

Avatars are persisted to disk in YAML format within each avatar's dedicated directory:

~/.agenticx/
└── <avatar_id>/
    └── avatar.yaml

The UI indicates this clearly: "保存后写入该分身目录下的 avatar.yaml" (Saved to the avatar.yaml file under the avatar directory after saving).

Sources: desktop/src/components/AvatarSettingsPanel.tsx

Avatar Settings Panel

The AvatarSettingsPanel component provides the primary interface for managing avatar configurations.

UI Components

┌─────────────────────────────────────────────┐
│ Avatar Settings Panel                       │
├─────────────────────────────────────────────┤
│ [Avatar Image Preview]     [Upload] [Clear] │
│   • Consistent with sidebar and chat list   │
│   • Recommended: < 1.8MB square image       │
├─────────────────────────────────────────────┤
│ 名称: [________________]                    │
│ 角色: [________________]                    │
│      例：全栈开发工程师、数据分析师          │
└─────────────────────────────────────────────┘

Key Features

1. Avatar Image Management

• Preview support for uploaded images
• Clear button to reset to default avatar
• Image size validation (recommended < 1.8MB)
• Visual consistency across sidebar, chat list, and sessions

1. Metadata Configuration

• name: Avatar display name
• role: Professional role descriptor

Sources: desktop/src/components/AvatarSettingsPanel.tsx

Avatar Creation Dialog

The AvatarCreateDialog component handles the initial creation of new avatars with skill selection.

Skill Assignment Workflow

graph TD
    A[Create New Avatar] --> B[Load Available Skills]
    B --> C{Global Skills Disabled?}
    C -->|Yes| D[Filter Out Disabled Skills]
    C -->|No| E[Show All Skills]
    D --> F[Display Skill List]
    E --> F
    F --> G[User Toggles Skills On/Off]
    G --> H[Save Avatar with Skills]

Skill Selection States

// Skill toggle button styling from AvatarCreateDialog.tsx
disabled
  ? "border-border-strong text-text-muted"
  : "border-cyan-500/40 bg-cyan-500/10 text-cyan-400"

Sources: desktop/src/components/AvatarCreateDialog.tsx, desktop/src/components/AvatarSettingsPanel.tsx

User Preferences and Style Injection

The Avatar system supports injecting user preferences into the system prompt of all agents. This feature is managed through the Settings Panel.

User Preference Configuration

Example usage:

我不喜欢绕弯子，请直接给结论；
偏好表格而非长段落；
遇到歧义先问我再执行。

This preference text is:

• Injected into every conversation's system prompt
• Applied to all agent responses
• Stored in local browser storage for local-only effects

Sources: desktop/src/components/SettingsPanel.tsx

Group Chat System

Overview

Group Chat enables multiple avatars to participate in collaborative conversations. This is particularly useful for complex tasks requiring diverse expertise.

Multi-Agent Collaboration Patterns

Based on the collaboration documentation, AgenticX supports multiple collaboration modes for group interactions:

Sources: agenticx/collaboration/README.md

Context Management

The Group Context system maintains conversational state across multiple participants:

• Message History: Tracks all messages from all participants
• Participant State: Maintains individual avatar states
• Turn Management: Controls speaking order and发言权

Message Routing

The Group Router determines how messages are routed between avatars:

graph LR
    A[User Message] --> B[Group Router]
    B --> C{Which Avatar?}
    C -->|Expert A| D[Process & Generate]
    C -->|Expert B| E[Process & Generate]
    C -->|Meta-Agent| F[Orchestrate Response]
    D --> G[Group Context Update]
    E --> G
    F --> G
    G --> H[Response to User]

Sources: enterprise/features/chat/README.md

Task Automation with Avatars

Avatars can be associated with automated tasks for scheduled or triggered execution.

Task Configuration

Each automated task can specify:

Task List UI

The Task List component displays:

• Task name and description
• Execution model (provider/model)
• Enable/disable toggle
• Last execution status with timestamps
• Error details for failed runs

Sources: desktop/src/components/automation/TaskList.tsx

Integration Points

WeChat Integration

Avatars can be bound to WeChat for receiving messages and triggering agent execution:

• Binding Method: QR code scanning via WeChat iLink protocol
• Status Indicators: Connected (green), Bound but not connected (yellow)
• Sidecar Port: Local service for WeChat communication

Sources: desktop/src/components/SettingsPanel.tsx

Meta-Agent (Machi)

The Meta-Agent system provides orchestration capabilities:

• Central coordination of multiple avatars
• Meta-agent SOUL saving and loading
• Unified interface for managing complex multi-agent workflows

Sources: desktop/src/components/SettingsPanel.tsx

Configuration Schema

Avatar YAML Structure

# avatar.yaml
name: "Avatar Display Name"
role: "Professional Role"
avatarUrl: "/path/to/image.png"
skills:
  - skill_name_1
  - skill_name_2
userPreference: "Behavioral preferences..."

Permission Modes

Sources: desktop/src/components/SettingsPanel.tsx

Summary

The Avatar and Group Chat system provides a comprehensive framework for:

1. Avatar Management: Create, configure, and persist digital personas with distinct roles and skills
2. Skill Association: Enable/disable skills per avatar with visual UI feedback
3. User Preference Injection: Customize agent behavior across all conversations
4. Group Collaboration: Enable multiple avatars to work together on complex tasks
5. Task Automation: Associate avatars with automated tasks for scheduled execution
6. Multi-Channel Integration: Connect avatars to external platforms like WeChat

The system is designed for flexibility, allowing fine-grained control over avatar behavior while supporting sophisticated multi-agent collaboration patterns.

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Desktop app fails on startup: agx serve failed to start (local API not available)

• Severity: high
• Finding: Installation risk is backed by a source signal: Desktop app fails on startup: agx serve failed to start (local API not available). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/issues/2

2. Installation risk: AgenticX + Machi v0.3.7

• Severity: medium
• Finding: Installation risk is backed by a source signal: AgenticX + Machi v0.3.7. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7

3. Installation risk: MCP will report an error upon startup: "[Errno 2] No such file or directory".

• Severity: medium
• Finding: Installation risk is backed by a source signal: MCP will report an error upon startup: "[Errno 2] No such file or directory".. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/issues/14

4. Installation risk: Machi launch failure on mac

• Severity: medium
• Finding: Installation risk is backed by a source signal: Machi launch failure on mac. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/issues/13

5. Installation risk: UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion

• Severity: medium
• Finding: Installation risk is backed by a source signal: UX: Cannot queue follow-up messages while bash_exec (or tool) is running; UI blocks until stop or completion. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/issues/8

6. Installation risk: Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)

• Severity: medium
• Finding: Installation risk is backed by a source signal: Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/issues/10

7. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.

8. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing

9. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium

10. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium

11. Security or permission risk: AgenticX v0.3.5

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: AgenticX v0.3.5. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5

12. Security or permission risk: AgenticX v0.3.6

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: AgenticX v0.3.6. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using AgenticX with real data or production workflows.

• Desktop app fails on startup: agx serve failed to start (local API not a - github / github_issue
• [MCP will report an error upon startup: "[Errno 2] No such file or direct](https://github.com/DemonDamon/AgenticX/issues/14) - github / github_issue
• Machi launch failure on mac - github / github_issue
• Windows: Document ingestion fails for PDF files (missing PDF reader libs - github / github_issue
• UX: Cannot queue follow-up messages while bash_exec (or tool) is runni - github / github_issue
• bash_exec fails to run any command on Windows (WinError 2) - github / github_issue
• Community source 7 - github / github_issue
• AgenticX v0.3.8 - github / github_release
• AgenticX + Machi v0.3.7 - github / github_release
• AgenticX v0.3.6 - github / github_release
• AgenticX v0.3.5 - github / github_release
• README/documentation is current enough for a first validation pass. - GitHub / issue