AgenticX: 统一的多智能体框架

一个统一、可扩展、生产就绪的多智能体应用开发框架

系统架构 • 功能特性 • 快速开始 • 示例 • 进展

Language / 语言: English | 中文

安全公告

LiteLLM（PyPI）： 恶意版本 litellm 1.82.7、1.82.8 已从 PyPI 下架，有报告称存在 窃取 API 密钥 行为。若曾安装上述版本，请 立即卸载、轮换可能泄露的凭据，并 升级 至上游与 PyPI 当前标注为安全的版本（例如按上游说明使用 1.82.9 及以上）。可用 pip show litellm 检查本机环境。

愿景

AgenticX 旨在打造一个统一、可扩展、生产就绪的多智能体应用开发框架，赋予开发者构建从简单自动化助手到复杂协作式智能体系统的全部能力。

系统架构

框架采用 5 层架构：用户界面层（桌面应用 / CLI / SDK）→ Studio 运行时层（会话管理器、Meta-Agent、团队管理器、分身与群聊）→ 核心框架层（编排与执行、智能体、记忆、工具、LLM 提供方、Hooks 钩子）→ 平台服务层（可观测性、通信协议、安全治理、存储）→ 领域扩展层（GUI Agent、知识系统 & GraphRAG、AgentKit 集成）。

核心功能

核心框架

• 智能体核心: 基于 12-Factor Agents 方法论的执行引擎，内置 Meta-Agent CEO 调度器、智能体团队管理、think-act 循环、事件驱动架构、自修复与溢出恢复
• 可嵌入 ReActAgent（SDK 原语）: 规范的异步函数调用 ReAct 循环（ainvoke/astream），含类型化 AgentEvent 事件流、多轮历史进出、并行工具执行，以及可选的循环检测 / 上下文压缩 / Offloader 注入——零 Studio/CLI 耦合（保留 legacy 文本-JSON TextReActAgent 门面以向后兼容）
• 统一卸载（Offload）: Offloader 协议 + 文件后端 FileOffloader，把大体积工具结果 / 压缩上下文移出实时历史（仅留内联引用占位符、按需取回）；并提供在沙箱内运行 MCP server 的 in-workspace MCP 网关
• 编排引擎: 图式工作流引擎 + Flow 系统（装饰器、执行计划），支持条件路由与并行执行
• 工具系统: 统一工具接口，支持函数装饰器、MCP Hub（多服务聚合）、远程工具 v2、OpenAPI 工具集、沙箱工具、技能包、文档路由
• 记忆系统: 分层记忆（核心 / 情景 / 语义）、Mem0 深度集成、工作区记忆、短期记忆、记忆衰减、混合搜索、压缩刷写、MCP 记忆、记忆智能引擎
• LLM 提供方: 15+ 提供方 — OpenAI、Anthropic、Ollama、Gemini、Kimi/Moonshot、MiniMax、Ark/火山引擎、智谱、千帆、百炼/Dashscope — 支持响应缓存、转录清洗、故障转移路由
• 通信协议: A2A 智能体间协议（客户端 / 服务端 / AgentCard / 技能即工具）、MCP 资源访问协议
• 任务验证: 基于 Pydantic 的输出解析、自动修复与护栏机制

分身与团队协作

• 分身系统: 分身注册中心（CRUD）、群聊支持多路由策略（用户指定 / 智能路由 / 轮流回复）
• Meta-Agent 运行时: CEO 调度器动态编排子智能体，团队管理含并发上限、归档快照、会话隔离
• 协作模式: 委派、角色扮演、会话管理、任务锁、协作度量

知识与检索

• 知识库: 文档处理流水线，含分块器、读取器、抽取器、图构建器（GraphRAG）
• 多脑知识库: 可隔离、按分身 / 会话挂载的「文档脑 + 代码脑」架构，支持多脑聚合检索
• 代码语义索引: 多代码库 hybrid（向量 + BM25）检索，与「代码脑」衔接
• 检索系统: 向量检索、BM25 检索、图检索、混合检索、自动检索、重排序器
• 嵌入模型: OpenAI、百炼、SiliconFlow、LiteLLM，支持智能路由

技能与自进化

• 技能系统: 注册与全生命周期管理 — 危险模式安全扫描门禁、5 策略模糊 patch、.changelog 版本变更日志、来源标注与按 skill 启停
• 技能自进化: 运行时采集工具调用观察，复杂会话后台 LLM 复盘自动沉淀新技能；质量门禁、使用统计、低效淘汰构成生命周期闭环
• 扩展生态 (AGX Bundle): Bundle 定义（skills / mcp_servers / avatars / memory_templates）、本地安装卸载、多源注册表聚合搜索

长程自主编码

• 长任务编排: 多任务源（手动队列 / Cron / Linear / 项目特性）轮询、每任务隔离工作区、停滞自愈、续跑 / 失败双轨退避、增量 Token 计量
• 项目状态机: 磁盘级单一事实来源，版本化特性状态机、文件锁 / 原子写，支撑「初始化 → 实现 → 验证 → 提交」可审计闭环

开发者体验

• CLI 工具 (agx): serve、studio、loop、run、project、deploy、codegen、docs、skills、hooks、debug、scaffold、config 等 15+ 命令
• Web UI (Studio): 基于 FastAPI 的管理服务器，支持会话管理、实时 WebSocket、协议对接
• 桌面应用: Electron + React + Zustand + Vite，Pro/Lite 双模式（多窗格 / 单窗格），含命令面板、设置面板、分身侧栏、子智能体面板、会话历史、工作区面板
• IM 远程网关: 飞书 / 企业微信 / 钉钉 / 个人微信(iLink) → 云端 → 本机 Agent 的远程指令中继与回复下发
• Claude Code 桥接: 受 Token 保护的本机 HTTP / NDJSON 控制面，headless（stream-json）与可见 TUI（PTY）双模驱动本地 Claude Code

企业级安全

• 安全层: 泄露检测、输入清洗器、高级注入检测器、策略引擎（规则 / 严重级别 / 动作）、输入验证器、沙箱策略、审计日志
• 沙箱: Docker / Microsandbox / Subprocess / 远端 HTTP 四种后端（三档模式工厂自动选择）；Jupyter 内核管理器、有状态代码解释器、沙箱模板、JSONL 执行审计
• 会话安全: 数据库级会话、写锁、内存会话、会话级多租户（tenant_id）隔离

可观测性与评估

• 监控: 完整回调系统、实时指标、Prometheus/OpenTelemetry 集成、轨迹分析、Span Tree、WebSocket 流式推送
• 评估框架: 基于 EvalSet 的评估、LLM 裁判、组合裁判、Span 评估器、轨迹匹配器、Trace 转换器
• 数据导出: 多格式导出（JSON / CSV / Prometheus）、时间序列分析

存储层

• 键值存储: SQLite、Redis、PostgreSQL、MongoDB、InMemory
• 向量存储: Milvus、Qdrant、Chroma、Faiss、PgVector、Pinecone、Weaviate
• 图存储: Neo4j、Nebula
• 对象存储: S3、GCS、Azure
• 统一管理: 存储路由器、迁移支持、统一存储接口

GUI Agent / 具身智能

• 动作反思机制: A/B/C 动作结果分类，支持启发式和 VLM 两种反思模式
• 卡住检测与恢复: 连续失败检测、重复模式识别、智能恢复策略推荐
• 动作缓存系统: 基于动作树的轨迹缓存，支持精确匹配和模糊匹配（可达 9x 加速）
• REACT 输出解析: 标准化的 REACT 格式解析，紧凑动作 Schema
• Device-Cloud 路由: 根据任务复杂度、敏感性动态选择设备端或云端模型
• DAG 任务验证: 基于 DAG 的多路径任务验证，支持双语义依赖
• 人机协作: 采集器、组件与事件模型，支持人工监督介入

快速开始

安装

方式一：从 PyPI 安装（推荐）

# 核心安装（轻量，无 torch，秒装）
pip install agenticx

# 按需安装可选功能
pip install "agenticx[memory]"      # 记忆系统: mem0, chromadb, qdrant, redis, milvus
pip install "agenticx[document]"    # 文档处理: PDF, Word, PPT 解析
pip install "agenticx[graph]"       # 知识图谱: networkx, neo4j, 社区检测
pip install "agenticx[llm]"         # 额外 LLM: anthropic, ollama
pip install "agenticx[monitoring]"  # 可观测性: prometheus, opentelemetry
pip install "agenticx[mcp]"         # MCP 协议
pip install "agenticx[database]"    # 数据库后端: postgres, SQLAlchemy
pip install "agenticx[data]"        # 数据分析: pandas, scikit-learn, matplotlib
pip install "agenticx[ocr]"         # OCR（会拉入 torch ~2GB）: easyocr
pip install "agenticx[volcengine]"  # 火山引擎 AgentKit
pip install "agenticx[all]"         # 全部功能

提示: 核心包仅包含 ~27 个轻量依赖，安装速度极快。重量级依赖（如 torch、pandas 等）均已移至可选分组，按需安装即可。

MCP 桌面升级（2026-04）: Near 设置页已支持 MCP 品牌自动扫描（Cursor / Trae / Claude / OpenClaw / Hermes / Codex）、内置 Monaco JSON 编辑器（含 schema 校验）以及 ModelScope MCP 市场一键安装。

方式二：从源码安装（开发）

# 克隆仓库
git clone https://github.com/DemonDamon/AgenticX.git
cd AgenticX

# 使用 uv（推荐，比 pip 快 10-100 倍）
pip install uv
uv pip install -e .                  # 核心安装
uv pip install -e ".[memory,graph]"  # 按需加载可选功能
uv pip install -e ".[all]"           # 全部功能
uv pip install -e ".[dev]"           # 开发工具

# 或使用 pip
pip install -e .
pip install -e ".[all]"

环境配置

# 设置环境变量
export OPENAI_API_KEY="your-api-key"
export ANTHROPIC_API_KEY="your-api-key"  # 可选

完整安装指南: 关于系统依赖（antiword、tesseract）和高级文档处理功能的详细信息，请参阅 INSTALL.md

CLI 快速上手

安装后，agx 命令行工具即可使用：

# 查看版本
agx --version

# 创建新项目
agx project create my-agent --template basic

# 启动 API 服务器
agx serve --port 8000

# 解析文档（PDF/PPT/Word 等）
agx mineru parse report.pdf --output ./parsed

完整 CLI 文档: 详见 docs/cli.md

创建第一个智能体

from agenticx import Agent, Task, AgentExecutor
from agenticx.llms import OpenAIProvider

# 创建智能体
agent = Agent(
    id="data-analyst",
    name="数据分析师",
    role="数据分析专家", 
    goal="帮助用户分析和理解数据",
    organization_id="my-org"
)

# 创建任务
task = Task(
    id="analysis-task",
    description="分析销售数据趋势",
    expected_output="详细的分析报告"
)

# 配置LLM
llm = OpenAIProvider(model="gpt-4")

# 执行任务
executor = AgentExecutor(agent=agent, llm=llm)
result = executor.run(task)
print(result)

工具使用示例

from agenticx.tools import tool

@tool
def calculate_sum(x: int, y: int) -> int:
    """计算两个数的和"""
    return x + y

@tool  
def search_web(query: str) -> str:
    """搜索网络信息"""
    return f"搜索结果: {query}"

# 智能体会自动调用这些工具

完整示例

我们提供了丰富的示例来展示框架的各种功能：

智能体核心 (M5)

单智能体示例

# 基础智能体使用
python examples/m5_agent_demo.py

• 展示智能体的基本创建和执行
• 工具调用和错误处理
• 事件驱动的执行流程

多智能体协作

# 多智能体协作示例
python examples/m5_multi_agent_demo.py

• 多个智能体的协作模式
• 任务分发和结果聚合
• 智能体间的通信

编排与验证 (M6 & M7)

简单工作流

# 基础工作流编排
python examples/m6_m7_simple_demo.py

• 工作流的创建和执行
• 任务输出的解析和验证
• 条件路由和错误处理

复杂工作流

# 复杂工作流编排
python examples/m6_m7_comprehensive_demo.py

• 复杂的工作流图结构
• 并行执行和条件分支
• 完整的生命周期管理

智能体通信 (M8)

A2A 协议演示

# 智能体间通信协议
python examples/m8_a2a_demo.py

• Agent-to-Agent 通信协议
• 分布式智能体系统
• 服务发现和技能调用

可观测性监控 (M9)

完整监控演示

# 可观测性模块演示
python examples/m9_observability_demo.py

• 实时性能监控
• 执行轨迹分析
• 失败分析和恢复建议
• 数据导出和报告生成

记忆系统

基础记忆使用

# 记忆系统示例
python examples/memory_example.py

• 长期记忆的存储和检索
• 上下文记忆管理

医疗场景应用

# 医疗记忆场景
python examples/mem0_healthcare_example.py  

• 医疗知识的记忆和应用
• 个性化的患者信息管理

人机协作

人工干预流程

# 人机协作示例
python examples/human_in_the_loop_example.py

• 人工审批工作流
• 人机协作模式
• 风险控制机制

详细说明请参考: examples/README_HITL.md

LLM 集成

聊天机器人

# LLM聊天示例
python examples/llm_chat_example.py

• 多模型支持演示
• 流式响应处理
• 成本控制和监控

安全沙箱

代码执行沙箱

# 微沙箱示例
python examples/microsandbox_example.py

• 安全的代码执行环境
• 资源限制和隔离

技术博客: examples/microsandbox_blog.md

意图识别服务

智能意图识别系统

# 意图识别服务示例
python examples/agenticx-for-intent-recognition/main.py

一个完全基于 AgenticX 框架构建的生产级分层意图识别服务，展示了 Agent、Workflow、Tool、Storage 等核心系统的真实应用场景。

架构设计： - Agent 层: 层次化智能体设计 — 基础 IntentRecognitionAgent（LLM 驱动）搭配专业智能体（GeneralIntentAgent、SearchIntentAgent、FunctionIntentAgent），实现细粒度意图分类 - 工作流引擎: 流水线式编排 — 文本预处理 → 意图分类 → 实体抽取 → 规则匹配 → 后处理；每种意图类型还有专属工作流 - 工具系统: 混合实体抽取（UIE + LLM + Rule 三源融合，置信度加权），正则/精确匹配工具，以及完整的后处理套件（置信度调整、冲突解决、实体优化、意图精化） - API 网关: 异步服务层，支持限流、并发控制、批量处理、健康检查和性能指标监控 - 存储层: 基于 SQLite 的数据持久化，通过 UnifiedStorageManager 管理训练数据 - 数据模型: 基于 Pydantic 的类型安全数据契约，覆盖 API 请求/响应和领域对象

核心能力： - 三层意图分类: 通用对话（问候、闲聊）、信息搜索（事实/方法/对比查询）、工具/功能调用 - 混合实体抽取: 融合 UIE 模型、LLM 和规则抽取器，支持多种智能融合策略 - 完整后处理流水线: 置信度调整、冲突解决、实体优化、意图精化一体化处理 - 高可扩展性: 新增意图类型只需添加新的 Agent 和 Workflow，无需修改已有代码

详见: examples/agenticx-for-intent-recognition/

GUI Agent / 具身智能 (M16)

GUI 自动化智能体

# GUI Agent 示例
python examples/agenticx-for-guiagent/AgenticX-GUIAgent/main.py

• 完整的 GUI 自动化框架，基于人类对齐学习理念
• 动作反思（A/B/C 分类）和卡住检测
• 动作缓存系统，性能优化可达 9x 加速
• REACT 输出解析和紧凑动作 Schema
• Device-Cloud 路由，智能模型选择
• DAG 任务验证，多路径任务定义和验证

核心能力： - 动作反思: 自动动作结果分类（成功/错误状态/无变化） - 卡住检测: 连续失败检测和恢复策略推荐 - 动作缓存: 轨迹缓存，支持精确匹配和模糊匹配（可达 9x 加速） - REACT 解析: 标准化的 REACT 格式输出解析 - 智能路由: 根据任务复杂度和敏感性动态选择设备端或云端模型 - DAG 验证: 多路径任务验证，支持双语义依赖

详见: examples/agenticx-for-guiagent/

更多应用示例

技术架构

```mermaid graph TD subgraph "用户界面层" Desktop["桌面应用 (Electron + React)"] CLI["CLI 命令行 (agx serve / loop / run / project)"] SDK[Python SDK] end

subgraph "Studio 运行时层"
    StudioServer["Studio 服务 (FastAPI)"]
    SessionMgr[会话管理器]
    MetaAgent["元智能体 (CEO 调度器)"]
    TeamMgr[智能体团队管理器]
    AvatarSys["分身 & 群聊系统"]
end

subgraph "核心框架层"
    subgraph "编排"
        WorkflowEngine[工作流引擎]
        Flow["Flow 流程系统"]
    end
    subgraph "执行"
        AgentRuntime["AgentRuntime (Studio 路径)"]
        AgentExecutor["AgentExecutor (Core 路径)"]
        TaskValidator[任务验证 & 输出解析]
    end
    subgraph "核心组件"
        Agent[智能体 Agent]
        Task[任务 Task]
        Tool["工具系统 & MCP Hub"]
        Memory["记忆 (Mem0 / 短期 / 工作区)"]
        LLM["LLM 提供方 (OpenAI / Anthropic / Ollama / 10+)"]
    end
    Collaboration["协作 & 委派"]
    Hooks["Hooks 钩子系统"]
end

subgraph "平台服务层"
    subgraph "可观测性"
        Monitoring["监控 & 轨迹分析"]
        Prometheus[Prometheus / OpenTelemetry]
    end
    subgraph "通信协议"
        A2A["A2A 智能体间协议"]
        MCP["MCP 协议"]
    end
    subgraph "安全治理"
        Safety["安全层 (泄露检测 / 清洗 / 策略)"]
        Sandbox["执行沙箱"]
    end
    subgraph "存储"
        KVStore["键值存储 (SQLite / Redis)"]
        VectorStore["向量存储 (Milvus / Qdrant / Chroma)"]
        GraphStore["图存储 (Neo4j / NetworkX)"]
    end
end

subgraph "领域扩展"
    Embodiment["GUI Agent / 具身智能"]
    Knowledge["知识系统 & GraphRAG"]
end

Desktop --> StudioServer
CLI --> StudioServer
SDK --> AgentExecutor

StudioServer --> SessionMgr
SessionMgr --> MetaAgent
MetaAgent --> TeamMgr
MetaAgent --> AvatarSys
TeamMgr --> AgentRuntime

AgentRuntime --> Agent
AgentExecutor --> Agent
WorkflowEngine --> AgentExecutor

Agent --> Tool
Agent --> Memory
Agent --> LLM
Agent --> Hooks

AgentRuntime --> Monitoring
AgentExecutor --> Monitoring
Agent --> A2A
Tool --> MCP

Agent --> Safety
Memory --> KVSt