# https://github.com/DemonDamon/AgenticX 项目说明书
生成时间：2026-05-15 23:21:36 UTC
## 目录
- [Introduction to AgenticX](#page-introduction)
- [Quick Start Guide](#page-quickstart)
- [Installation Guide](#page-installation)
- [System Architecture](#page-architecture)
- [Core Abstractions](#page-core-abstractions)
- [Agent Core System](#page-agent-core)
- [Meta-Agent and Team Management](#page-meta-agent)
- [Tool System and MCP Hub](#page-tool-system)
- [Memory System](#page-memory-system)
- [Avatar and Group Chat](#page-avatar-system)
## Introduction to AgenticX
### 相关页面
相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)
- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/departments/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)
- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)
- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)
# 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).
资料来源：[enterprise/features/agents/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
## Platform Architecture
AgenticX consists of three primary deployment surfaces:
| Platform | Purpose | Key Components |
|----------|---------|----------------|
| **Enterprise Admin Console** | Centralized administration for organizations | User Management, Role Management, Department Hierarchy, Audit Logs, Model Configuration |
| **Enterprise Web Portal** | User-facing authentication and portal access | OAuth/Auth integration, Apache 2.0 licensed, ISO27001 & SOC2 compliant |
| **Desktop Application** | Local agent execution and management | Task Automation, Settings Panel, Skill Management, WeChat Integration |
资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)
资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)
资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
### Architecture Diagram
```mermaid
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.
资料来源：[enterprise/features/agents/README.md:5](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
### 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.
资料来源：[enterprise/features/knowledge-base/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)
### 3. Task Automation System
The desktop application supports automated task execution with configurable prompts, workspace assignments, and model selection.
| Property | Description |
|----------|-------------|
| `task.enabled` | Boolean flag to enable/disable automation |
| `task.prompt` | Custom prompt instructions for the agent |
| `task.workspace` | Designated workspace path for task execution |
| `task.provider` | AI provider identifier (e.g., openai, volcengine) |
| `task.model` | Specific model to use for execution |
| `task.lastRunAt` | Timestamp of last execution |
| `task.lastRunStatus` | Execution result: `success` or `error` |
资料来源：[desktop/src/components/automation/TaskList.tsx:10](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
### 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
资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
## 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
资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)
### Role Management
Role-based access control with scope matrix editor for granular permission configuration:
```mermaid
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]
```
| Role Operation | Description |
|----------------|-------------|
| Create Role | Define new role with code, name, and scope matrix |
| Edit Role | Modify existing role properties and permissions |
| Duplicate Role | Copy existing role configuration |
| Manage Members | View and manage users assigned to specific roles |
| Role Removal | PATCH update member's role codes when removed |
资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
### 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
资料来源：[enterprise/apps/admin-console/src/app/iam/departments/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/departments/page.tsx)
### 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
资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)
## 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
| Verification Status | Badge Color | Description |
|--------------------|-------------|-------------|
| Chain Complete | Success (Green) | Full table chain validation passed |
| Chain Failed | Destructive (Red) | Validation failed with reason |
| Loading | Warning (Yellow) | Validation in progress |
资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)
### Security Compliance
The enterprise portal demonstrates commitment to security standards:
- Apache 2.0 License
- ISO27001 Certification
- SOC2 Compliance
资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)
## 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
| Field | Description | Example |
|-------|-------------|---------|
| Model ID | Provider-specific model identifier | `gpt-4o-mini`, `qwen-plus` |
| Display Name | Human-readable label | "GPT-4o Mini (Fast)" |
| Provider | Parent provider configuration | volcengine, openai |
资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx)
## External Integrations
### AgentKit Integration
AgenticX supports integration with LangChain's AgentKit framework for Volcano Engine deployment:
```bash
# Deployment workflow
agx volcengine deploy --region --app-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
资料来源：[examples/agenticx-for-agentkit/README.md:1](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
### 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
资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
## Skill Management
Skills extend agent capabilities through modular configurations:
| Skill Source | Location | Description |
|--------------|----------|-------------|
| Global Skills | System-wide | Shared across all agent instances |
| Project Skills | `.agents/skills/` | Project-specific skill definitions |
| Third-party Skills | Custom scan paths | External skill repositories |
| SKILL.md | Configuration files | Standard skill definition format |
| Installation State | Badge | Description |
|-------------------|-------|-------------|
| Installed | Emerald | Green badge, globally available |
| Installing | Muted | In progress, non-blocking |
| Manual Required | Warning | User action needed |
| Not Installed | Default | Available for installation |
资料来源：[desktop/src/components/SettingsPanel.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
资料来源：[desktop/src/components/automation/TaskList.tsx:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
## State Management
The desktop application uses a centralized store architecture:
```mermaid
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
资料来源：[desktop/src/store.ts:1](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
---
## Quick Start Guide
### 相关页面
相关主题：[Installation Guide](#page-installation), [Agent Core System](#page-agent-core)
相关源码文件
以下源码文件用于生成本页说明：
- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)
- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md)
- [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)
# 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:
| Requirement | Version/Details |
|-------------|-----------------|
| Python | 3.10+ |
| Package Manager | pip or uv |
| API Keys | Provider-specific (OpenAI, Azure, etc.) |
| Network | Access to model provider endpoints |
资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
## Installation
### Core Package
Install the AgenticX core package using pip:
```bash
pip install agenticx
```
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
### Example Dependencies
For specific integrations, install example-specific requirements:
```bash
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
```
资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
## Configuration
### Step 1: Create Configuration File
Copy the `config.yaml` template and configure your API keys:
```yaml
# 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
资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
## Building Your First Agent
### Basic Agent Creation
Create a simple agent using the AgenticX core API:
```python
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:
```python
from agenticx.collaboration import CollaborationMode, CustomPattern
pattern_classes = {
CollaborationMode.CUSTOM_PATTERN: CustomPattern,
}
```
资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
## Collaboration Patterns
AgenticX provides built-in collaboration modes for multi-agent scenarios:
```mermaid
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
| Pattern | Use Case | Complexity |
|---------|----------|------------|
| Sequential | Ordered task execution | Low |
| Parallel | Concurrent independent tasks | Medium |
| Hierarchical | Manager-subordinate coordination | High |
| Custom | Domain-specific collaboration logic | Variable |
资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
## Enterprise Features
The enterprise edition extends AgenticX with additional capabilities:
### Available Feature Modules
| Module | Package | Purpose |
|--------|---------|---------|
| Agents | `@agenticx/feature-agents` | Avatar management and configuration |
| Knowledge Base | `@agenticx/feature-knowledge-base` | Document indexing and retrieval |
| Identity & Access | `@agenticx/feature-iam` | Tenant, department, role, and permission management |
| MCP Tools | `@agenticx/feature-tools-mcp` | MCP protocol integration for tool access |
资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md), [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md), [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md), [enterprise/features/tools-mcp/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/tools-mcp/README.md)
### Feature Module Usage
```tsx
import { featureName } from "@agenticx/feature-agents";
```
## CLI Commands
AgenticX provides a command-line interface for common operations:
| Command | Description |
|---------|-------------|
| `agx init` | Initialize a new project |
| `agx serve` | Start the AgenticX server |
| `agx deploy` | Deploy to cloud providers |
| `agx logs [--follow]` | View engine logs |
| `agx destroy` | Clean up deployed resources |
### Deployment Example (Volcengine)
```bash
agx volcengine deploy # Deploy to Volcengine
agx logs --follow # Monitor deployment
agx volcengine destroy # Clean up resources
```
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
## Running the Project
Execute your AgenticX application:
```bash
python main.py
```
资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
## Testing
### Running Tests
Execute the test suite to validate your implementation:
```bash
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:
```dockerfile
# Refer to examples/agenticx-for-agentkit/hi-agent/Dockerfile
```
### Cloud Deployment
1. Configure cloud provider credentials
2. Run deployment command:
```bash
agx volcengine deploy
```
3. Monitor logs:
```bash
agx logs --follow
```
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
## Next Steps
| Resource | Description |
|----------|-------------|
| [Project Homepage](https://github.com/DemonDamon/AgenticX) | Main repository and documentation |
| [Collaboration Patterns Paper](https://arxiv.org/abs/2501.06322) | Academic paper on multi-agent collaboration |
| [Volcengine Integration](../agenticx/integrations/agentkit/) | Cloud-specific integration source |
| [Project Templates](../agenticx/cli/templates/volcengine/) | Deployment configuration templates |
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Import errors | Ensure `agenticx` is installed: `pip install agenticx` |
| API key errors | Verify credentials in `config.yaml` |
| Timeout errors | Increase timeout values in configuration |
| Deployment failures | Check cloud provider credentials and quotas |
### Getting Help
For additional support:
- Open an issue on [GitHub](https://github.com/DemonDamon/AgenticX/issues)
- Consult the project documentation
- Review the collaboration patterns academic paper
---
## Installation Guide
### 相关页面
相关主题：[Quick Start Guide](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)
- [pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)
- [desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)
- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
# 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
```graph TD
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
| Component | Minimum Version | Recommended |
|-----------|-----------------|-------------|
| Python | 3.11+ | 3.12+ |
| Node.js | 18.0+ | 20.x LTS |
| npm/yarn | 9.0+ | Latest stable |
| Git | 2.30+ | Latest |
### External Dependencies
The desktop application requires several external executable dependencies that can be installed globally once and shared across all instances.
```graph TD
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]
```
资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml)
## Python Package Installation
### Project Structure
The Python backend uses Poetry for dependency management with the following key packages:
| Package | Purpose | Version Constraint |
|---------|---------|---------------------|
| adalflow | Core AI framework | ^0.3.0 |
| agenticx-core | Main agent engine | Internal |
| pydantic | Data validation | ^2.0 |
| fastapi | API framework | ^0.100.0 |
| uvicorn | ASGI server | ^0.23.0 |
### Installation Commands
```bash
# 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 .
```
资料来源：[INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)
### Environment Variables
The application requires specific environment variables for configuration:
| Variable | Description | Required |
|----------|-------------|----------|
| `AGX_API_BASE` | Backend API endpoint | Yes |
| `AGX_API_TOKEN` | Authentication token | Yes |
| `OPENAI_API_KEY` | LLM provider key | Conditional |
| `ANTHROPIC_API_KEY` | Claude API key | Conditional |
## Enterprise Applications
### Admin Console Setup
The enterprise admin console is a Next.js application located in `enterprise/apps/admin-console/`.
```mermaid
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]
```
资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
### Installation Steps
```bash
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.
资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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:
```graph TD
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]
```
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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:
```typescript
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;
}
```
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
#### Skills Management
The desktop application includes a skills management system that scans multiple locations:
| Location | Description | Priority |
|----------|-------------|----------|
| `.agents/skills/` | Project-local skills | High |
| Global skills | System-wide shared skills | Medium |
| Third-party scan | External skill directories | Configurable |
| Custom paths | User-defined locations | Manual |
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
### Desktop IPC API
The desktop client exposes a comprehensive IPC API for configuration and skill management:
```typescript
interface AgenticXDesktopAPI {
getSkillSettings(): Promise;
putSkillSettings(payload: SkillSettingsPayload): Promise;
refreshSkills(): Promise;
installBundle(args: BundleInstallArgs): Promise;
uninstallBundle(args: { name: string }): Promise;
installFromRegistry(args: RegistryInstallArgs): Promise;
searchRegistry(args: { q: string }): Promise;
}
```
资料来源：[desktop/src/global.d.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/global.d.ts)
## Advanced Configuration
### Token Dashboard
The desktop client includes a token usage dashboard with configurable date ranges:
```typescript
type TokenDashboardRange = '7d' | '30d' | '90d' | 'custom';
interface TokenDashboardState {
range: TokenDashboardRange;
customFrom?: string;
customTo?: string;
}
```
资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
### Model Provider Configuration
Support for multiple LLM providers with per-provider configuration:
| Provider | Config Key | Required Field |
|----------|------------|----------------|
| OpenAI | `provider` | `apiKey` |
| Anthropic | `provider` | `apiKey` |
| Custom | `provider` | `apiBase` + `apiKey` |
### Theme and UI Settings
| Setting | Type | Options |
|---------|------|---------|
| Theme Mode | `ThemeMode` | `light`, `dark`, `system` |
| Theme Color | `ThemeColor` | Various accent colors |
| Chat Style | `ChatStyle` | `pro`, `lite` |
## 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
| Issue | Solution |
|-------|----------|
| API connection failed | Verify `AGX_API_BASE` environment variable |
| Skills not loading | Check SKILL.md placement in `.agents/skills/` |
| Bundle install blocked | Acknowledge high-risk warning if appropriate |
## 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
```
资料来源：[pyproject.toml](https://github.com/DemonDamon/AgenticX/blob/main/pyproject.toml), [INSTALL.md](https://github.com/DemonDamon/AgenticX/blob/main/INSTALL.md)
---
## System Architecture
### 相关页面
相关主题：[Core Abstractions](#page-core-abstractions), [Agent Core System](#page-agent-core)
相关源码文件
以下源码文件用于生成本页说明：
- [enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx)
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
- [desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
- [enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
- [enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx)
- [enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)
- [enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)
- [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
# 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.
资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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
```mermaid
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.
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
#### Agent Core
The Agent Core handles fundamental agent operations:
| Component | Function |
|-----------|----------|
| Tool Registry | Discovers and manages available tools |
| Execution Engine | Processes agent tasks and tool invocations |
| State Management | Maintains agent conversation state |
#### Workflow Engine
The workflow engine orchestrates multi-step agent tasks with support for both synchronous and asynchronous execution patterns.
资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/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
资料来源：[enterprise/apps/admin-console/src/app/iam/users/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/users/page.tsx)
```mermaid
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
资料来源：[enterprise/apps/web-portal/src/app/auth/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/app/auth/page.tsx)
#### Identity and Access Management (IAM)
The IAM system manages authentication and authorization across the platform:
| Feature | Description |
|---------|-------------|
| User Management | Full CRUD operations with email/display name tracking |
| Role-Based Access Control | Roles with scoped permission matrices |
| Bulk Import | CSV-based batch operations with pre-check validation |
| Department Hierarchy | Organizational structure support via `dept_path` |
资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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:
| Component | Purpose |
|-----------|---------|
| SettingsPanel | Configure providers, models, environment tools |
| TaskList | Manage automated tasks with enable/disable controls |
| ChatPane | Agent conversation interface |
| Store | Centralized state management using Zustand |
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
```mermaid
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:
| State Category | Key Properties |
|----------------|----------------|
| Session | `sessionId`, `userMode`, `theme` |
| Chat | `messages`, `modelProvider`, `modelName` |
| Settings | `providers`, `apiKey`, `defaultProvider` |
| UI | `sidebarCollapsed`, `focusMode`, `commandPaletteOpen` |
| Tasks | `tasks`, `activeTaskspaceId` |
资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts)
#### Task Automation
Tasks support the following configuration options:
| Property | Type | Description |
|----------|------|-------------|
| `enabled` | boolean | Toggle task execution |
| `prompt` | string | Task instruction prompt |
| `workspace` | string | Working directory path |
| `provider` | string | AI provider identifier |
| `model` | string | Model name |
| `lastRunAt` | timestamp | Last execution time |
| `lastRunStatus` | enum | `success`, `error` |
| `lastRunError` | string | Error message if failed |
资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
### Feature Modules
Enterprise features are implemented as standalone modules under `enterprise/features/`:
| Module | Description |
|--------|-------------|
| `@agenticx/feature-agents` | Multi-agent spawning and management |
| `@agenticx/feature-knowledge-base` | RAG-based knowledge retrieval |
资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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 │
└──────────┘ └───────────┘ └────────────┘
```
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
### WeChat Integration
The desktop application supports WeChat integration via the iLink protocol:
```mermaid
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
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
## Security Architecture
### Audit Chain Verification
The audit system implements chain verification to ensure log integrity:
| Status | Description |
|--------|-------------|
| `full` | Full table chain verification passed |
| `valid` | Chain verification in progress |
| `failed` | Chain verification failed with reason |
Each audit log entry includes a chain signature that can be verified against the full table state.
资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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
资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
## Deployment Architecture
### Project Templates
AgenticX provides deployment templates for different use cases:
| Template | Command | Use Case |
|----------|---------|----------|
| `mcp` | `agx volcengine init --template mcp` | Tool auto-discovery and sharing |
| `a2a` | `agx volcengine init --template a2a` | Multi-agent collaboration |
| `knowledge` | `agx volcengine init --template knowledge` | Knowledge base RAG |
资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
### CLI Commands
| Command | Description |
|---------|-------------|
| `agx volcengine init` | Initialize new project from template |
| `agx volcengine logs [--follow]` | View deployment logs |
| `agx volcengine destroy` | Clean up deployed resources |
## Data Flow
### Bulk Import Flow
```mermaid
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
```mermaid
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:
| State | Badge | Description |
|-------|-------|-------------|
| `installed` | Green | Tool globally installed |
| `installing` | Blue | Installation in progress |
| `manual_required` | Orange | User must install manually |
| `not_installed` | Gray | Not yet installed |
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
### Theme and Localization
The platform supports dynamic theme switching:
| Theme Mode | Description |
|------------|-------------|
| `light` | Light color scheme |
| `dark` | Dark color scheme |
| `system` | Follow OS preference |
Supported locales: `zh` (Chinese), `en` (English)
资料来源：[enterprise/apps/web-portal/src/components/WorkspaceShell.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/web-portal/src/components/WorkspaceShell.tsx)
---
## Core Abstractions
### 相关页面
相关主题：[System Architecture](#page-architecture), [Agent Core System](#page-agent-core), [Tool System and MCP Hub](#page-tool-system)
相关源码文件
以下源码文件用于生成本页说明：
- [agenticx/core/agent.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent.py) *(未在上下文中找到)*
- [agenticx/core/task.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task.py) *(未在上下文中找到)*
- [agenticx/core/tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/tool.py) *(未在上下文中找到)*
- [agenticx/core/component.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/component.py) *(未在上下文中找到)*
- [agenticx/core/event_bus.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/event_bus.py) *(未在上下文中找到)*
- [agenticx/core/message.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/message.py) *(未在上下文中找到)*
**注意**：指定的 Core 模块源文件未出现在本次检索的上下文中。页面基于可见的代码结构和命名约定生成，标注为"基于推断"的部分需要后续对照源码验证。
# 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.
---
## Overview
AgenticX follows a modular, composable architecture where every functional unit is modeled as a first-class abstraction. The core layer defines:
- **Agent** — The primary executor that coordinates tasks, tools, and message handling
- **Task** — A unit of work with prompts, execution constraints, and state tracking
- **Tool** — Callable functions and external integrations available to agents
- **Component** — Reusable building blocks that can be mixed into agents
- **EventBus** — Publish/subscribe infrastructure for inter-component messaging
- **Message** — Standardized data structures for agent communication
---
## Architecture Diagram
```mermaid
graph TD
A[User Input] --> B[Agent]
B --> C[Task Executor]
B --> D[Tool Registry]
B --> E[Message Bus]
C --> F[Task]
F --> G[Prompt Engine]
D --> H[Tool 1]
D --> I[Tool 2]
D --> J[Tool N]
E --> K[EventBus]
K --> L[Component 1]
K --> M[Component 2]
N[Model Provider] --> B
O[External Services] --> D
```
---
## Agent Abstraction
The `Agent` class is the central coordinator that orchestrates all other abstractions. It manages the execution loop, tool invocations, message history, and component lifecycle.
### Key Responsibilities
| Responsibility | Description |
|----------------|-------------|
| Execution Control | Runs the agent loop, handling user prompts and model responses |
| Tool Management | Maintains a registry of available tools and routes tool calls |
| Message Handling | Processes incoming messages and maintains conversation history |
| Component Integration | Loads and coordinates components for extended functionality |
| State Management | Tracks execution state, errors, and result outputs |
### Agent Configuration
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Unique identifier for the agent |
| `model` | `str` | Model provider/model identifier (e.g., `openai/gpt-4o`) |
| `provider` | `str` | LLM provider backend |
| `tools` | `List[Tool]` | List of tools the agent can invoke |
| `system_prompt` | `str` | Base instructions guiding agent behavior |
| `max_retries` | `int` | Maximum retry attempts for failed operations |
资料来源：[agenticx/core/agent.py]() *(源码待验证)*
---
## Task Abstraction
Tasks represent discrete units of work that an agent can execute. They encapsulate the prompt, execution parameters, and runtime state.
### Task State Machine
```mermaid
stateDiagram-v2
[*] --> Pending
Pending --> Running : start()
Running --> Success : complete()
Running --> Failed : error
Running --> Pending : retry
Success --> [*]
Failed --> [*]
```
### Task Properties
| Property | Type | Description |
|----------|------|-------------|
| `prompt` | `str` | The task instruction or question |
| `workspace` | `Optional[str]` | Working directory or context path |
| `enabled` | `bool` | Whether the task can execute |
| `lastRunAt` | `Optional[datetime]` | Timestamp of last execution |
| `lastRunStatus` | `Optional[str]` | Outcome: `success`, `error` |
| `lastRunError` | `Optional[str]` | Error message if failed |
资料来源：[desktop/src/components/automation/TaskList.tsx](desktop/src/components/automation/TaskList.tsx) *(前端实现参照)*
---
## Tool Abstraction
Tools extend agent capabilities by providing callable functions for external operations. Tools can be local Python functions or remote service integrations.
### Tool Registration Flow
```mermaid
sequenceDiagram
participant A as Agent
participant T as Tool Registry
participant M as Model
participant E as External Service
A->>T: Register Tool
M-->>A: Generate Tool Call
A->>E: Execute via Tool
E-->>A: Return Result
A->>M: Pass Result to Model
```
### Tool Installation States
| State | Badge | Description |
|-------|-------|-------------|
| `installed` | 已安装 | Tool binary present and functional |
| `installing` | 安装中 | Installation in progress |
| `manual_required` | 需手动安装 | User must install externally |
| `not_installed` | 未安装 | Tool not found, can be installed |
资料来源：[desktop/src/components/SettingsPanel.tsx](desktop/src/components/SettingsPanel.tsx)
### Registry Tool Structure
| Field | Type | Description |
|-------|------|-------------|
| `name` | `str` | Tool identifier |
| `description` | `Optional[str]` | Human-readable description |
| `enabled` | `bool` | Availability status |
---
## Component Abstraction
Components are reusable functional units that can be mixed into agents to provide specific capabilities. They communicate via the EventBus and expose lifecycle hooks.
### Component Features
| Feature | Description |
|---------|-------------|
| Lifecycle Hooks | `on_init`, `on_start`, `on_stop` methods |
| Event Subscription | Subscribe to specific event types via EventBus |
| State Sharing | Components can share state through the agent context |
资料来源：[agenticx/core/component.py]() *(源码待验证)*
---
## EventBus Abstraction
The EventBus provides a publish/subscribe messaging infrastructure for loose coupling between components.
### Event Flow
```mermaid
graph LR
P[Publisher] -->|emit| EB[EventBus]
EB -->|dispatch| S1[Subscriber 1]
EB -->|dispatch| S2[Subscriber 2]
EB -->|dispatch| SN[Subscriber N]
```
### Supported Event Types
| Event | Trigger |
|-------|---------|
| `agent.start` | Agent execution begins |
| `agent.complete` | Agent finishes execution |
| `tool.call` | A tool is invoked |
| `tool.result` | Tool execution returns |
| `error` | Any error occurs in the pipeline |
资料来源：[agenticx/core/event_bus.py]() *(源码待验证)*
---
## Message Abstraction
Messages are the standard units of communication between agents, components, and external systems.
### Message Structure
| Field | Type | Description |
|-------|------|-------------|
| `role` | `str` | Sender role: `user`, `assistant`, `system`, `tool` |
| `content` | `str` | Message body |
| `tool_calls` | `Optional[List]` | Tool invocation metadata |
| `tool_call_id` | `Optional[str]` | Correlation ID for tool responses |
| `metadata` | `Optional[Dict]` | Additional contextual data |
资料来源：[agenticx/core/message.py]() *(源码待验证)*
---
## Integration with Enterprise Features
The core abstractions compose with enterprise-level features:
### Skill System
Agents can be configured with skills—specialized capabilities loaded from:
- Global skill directory (`.agents/skills/`)
- Third-party scan paths
- Custom skill paths
资料来源：[desktop/src/components/AvatarCreateDialog.tsx](desktop/src/components/AvatarCreateDialog.tsx)
### Model Management
The admin console provides UI for managing model providers and configurations:
| Field | Description |
|-------|-------------|
| `id` | Unique provider identifier |
| `displayName` | Human-readable name |
| `models` | List of available model IDs |
资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx](enterprise/apps/admin-console/src/app/admin/models/page.tsx)
---
## Quick Start Pattern
```python
from agenticx import Agent, Tool, Message
# Define a custom tool
calculator = Tool(
name="calculator",
description="Perform arithmetic operations",
func=compute
)
# Create an agent
agent = Agent(
name="math-assistant",
model="openai/gpt-4o",
tools=[calculator],
system_prompt="You are a helpful math assistant."
)
# Execute
response = agent.run(Message(role="user", content="What is 2 + 2?"))
print(response.content)
```
---
## See Also
- [Collaboration Patterns](../collaboration/README.md) — Multi-agent coordination using Core Abstractions
- [Tool Integration](../integrations/) — Built-in tool adapters
- [Enterprise IAM](../enterprise/features/iam/) — Access control for agents
---
## Agent Core System
### 相关页面
相关主题：[Meta-Agent and Team Management](#page-meta-agent), [Tool System and MCP Hub](#page-tool-system), [Memory System](#page-memory-system)
相关源码文件
以下源码文件用于生成本页说明：
- [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py)
- [agenticx/core/self_repair.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/self_repair.py)
- [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/overflow_recovery.py)
- [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task_validator.py)
- [agenticx/core/reflector.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)
- [agenticx/core/guiderails.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/guiderails.py)
# 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
```mermaid
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](https://github.com/DemonDamon/AgenticX/blob/main/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:**
| Category | Description |
|----------|-------------|
| Structural | Output format and schema compliance |
| Semantic | Logical consistency and coherence |
| Safety | Absence of harmful or inappropriate content |
| Completeness | Full task requirement fulfillment |
**Source:** [agenticx/core/task_validator.py](https://github.com/DemonDamon/AgenticX/blob/main/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](https://github.com/DemonDamon/AgenticX/blob/main/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:**
| Strategy | Purpose |
|----------|---------|
| Context Trimming | Remove less relevant historical context |
| Summary Generation | Compress conversation history |
| Priority Preservation | Retain essential state information |
| Progressive Cleanup | Gradual memory release |
**Source:** [agenticx/core/overflow_recovery.py](https://github.com/DemonDamon/AgenticX/blob/main/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](https://github.com/DemonDamon/AgenticX/blob/main/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](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/reflector.py)
## Execution Flow
```mermaid
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](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) - State management
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) - Configuration UI
- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx) - Task automation
### Enterprise Features
Enterprise features build upon the core system to provide additional capabilities:
| Feature | Module | Integration Point |
|---------|--------|-------------------|
| Knowledge Base | `@agenticx/feature-knowledge-base` | Context enrichment |
| Agent Management | `@agenticx/feature-agents` | Multi-agent orchestration |
| Identity & Access | `@agenticx/feature-iam` | Security and permissions |
| Tools MCP | `@agenticx/feature-tools-mcp` | Tool integration |
**Related Files:**
- [enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
- [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/audit/page.tsx) - Audit logging interface
- [enterprise/apps/admin-console/src/app/admin/models/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/admin/models/page.tsx) - Model management
## Configuration Options
The Agent Core System supports various configuration parameters:
| Parameter | Description | Default |
|-----------|-------------|---------|
| `max_iterations` | Maximum execution iterations per task | Configurable |
| `timeout_seconds` | Task execution timeout | Platform dependent |
| `memory_limit` | Maximum memory allocation | Based on plan tier |
| `enable_self_repair` | Enable automatic error correction | Enabled |
| `enable_guiderails` | Enable safety mechanisms | Enabled |
| `reflection_level` | Reflection detail depth | Standard |
## 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](../sandbox/README.md) - Isolated execution environment
- [Collaboration Mode](../collaboration/README.md) - Multi-agent cooperation
- [AgentKit Integration](../integrations/agentkit/) - External framework integration
---
## Meta-Agent and Team Management
### 相关页面
相关主题：[Agent Core System](#page-agent-core), [Avatar and Group Chat](#page-avatar-system)
相关源码文件
以下源码文件用于生成本页说明：
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)
- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
- [enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/iam/roles/page.tsx)
# 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
资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
## Architecture
The system follows a layered architecture:
```graph TD
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
| Component | Purpose | Key File Reference |
|-----------|---------|-------------------|
| **Meta-Agent** | Top-level coordinator that decomposes tasks and delegates to team members | `agenticx/collaboration/README.md` |
| **Team Manager** | Manages agent lifecycle, grouping, and inter-agent communication | Collaboration patterns |
| **Agent Clone (Avatar)** | Individual agent with specific prompt, model, and workspace configuration | `desktop/src/components/AvatarCreateDialog.tsx` |
| **Skills System** | Modular capability extensions attachable to agents | `desktop/src/components/SettingsPanel.tsx` |
| **Tool Registry** | Centralized tool definitions and permissions | `desktop/src/components/SettingsPanel.tsx` |
| **Role-Based Access** | IAM integration for agent permissions | `enterprise/apps/admin-console/src/app/iam/roles/page.tsx` |
资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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
```typescript
// Avatar configuration interface (simplified)
interface AgentClone {
id: string;
name: string;
prompt: string;
workspace?: string;
provider?: string;
model?: string;
enabledSkills: string[];
enabled: boolean;
}
```
资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)
### Skills Configuration
Skills can be assigned to agents with fine-grained control:
| Setting | Description |
|---------|-------------|
| **Global Skills** | Skills available to all agents, can be disabled per-agent |
| **Agent-Specific Skills** | Skills enabled only for particular agents |
| **Skill Source Priority** | Preferred source when multiple skill definitions exist |
| **Disabled Skills** | Skills explicitly disabled at global or agent level |
```tsx
// Skills UI state management
const [skillsEnabledDraft, setSkillsEnabledDraft] = useState>({});
const [preferredSkillSources, setPreferredSkillSources] = useState>({});
```
资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)
## Team Management
### Team Structure
Agents are organized into teams with coordinated behavior:
```graph TD
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:
| Mode | Description | Use Case |
|------|-------------|----------|
| **Custom Pattern** | User-defined collaboration flow | Complex, non-standard workflows |
| **Sequential** | Agents execute tasks in order | Pipeline processing |
| **Parallel** | Multiple agents work simultaneously | Independent subtasks |
| **Hierarchical** | Meta-agent delegates to specialists | Decomposed complex tasks |
```python
# Pattern registration in manager
pattern_classes = {
CollaborationMode.CUSTOM_PATTERN: CustomPattern,
# ... other modes
}
```
资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
## Task Automation
### Task Configuration
Automated tasks can be assigned to agents with scheduling and execution parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Unique task identifier |
| `enabled` | boolean | Whether task is active |
| `prompt` | string | Task instruction |
| `workspace` | string | Working directory |
| `provider` | string | Model provider |
| `model` | string | Model identifier |
| `lastRunAt` | timestamp | Last execution time |
| `lastRunStatus` | enum | "success" / "error" |
| `lastRunError` | string | Error message if failed |
### Task Execution States
```graph TD
A[Scheduled] --> B{Running}
B -->|Success| C[Completed]
B -->|Error| D[Failed]
D -->|Retry| B
C --> E[Update Status]
E --> F[Ready for Next]
```
资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
## Tool Registry and Permissions
### Tool Management
Tools are registered centrally and can be:
| Status | Badge | Description |
|--------|-------|-------------|
| **Installed** | Green "已安装" | Tool executable available |
| **Installing** | Accent color "安装中" | Installation in progress |
| **Manual Required** | Amber "需手动安装" | User action needed |
| **Not Installed** | Red "未安装" | Tool not present |
### Denied Tools
Specific tools can be explicitly denied for security:
```tsx
{deniedTools.map((toolPat, idx) => (
))}
```
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
## Role-Based Access Control
### Role Permissions for Agents
Agent operations are governed by role-based permissions:
| Permission | Scope | Description |
|------------|-------|-------------|
| `agents:read` | Global/Team | View agent configurations |
| `agents:write` | Global/Team | Create/modify agents |
| `agents:execute` | Agent-specific | Run agent tasks |
| `skills:manage` | Global | Configure global skills |
| `tools:approve` | Admin | Approve tool requests |
### Role Management UI
The admin console provides role management with scope matrix editing:
```tsx
```
资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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)
```tsx
const wechatStatus = await window.agenticxDesktop.wechatSidecarPort();
if (!running) {
const startRes = await window.agenticxDesktop.wechatSidecarStart();
}
```
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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
```graph LR
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:
| Module | Purpose |
|--------|---------|
| `@agenticx/feature-agents` | Core agent management |
| `@agenticx/feature-knowledge-base` | Knowledge retrieval integration |
| `@agenticx/feature-tools-mcp` | MCP (Model Context Protocol) tool integration |
| `@agenticx/feature-iam` | Identity, roles, and permissions |
| `@agenticx/feature-chat` | Chat workspace UI |
```tsx
import { featureName } from "@agenticx/feature-agents";
```
资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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
```tsx
description={`共 ${items.length} 条记录 · ${
chainFull?.valid ? "全表链校验通过" : "全表链校验失败"
}`}
```
资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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.
---
## Tool System and MCP Hub
### 相关页面
相关主题：[Agent Core System](#page-agent-core)
相关源码文件
以下源码文件用于生成本页说明：
- [agenticx/tools/function_tool.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/function_tool.py)
- [agenticx/tools/mcp_hub.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/mcp_hub.py)
- [agenticx/tools/remote_v2.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/remote_v2.py)
- [agenticx/tools/openapi_toolset.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/openapi_toolset.py)
- [agenticx/tools/sandbox_tools.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/sandbox_tools.py)
- [agenticx/tools/guardrails/builtin.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/guardrails/builtin.py)
# 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:
```mermaid
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.
```python
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
```mermaid
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
```
资料来源：[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
```mermaid
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:
| Feature | Description |
|---------|-------------|
| Server Management | Register and manage multiple MCP server connections |
| Tool Discovery | Automatic discovery of available tools from connected servers |
| Connection Pooling | Efficient reuse of MCP client connections |
| Error Handling | Graceful degradation when servers are unavailable |
| Tool Registry Integration | Seamless integration with the AgenticX tool registry |
资料来源：[agenticx/tools/mcp_hub.py]()
### Usage Pattern
```python
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
```mermaid
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
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `base_url` | string | required | Base URL for the remote service |
| `timeout` | int | 30 | Request timeout in seconds |
| `max_retries` | int | 3 | Maximum retry attempts |
| `pool_size` | int | 10 | Connection pool size |
| `auth_type` | string | "none" | Authentication type: bearer, api_key, basic |
资料来源：[agenticx/tools/remote_v2.py]()
### Implementation
```python
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
```mermaid
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
| Feature | Status | Description |
|---------|--------|-------------|
| GET requests | Supported | Retrieve resources |
| POST requests | Supported | Create resources |
| PUT/PATCH requests | Supported | Update resources |
| DELETE requests | Supported | Remove resources |
| Authentication | Supported | Bearer, API Key, OAuth2 |
| Request body schemas | Supported | JSON Schema validation |
| Response parsing | Supported | Automatic result extraction |
资料来源：[agenticx/tools/openapi_toolset.py]()
### Usage Example
```python
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
```mermaid
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
| Template | Use Case | CPU | Memory | Timeout |
|----------|----------|-----|--------|---------|
| LIGHTWEIGHT_TEMPLATE | Quick computations | 1 core | 512MB | 30s |
| HIGH_PERFORMANCE_TEMPLATE | Complex operations | 4 cores | 8GB | 300s |
| CODE_INTERPRETER | Python execution | 2 cores | 4GB | 120s |
### Error Handling
The sandbox module defines specific exception types for different failure scenarios:
```python
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}")
```
资料来源：[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
```mermaid
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
| Guardrail | Purpose | Configuration |
|-----------|---------|---------------|
| InputValidation | Validate parameter types and ranges | Schema-based |
| RateLimiting | Prevent excessive calls | Calls per time window |
| ContentFilter | Block sensitive content patterns | Pattern matching |
| OutputSanitizer | Remove sensitive data from results | Data classification |
| AuditLogger | Log all tool invocations | Structured logging |
资料来源：[agenticx/tools/guardrails/builtin.py]()
### Implementation Pattern
```python
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.
```mermaid
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
| Criterion | Description |
|-----------|-------------|
| Capability Match | Tool can solve the required sub-task |
| Availability | Tool is registered and accessible |
| Permission | Agent has permission to invoke tool |
| Rate Limits | Tool rate limits not exceeded |
| Guardrail Compliance | Request passes all guardrail checks |
## 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.
---
## Memory System
相关源码文件
以下源码文件用于生成本页说明：
- [agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)
- [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md)
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
- [agenticx/memory/__init__.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/__init__.py)
- [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md)
# Memory System
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 │ │
│ └─────────────┴───────────────┴───────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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.
```python
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")
```
资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)
| Parameter | Type | Description |
|-----------|------|-------------|
| `tenant_id` | `str` | Unique identifier for tenant isolation |
| `content` | `str` | Memory content text |
| `metadata` | `dict` | Optional key-value metadata for categorization |
### 2. KnowledgeBase
KnowledgeBase enables organization of content into specialized domains with content-type filtering.
```python
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")
```
资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)
| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Knowledge base identifier |
| `memory_backend` | `MemoryBackend` | Underlying storage implementation |
| `allowed_content_types` | `set[str]` | Filter for permitted content types |
### 3. MemoryComponent
The MemoryComponent provides intelligent memory operations with automatic cleanup and advanced retrieval capabilities.
```python
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"}
)
```
资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/README.md)
## Memory Backend Types
| Backend Type | Use Case | Persistence |
|--------------|----------|-------------|
| `ShortTermMemory` | Session state, temporary data | Ephemeral with optional persistence |
| `EpisodicMemory` | Event sequences, conversation history | Long-term storage |
| `SemanticMemory` | Embedding-based semantic search | Vector-enabled storage |
| `HierarchicalMemory` | Multi-level memory organization | Tiered storage |
| `Mem0Memory` | Healthcare, personalized data | Specialized domain storage |
## MCP Integration
The Memory System supports Model Context Protocol (MCP) for external memory service integration.
```python
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")
```
资料来源：[agenticx/memory/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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.
```bash
# Run healthcare memory example
python examples/mem0_healthcare_example.py
```
资料来源：[README.md](https://github.com/DemonDamon/AgenticX/blob/main/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.
```tsx
// SettingsPanel.tsx integration
import { useAgenticxDesktop } from "@agenticx/desktop";
const memorySettings = {
enableMemorySync: true,
syncInterval: 30000, // ms
maxMemorySize: "100MB"
};
```
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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
资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/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.
```bash
# Run intent recognition example
python examples/agenticx-for-intent-recognition/main.py
```
资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/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
```python
memory_id = await memory.add(
content: str,
metadata: Optional[dict] = None,
content_type: Optional[str] = None,
embedding: Optional[list[float]] = None
) -> str
```
### Search Memory
```python
results = await memory.search(
query: str,
limit: int = 10,
content_type: Optional[str] = None,
filters: Optional[dict] = None
) -> list[MemoryResult]
```
### Delete Memory
```python
await memory.delete(memory_id: str) -> bool
```
### Update Memory
```python
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:
```python
# 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:
| Content Type | Description |
|--------------|-------------|
| `tutorial` | Educational content |
| `guide` | How-to documentation |
| `faq` | Frequently asked questions |
| `code` | Code snippets and examples |
| `snippet` | Small code fragments |
### Metadata Usage
Leverage metadata for enhanced search and filtering:
```python
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:
| Package | Purpose |
|---------|--------|
| `mem0ai` | Mem0 memory backend integration |
| `chromadb` | Vector storage for semantic search |
| `pydantic` | Data validation and serialization |
## 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.
---
## Avatar and Group Chat
相关源码文件
以下源码文件用于生成本页说明：
- [desktop/src/components/AvatarSettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarSettingsPanel.tsx)
- [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)
- [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx)
- [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx)
- [enterprise/features/chat/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/chat/README.md)
- [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md)
- [enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md)
# Avatar and Group Chat
## 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
资料来源：[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:
| Property | Type | Description |
|----------|------|-------------|
| `name` | string | Display name of the avatar |
| `role` | string | Professional role description (e.g., "Full-stack Developer", "Data Analyst") |
| `avatarUrl` | string | Path to the avatar's profile image |
| `skills` | string[] | List of enabled skills for this avatar |
| `systemPrompt` | string | Custom system prompt override |
| `userPreference` | string | User preference injection for behavioral tuning |
资料来源：[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.yaml
```
The UI indicates this clearly: "保存后写入该分身目录下的 avatar.yaml" (Saved to the avatar.yaml file under the avatar directory after saving).
资料来源：[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
2. **Metadata Configuration**
- `name`: Avatar display name
- `role`: Professional role descriptor
资料来源：[desktop/src/components/AvatarSettingsPanel.tsx]()
## Avatar Creation Dialog
The `AvatarCreateDialog` component handles the initial creation of new avatars with skill selection.
### Skill Assignment Workflow
```mermaid
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
| State | Visual Indicator | Description |
|-------|-------------------|-------------|
| Enabled | Cyan border with background | Skill is active for this avatar |
| Disabled | Muted border, muted text | Skill is not used by this avatar |
```tsx
// 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"
```
资料来源：[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
| Setting | Description | Character Limit |
|---------|-------------|-----------------|
| `userPreference` | Behavioral style instructions for agents | 500 characters |
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
资料来源：[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:
资料来源：[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:
```mermaid
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]
```
资料来源：[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:
| Property | Description |
|----------|-------------|
| `prompt` | The task instruction prompt |
| `workspace` | Working directory for task execution |
| `provider` | LLM provider for task execution |
| `model` | Specific model to use |
| `enabled` | Whether the task is active |
| `lastRunAt` | Timestamp of last execution |
| `lastRunStatus` | Execution result (success/error) |
| `lastRunError` | Error message if failed |
### 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
资料来源：[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
资料来源：[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
资料来源：[desktop/src/components/SettingsPanel.tsx]()
## Configuration Schema
### Avatar YAML Structure
```yaml
# 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
| Mode | Behavior | Risk Level |
|------|----------|------------|
| `manual` | Confirm every tool execution | Safest |
| `semi-auto` | Auto-approve whitelisted operations | Recommended |
| `auto` | Execute all tools automatically | High Risk |
资料来源：[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 踩坑日志
项目：DemonDamon/AgenticX
摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)。
## 1. 安装坑 · 来源证据：Desktop app fails on startup: agx serve failed to start (local API not available)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Desktop app fails on startup: agx serve failed to start (local API not available)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4330954394974f1ab2f82c8645e1dce9 | https://github.com/DemonDamon/AgenticX/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：AgenticX + Machi v0.3.7
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AgenticX + Machi v0.3.7
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f4983001c0714fbe923df9e3263934b3 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：MCP will report an error upon startup: "[Errno 2] No such file or directory".
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP will report an error upon startup: "[Errno 2] No such file or directory".
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_026abb56e0864ba4b60ba497e1a19084 | https://github.com/DemonDamon/AgenticX/issues/14 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：Machi launch failure on mac
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Machi launch failure on mac
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1f85a307f6b44099b52dfdb50d13f91c | https://github.com/DemonDamon/AgenticX/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安装坑 · 来源证据：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：UX: Cannot queue follow-up messages while `bash_exec` (or tool) is running; UI blocks until stop or completion
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_170a543fa1d640b7a6c9c54d5b9ce6c1 | https://github.com/DemonDamon/AgenticX/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安装坑 · 来源证据：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: Document ingestion fails for PDF files (missing PDF reader libs / missing numpy)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2d8c2ce59a394bd8901a52ddaf36f821 | https://github.com/DemonDamon/AgenticX/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | README/documentation is current enough for a first validation pass.
## 8. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | last_activity_observed missing
## 9. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium
## 10. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | no_demo; severity=medium
## 11. 安全/权限坑 · 来源证据：AgenticX v0.3.5
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.5
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c05bccba0b02475cb74b550d42c91222 | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：AgenticX v0.3.6
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.6
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_619eaf3ee1334cb6bc5db5adb67b7c8f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. 安全/权限坑 · 来源证据：AgenticX v0.3.8
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AgenticX v0.3.8
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3c0dad4f133a4a199f8b54083f16427f | https://github.com/DemonDamon/AgenticX/releases/tag/v0.3.8 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：bash_exec fails to run any command on Windows (WinError 2)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bash_exec fails to run any command on Windows (WinError 2)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_14230559f63c4fd8a7a8d1310b6284d0 | https://github.com/DemonDamon/AgenticX/issues/7 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：添加模型不支持codex 认证方式
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加模型不支持codex 认证方式
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b24824ec7b6e4e7fa6bc5b7b2874817c | https://github.com/DemonDamon/AgenticX/issues/4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 16. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | issue_or_pr_quality=unknown
## 17. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:772408997 | https://github.com/DemonDamon/AgenticX | release_recency=unknown