架构

AgenticX 系统架构概览。

架构

概述

AgenticX 是一套能力核心，上面叠三种产品形态：

Core / Runtime：Python SDK、Studio Server 与 Agent Runtime
Near Desktop：本地优先工作区，默认走本机 agx serve
Enterprise：Portal、Admin Console 与 Go AI 网关，面向受管控的 Web 访问

Near 与 Enterprise 共用抽象，当前部署路径彼此独立。网关是合规与模型中继，不是完整的 Agent Runtime。

示意图：SDK、Near、Enterprise 启动的是不同进程；只有 Near 跑 AgentRuntime。

Runtime 内部仍可按五层来读，从用户界面到平台服务。

示意图：界面 → Studio → 核心循环 → 协议 → ~/.agenticx 平台文件。

实践案例：同一句话，三扇门

场景。 「总结这个仓库的 README。」

入口	你实际启动的	循环跑在哪
SDK	`AgentExecutor(llm_provider=...).run(agent=, task=)`	你的 Python 进程
Near	应用 → 本机 `agx serve` → `AgentRuntime.run_turn`	`127.0.0.1` 上的 Studio
Enterprise	Portal → Go 网关 → 上游模型	网关策略 / 配额；不是 `AgentRuntime`

你会看到。 Near：聊天窗格、工具卡、~/.agenticx/sessions/<id>/messages.json。Enterprise：浏览器工作区；命中规则时有审计 / 策略提示。不要指望网关后面还有 Desktop 窗格。

上面三张正式架构图是产品总图，需要一眼看完整栈时用它们。

第 1 层：用户界面

Near Desktop

Electron + React + Zustand + Vite。多窗格聊天、分身、群聊、工作区、终端、自动化与语音焦点。详见 Near 桌面。

CLI（`agx`）

功能完整的命令行工具，涵盖：serve、studio、loop、run、project、deploy、codegen、docs、skills、hooks、debug、scaffold、配置管理等。

请参阅 CLI 参考 →

SDK

用于将 AgenticX 嵌入自有应用的 Python SDK。

第 2 层：Studio 运行时

Session Manager

管理用户会话、聊天历史持久化（messages.json）、写锁与内存状态，并支持跨会话查询分身状态。

Meta-Agent

CEO 调度器。动态编排子智能体、维护活跃智能体快照，并在每轮对话中注入记忆召回。由 agenticx/runtime/prompts/meta_agent.py 构建。

Team Manager（`AgentTeamManager`）

控制并发智能体执行、归档快照（_archived_agents）、owner_session_id 会话隔离、avatar_id 绑定以及全局注册表查询。

分身与群聊

Avatar Registry：持久化智能体身份的 CRUD 操作
Group Chat：多种路由策略 — 用户定向（@mention）、Meta 路由、轮询
Group Router：处理 @mention 解析（全名 / slug ID），智能路由至指定成员

第 3 层：核心框架

智能体执行引擎

基于 12-Factor Agents 方法论。think-act 循环处理工具调用、应对上下文溢出并执行自修复；工具调用序列经校验，避免 provider 400 错误。

编排引擎

基于图的工作流，支持条件路由与并行执行；Flow 体系提供装饰器式流水线定义。

工具系统

函数装饰器（@tool）
MCP Hub（多服务器聚合）
Remote Tools v2
OpenAPI toolset
沙箱工具
Skill bundles

记忆系统

分层结构：core → episodic → semantic。与 Mem0 集成以实现长期持久化，支持记忆衰减、混合搜索以及压缩/刷写。

LLM 供应商

统一 provider 接口，覆盖 15+ LLM，具备响应缓存、故障转移路由与 transcript 清洗能力。

第 4 层：平台服务

可观测性

回调体系、实时指标、Prometheus/OpenTelemetry 集成、轨迹分析、span 树、WebSocket 流式输出。

协议

A2A：智能体间通信（client / server / AgentCard / skill-as-tool）
MCP：Model Context Protocol，用于工具与资源访问

安全

泄漏检测、注入检测器、策略引擎、审计日志、沙箱（Docker / Microsandbox / Subprocess）。Studio 路径由 hooks、权限与路径保护组合而成，尚未把每次操作都送进完整的 SafetyLayer。

存储

KV：SQLite、Redis、PostgreSQL、MongoDB、InMemory
Vector：Milvus、Qdrant、Chroma、Faiss、PgVector、Pinecone、Weaviate
Graph：Neo4j、Nebula
Object：S3、GCS、Azure

Studio 默认持久化是 ~/.agenticx 文件树加 SQLite。部分第三方适配器仍是占位，未接到 Studio 主路径。

第 5 层：领域扩展

GUI Agent

桌面自动化框架，采用启发式与 VLM 反思模式进行 A/B/C 结果分类。

知识与 GraphRAG

文档处理流水线 → chunkers / readers / extractors → 图构建（GraphRAG）→ 检索器（vector / BM25 / graph / hybrid）→ reranker。

AgentKit 集成

面向外部智能体框架的可插拔集成层。