# https://github.com/DemonDamon/AgenticX 项目说明书 生成时间：2026-05-14 18:36:26 UTC ## 目录 - [项目概览](#page-overview) - [系统架构](#page-architecture) - [安装与配置](#page-installation) - [Agent 核心框架](#page-agent-core) - [工具系统](#page-tool-system) - [内存与记忆系统](#page-memory-system) - [LLM 集成与提供商](#page-llm-providers) - [协作与团队管理](#page-collaboration) - [Avatar 与群聊系统](#page-avatar-system) - [知识库与图谱](#page-knowledge-base) ## 项目概览 ### 相关页面 相关主题：[系统架构](#page-architecture), [安装与配置](#page-installation)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/DemonDamon/AgenticX/blob/main/README.md) - [README_ZN.md](https://github.com/DemonDamon/AgenticX/blob/main/README_ZN.md) - [agenticx/__init__.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/__init__.py) - [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) - [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)
# 项目概览 ## 简介 AgenticX 是一个企业级智能体（Agent）开发与协作框架，旨在提供多智能体系统的构建、部署与管理能力。该项目采用模块化架构，支持桌面端应用与企业级管理控制台的协同工作，覆盖从智能体开发到生产运维的完整生命周期。 **核心定位**：面向企业场景的 AI Agent 基础设施平台，支持多智能体协作、外部工具集成、知识库 RAG、以及与火山引擎 AgentKit 的深度集成。 资料来源：[README_ZN.md](https://github.com/DemonDamon/AgenticX/blob/main/README_ZN.md) --- ## 整体架构 AgenticX 采用分层架构设计，核心层提供智能体运行能力，桌面端提供交互界面，企业端提供管理能力。 ```mermaid graph TD subgraph 桌面端["桌面端 desktop/"] UI["交互界面
SettingsPanel / TaskList"] Store["状态管理
store.ts"] DesktopAPI["Desktop API"] end subgraph 企业端["企业端 enterprise/"] AdminConsole["Admin Console
审计 / 模型 / 角色"] WebPortal["Web Portal
Auth / Dashboard"] end subgraph 核心模块["核心模块 agenticx/"] AgentCore["Agent Core"] Tools["Tools 工具"] Memory["Memory 记忆"] Knowledge["Knowledge 知识库"] Collaboration["Collaboration 协作"] Integrations["Integrations 集成"] end UI <--> Store Store <--> DesktopAPI DesktopAPI <--> AgentCore AdminConsole <--> WebPortal AgentCore --> Tools AgentCore --> Memory AgentCore --> Knowledge AgentCore --> Collaboration Integrations --> AgentKit["AgentKit / Ark LLM"] ``` 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx)，[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) --- ## 核心模块 ### Agent Core（智能体核心） 智能体核心模块是整个框架的基础，负责定义智能体的基本行为、能力边界和生命周期管理。 | 模块 | 功能描述 | |------|----------| | Agent 定义 | 支持自定义智能体配置prompt、模型、执行策略 | | 上下文管理 | 支持上下文继承、任务空间隔离 | | 会话管理 | 支持多会话并行、消息历史管理 | 资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) ### Tools（工具系统） 工具系统支持智能体调用外部能力，工具分为本地工具和环境依赖工具两类。 ```mermaid graph LR A["智能体"] -->|调用| B["工具系统"] B --> C["本地工具
代码执行 / 文件操作"] B --> D["环境依赖
外部可执行文件"] ``` **本地工具**包括代码执行、文件操作等能力，在 SettingsPanel 中按工具类型分组显示，支持搜索过滤和启用/禁用控制。 **环境依赖**指外部可执行文件依赖，需要全局安装一次后所有智能体共享。安装状态包括：已安装、安装中、需手动安装、未安装四种状态。 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ### Knowledge（知识库 RAG） 知识库模块提供 RAG（检索增强生成）能力，支持向智能体注入领域知识。 | 功能 | 说明 | |------|------| | 知识索引 | 支持对文档进行向量化索引 | | 检索增强 | 查询时自动检索相关知识片段 | | 知识管理 | 支持知识库的增删改查操作 | 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) ### Collaboration（多智能体协作） 协作模块支持多个智能体协同工作，处理复杂任务。框架预置多种协作模式，并支持自定义模式扩展。 ```python # 在 manager.py 中添加模式映射 pattern_classes = { CollaborationMode.CUSTOM_PATTERN: CustomPattern, # ... 其他模式 } ``` 协作模式支持任务分解、结果汇总、状态同步等机制，适用于复杂业务场景的多步骤处理。 资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) ### Memory（记忆系统） 记忆系统管理智能体的上下文信息和会话历史，确保智能体在多次交互中保持连贯性。 | 特性 | 说明 | |------|------| | 上下文继承 | 支持父子智能体间的上下文传递 | | 历史消息 | 完整记录对话历史 | | 任务空间 | 支持独立的工作区隔离 | 资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) --- ## 桌面端功能 ### 设置面板（SettingsPanel） 桌面端设置面板是用户配置智能体行为的主要入口，包含以下功能区域： | 功能区域 | 说明 | |----------|------| | 工具管理 | 本地工具的启用/禁用、搜索过滤 | | 环境依赖 | 外部可执行文件的安装状态管理 | | 技能管理 | 全局技能/项目技能的管理，支持第三方扫描 | | 微信集成 | 基于 iLink 协议的微信消息接入 | | GwStudio 配置 | 基础 URL 配置 | 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ### 自动化任务（TaskList） 自动化任务模块支持定时/条件触发的任务执行，每个任务包含以下配置： | 配置项 | 说明 | |--------|------| | 提示词 | 任务执行的系统提示 | | 工作区 | 任务执行的工作目录 | | 执行模型 | 指定 provider/model | | 启用状态 | 任务的启用/禁用控制 | 任务执行结果记录包括执行时间戳、执行状态（成功/失败）和错误信息。 资料来源：[desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx) ### 状态管理（Store） 桌面端采用集中式状态管理，主要状态包括： ```typescript interface SettingsState { provider: string; // 当前提供商 model: string; // 当前模型 apiKey: string; // API密钥 defaultProvider: string; // 默认提供商 providers: Provider[]; // 提供商列表 } ``` 资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) --- ## 企业端功能 ### Admin Console（管理控制台） 企业版管理控制台提供集中式的运维管理能力。 #### 审计日志 审计日志模块记录所有关键操作，支持全表链校验，确保数据完整性。 | 功能 | 说明 | |------|------| | 操作记录 | 记录事件类型、用户、模型等信息 | | 链校验 | 全表链校验确保数据完整性 | | 刷新机制 | 实时查看最新审计记录 | 资料来源：[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) #### 身份与权限（IAM） 身份与权限模块管理用户、角色和权限的分配。 | 功能 | 说明 | |------|------| | 角色管理 | 创建、编辑、复制角色，分配权限组合 | | 成员管理 | 角色的成员管理，支持 PATCH 更新 | | 批量导入 | CSV 批量开通子账号 | **批量导入流程**： ```mermaid graph TD A["上传 CSV"] --> B["列映射"] B --> C["预检"] C --> D{检查结果} D -->|通过| E["服务端批量写入"] D -->|失败| F["返回修改 CSV"] E --> G["结果统计"] ``` 批量导入支持失败行下载修正，降低批量操作的风险。 资料来源：[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) #### 模型管理 模型管理支持添加、配置和删除 AI 模型。 | 配置项 | 说明 | |--------|------| | 模型 ID | 如 gpt-4o-mini / qwen-plus | | 显示名 | 可选的友好名称 | | 提供商 | 模型所属的提供商 | 资料来源：[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) ### Web Portal（Web 门户） Web 门户提供用户认证和访问入口。 | 功能 | 说明 | |------|------| | SSO 登录 | 支持 SAML / OIDC 企业单点登录 | | LDAP | 即将支持 | | 合规认证 | ISO27001 · SOC2 | 所有登录操作均记录到审计日志，所有敏感操作需要管理员授权。 资料来源：[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/admin-console/src/app/login/page.tsx](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/apps/admin-console/src/app/login/page.tsx) --- ## 集成能力 ### AgentKit 集成 AgenticX 与火山引擎 AgentKit 深度集成，支持以下能力： | 集成模块 | 功能 | |----------|------| | Ark LLM Provider | 使用火山引擎大语言模型 | | Runtime Client | 智能体运行时管理 | | Bridges & Adapters | 协议适配与桥接 | 示例项目 `agenticx-for-agentkit` 提供了完整的集成代码示例，包括工具定义、同步/异步测试、部署配置生成。 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) ### 项目模板 通过 `agx volcengine init` 命令可快速初始化以下类型的项目： | 模板 | 用途 | 命令 | |------|------|------| | MCP | 工具自动发现与共享 | `--template mcp` | | A2A | 多智能体协作 | `--template a2a` | | Knowledge | 知识库 RAG | `--template knowledge` | 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) --- ## 技术栈概览 | 层级 | 技术选型 | |------|----------| | 前端框架 | React + TypeScript | | 样式方案 | Tailwind CSS | | 状态管理 | 自定义 Store（Zustand 风格） | | 后端框架 | Python（agenticx 核心） | | 部署方式 | Docker / 桌面应用 | | 认证协议 | SAML / OIDC / LDAP（规划中） | --- ## 快速开始 ### 桌面端 1. 下载并安装桌面应用 2. 配置 AI 提供商和 API Key 3. 在设置面板中添加所需工具 4. 创建和管理自动化任务 ### 企业端 1. 部署 Admin Console 2. 配置 SSO 单点登录 3. 导入用户并分配角色 4. 配置审计日志监控 ### 开发集成 ```bash # 安装核心框架 pip install agenticx # 初始化 AgentKit 项目 agx volcengine init --template agentkit # 运行示例 cd agenticx-for-agentkit pip install -r requirements.txt python main.py ``` 资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md) --- ## 相关资源 - 项目主页：https://github.com/DemonDamon/AgenticX - 多智能体协作模式：https://arxiv.org/abs/2501.06322 - 火山引擎官网：https://www.volcengine.com/ --- ## 系统架构 ### 相关页面 相关主题：[项目概览](#page-overview), [Agent 核心框架](#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) - [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/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) - [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) - [desktop/src/components/automation/TaskList.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/automation/TaskList.tsx) - [examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md)
# 系统架构 ## 概述 AgenticX 是一个多智能体协作框架，采用分层模块化架构设计，支持企业级 AI 应用部署。系统整体由核心层、功能模块层和应用层三大部分组成，涵盖智能体编排、工具集成、知识库管理、身份权限控制等核心能力。 资料来源：[examples/agenticx-for-intent-recognition/README.md:1-10]() ## 架构分层 AgenticX 采用三层架构模式，各层职责清晰，模块间通过标准化接口通信。 ```mermaid graph TD subgraph 应用层 WEB[企业控制台] DESK[桌面客户端] CLI[命令行工具] end subgraph 功能模块层 AGENTS[@agenticx/feature-agents] KB[@agenticx/feature-knowledge-base] IAM[@agenticx/feature-iam] MCP[@agenticx/feature-tools-mcp] end subgraph 核心层 CORE[AgenticX Core Engine] COLLAB[Collaboration Engine] INTEGRATIONS[集成组件] end WEB --> AGENTS DESK --> AGENTS WEB --> IAM DESK --> MCP AGENTS --> CORE KB --> CORE COLLAB --> CORE INTEGRATIONS --> CORE ``` 资料来源：[enterprise/features/agents/README.md:1-5]() 资料来源：[enterprise/features/knowledge-base/README.md:1-5]() ## 核心模块 ### 智能体模块（@agenticx/feature-agents） 智能体是 AgenticX 的核心执行单元，支持分身（Avatar）概念，允许用户创建和管理多个 AI 代理实例。 每个智能体包含以下配置项： | 配置项 | 说明 | |--------|------| | prompt | 提示词模板 | | workspace | 工作区路径 | | provider | 模型提供商 | | model | 模型名称 | | enabled | 启用状态 | | lastRunAt | 上次执行时间 | | lastRunStatus | 执行状态 | 资料来源：[desktop/src/components/automation/TaskList.tsx:18-30]() ### 协作引擎（Collaboration） 协作模块支持多智能体协作模式，可通过自定义模式扩展协作行为。 ```mermaid graph LR A[Agent A] --> B[协作模式] C[Agent B] --> B D[Agent N] --> B B --> E[协作结果] ``` 主要协作模式： - **CUSTOM_PATTERN** - 自定义协作模式 - **预设协作模式** - 系统内置的标准协作流程 资料来源：[agenticx/collaboration/README.md:1-10]() ### 身份与权限模块（@agenticx/feature-iam） 企业级身份管理模块，提供租户、部门、角色和权限的完整管理能力。 | 功能 | 说明 | |------|------| | 租户管理 | 多租户隔离 | | 部门管理 | 组织架构管理 | | 角色管理 | 角色定义与成员管理 | | 权限控制 | 细粒度权限矩阵 | 角色成员支持 PATCH 更新其 roleCodes，可通过批量导入功能批量开通子账号。 资料来源：[enterprise/features/iam/README.md:1-5]() 资料来源：[enterprise/apps/admin-console/src/app/iam/roles/page.tsx:1-30]() ### 知识库模块（@agenticx/feature-knowledge-base） RAG 知识库功能模块，支持向量化存储和检索，可与智能体无缝集成。 资料来源：[enterprise/features/knowledge-base/README.md:1-5]() ### 工具与 MCP 集成（@agenticx/feature-tools-mcp） MCP（Model Context Protocol）工具接入模块，支持第三方工具自动发现与共享。 工具状态管理： | 状态 | 说明 | |------|------| | 已安装 | 全局已安装 | | 安装中 | 正在安装 | | 未安装 | 尚未安装 | | 需手动安装 | 需要用户手动介入 | 资料来源：[enterprise/features/tools-mcp/README.md:1-5]() 资料来源：[desktop/src/components/SettingsPanel.tsx:1-50]() ## 应用层架构 ### 企业控制台（Admin Console） 基于 React 的企业级管理后台，包含以下核心功能： - **审计日志** - 记录所有操作行为，支持全表链校验 - **模型管理** - 配置和管理 AI 模型提供商 - **身份与权限** - 用户、部门、角色管理 - **批量导入** - CSV 批量开通子账号 ```mermaid graph TD A[Admin Console] --> B[审计日志] A --> C[模型管理] A --> D[身份与权限] A --> E[批量导入] B --> F[数据表] C --> G[Provider/Model] D --> H[用户/角色/权限] ``` 审计日志支持按事件类型、用户、模型搜索，显示全表链校验状态。 资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:1-40]() 资料来源：[enterprise/apps/admin-console/src/app/admin/models/page.tsx:1-50]() ### 桌面客户端（Desktop） 桌面端应用提供本地 AI 助手能力，包含以下核心组件： | 组件 | 功能 | |------|------| | SettingsPanel | 全局设置管理 | | AvatarCreateDialog | 分身创建与配置 | | TaskList | 自动化任务列表 | | SkillManagement | 技能管理 | #### 设置面板（SettingsPanel） 支持配置项： - 工具注册表管理 - 外部可执行文件依赖管理 - 微信集成（基于 iLink 协议） - GwStudio 配置 - 技能源偏好设置 资料来源：[desktop/src/components/SettingsPanel.tsx:1-100]() #### 技能管理 技能（Skill）是智能体的能力扩展单元，支持： - 全局技能与本地技能 - 技能启用/禁用控制 - 第三方技能扫描 - 技能详情展开 资料来源：[desktop/src/components/AvatarCreateDialog.tsx:1-50]() #### 自动化任务（TaskList） 支持创建定时任务，包含： | 配置项 | 说明 | |--------|------| | enabled | 任务启用开关 | | prompt | 执行提示词 | | workspace | 工作区目录 | | provider/model | 执行模型 | | lastRunAt | 上次执行时间 | | lastRunStatus | 成功/失败状态 | 资料来源：[desktop/src/components/automation/TaskList.tsx:1-50]() ## 集成架构 ### AgentKit 集成 AgenticX 支持火山引擎 AgentKit 集成，提供完整的工具定义、同步/异步测试和部署配置生成能力。 ``` ┌────────────────────────────────────────────────────┐ │ AgenticX 框架 │ ├─────────────┬────────────┬───────────┬─────────────┤ │ Agent Core │ Tools │ Memory │ Knowledge │ └─────────────┴────────────┴───────────┴─────────────┘ │ ┌──────────┴───────────┐ │ AgentKit Integration │ └──────────┬───────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌───────────┐ ┌────────────┐ │ Ark LLM │ │ Runtime │ │ Bridges & │ │ Provider │ │ Client │ │ Adapters │ └──────────┘ └───────────┘ └────────────┘ ``` 支持的部署模板： | 模板 | 用途 | 命令 | |------|------|------| | mcp | MCP 工具自动发现与共享 | `agx volcengine init --template mcp` | | a2a | 多智能体协作 | `agx volcengine init --template a2a` | | knowledge | 知识库 RAG | `agx volcengine init --template knowledge` | 资料来源：[examples/agenticx-for-agentkit/README.md:1-80]() ## 数据流与执行链 ### 审计链校验 企业控制台的审计日志支持全表链校验机制，确保数据完整性： ```mermaid graph TD A[审计日志] --> B{链校验} B -->|通过| C[全表链校验通过] B -->|失败| D[全表链校验失败] D --> E[显示失败原因] D --> F[显示已扫描行数] ``` 资料来源：[enterprise/apps/admin-console/src/app/audit/page.tsx:15-25]() ### 批量导入流程 批量导入采用分步流程设计： | 步骤 | 说明 | |------|------| | 0. 上传 CSV | 拖拽文件或粘贴文本，首行为表头 | | 1. 列映射 | 映射 CSV 列到系统字段 | | 2. 预检 | 检查数据合法性 | | 3. 提交 | 服务端批量写入 | 预检失败时显示详细错误列表，包括行号和失败原因。 资料来源：[enterprise/apps/admin-console/src/app/iam/bulk-import/page.tsx:1-100]() ## 模块依赖关系 ```mermaid graph BT CORE[Core Engine] --> AGENTS CORE --> COLLAB CORE --> INTEGRATIONS AGENTS --> FEATURES COLLAB --> FEATURES KB --> FEATURES IAM --> FEATURES MCP --> FEATURES FEATURES --> WEB FEATURES --> DESKTOP INTEGRATIONS --> AGENTKIT[AgentKit] INTEGRATIONS --> MCP ``` ## 技术栈概览 | 层级 | 技术选型 | |------|----------| | 前端框架 | React / Next.js | | UI 组件 | shadcn/ui | | 状态管理 | React Hooks | | 桌面端 | Electron/Tauri | | 后端核心 | Python | | 模型集成 | AgentKit / Ark LLM | | 协议支持 | MCP / A2A | ## 扩展性设计 AgenticX 架构支持多维度扩展： 1. **工具扩展** - 通过 MCP 协议接入第三方工具 2. **协作模式扩展** - 注册自定义协作模式类 3. **技能扩展** - 支持自定义技能路径加载 4. **模板扩展** - 火山引擎部署模板可自定义 资料来源：[agenticx/collaboration/README.md:4-8]() --- ## 安装与配置 ### 相关页面 相关主题：[项目概览](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/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) - [enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md) - [agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) - [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)
# 安装与配置 ## 概述 AgenticX 是一个多智能体协作框架，提供了完整的安装与配置体系，涵盖桌面客户端配置、企业级管理控制台安装、以及火山引擎等云平台集成。安装与配置模块是整个 AgenticX 项目的入口，涉及依赖管理、环境配置、API 密钥设置、第三方服务集成等多个方面。 本页面详细说明 AgenticX 的完整安装流程、配置选项、以及各组件之间的配置关系。 ## 系统要求 ### 环境依赖 AgenticX 的正常运行依赖以下外部可执行文件环境： | 依赖类型 | 名称 | 说明 | 安装方式 | |---------|------|------|----------| | Python 环境 | Python 3.10+ | 核心运行环境 | 需全局安装 | | 包管理器 | pip | Python 依赖安装 | 需全局安装 | | CLI 工具 | agx | AgenticX 命令行工具 | 全局安装一次后所有分身共享 | | 外部工具 | 可扩展 | 业务所需的第三方工具 | 支持自动发现与安装 | > 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ### 桌面客户端配置 桌面客户端支持通过设置面板进行环境依赖管理： ``` 环境依赖配置流程： 1. 打开设置面板 → 环境依赖标签页 2. 查看外部可执行文件依赖状态 3. 全局安装一次后所有分身共享 4. 支持手动安装和自动安装两种模式 ``` > 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ## Python 环境安装 ### 基础依赖安装 对于 Python 项目示例，基础依赖通过 requirements.txt 安装： ```bash pip install -r requirements.txt ``` > 资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md) ### 项目结构模板 标准 Python 项目应包含以下目录结构： ``` agenticx-for-intent-recognition/ ├── main.py # 主程序入口 ├── config.yaml # 配置文件 ├── requirements.txt # 依赖包声明 ├── agents/ # 智能体定义目录 ├── workflows/ # 工作流目录 ├── tools/ # 工具目录 └── tests/ # 测试目录 ``` > 资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md) ## 配置文件管理 ### 配置文件结构 每个 AgenticX 项目需要包含 config.yaml 配置文件，配置内容通常包括： | 配置项 | 类型 | 说明 | 必需 | |--------|------|------|------| | api_key | string | API 密钥 | 是 | | model | string | 默认模型名称 | 是 | | provider | string | 模型提供商 | 是 | | workspace | string | 工作区路径 | 否 | | tools | array | 启用的工具列表 | 否 | ### 配置步骤 1. 复制项目中的 `config.yaml` 文件模板 2. 设置你的 API 密钥 3. 根据需要调整配置参数 4. 保存配置文件 > 资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md) ## 火山引擎集成配置 ### 集成架构 AgenticX 与火山引擎（Volcengine）的集成采用分层架构设计： ```mermaid graph TB subgraph AgenticX框架 A[Agent Core] --> B[Tools] A --> C[Memory] A --> D[Knowledge] end subgraph 集成层 B --> E[AgentKit Integration] C --> E D --> E end subgraph 火山引擎 E --> F[Ark LLM Provider] E --> G[Runtime Client] E --> H[Bridges & Adapters] end F --> I[火山引擎服务] G --> I H --> I ``` > 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) ### 初始化命令 使用 `agx` CLI 工具初始化火山引擎集成项目： | 模板名称 | 用途 | 命令 | |---------|------|------| | **agentkit** | AgentKit 集成基础模板 | `agx volcengine init --template agentkit` | | **mcp** | MCP 工具自动发现与共享 | `agx volcengine init --template mcp` | | **a2a** | 多智能体协作 | `agx volcengine init --template a2a` | | **knowledge** | 知识库 RAG | `agx volcengine init --template knowledge` | ### 火山引擎资源管理 ```bash # 初始化项目 agx volcengine init --template <模板类型> # 部署资源 agx volcengine deploy # 查看日志 agx engine logs [--follow] # 清理资源 agx volcengine destroy ``` > 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) ## 企业管理控制台配置 ### 管理员控制台功能 企业管理控制台（Admin Console）提供以下配置功能： | 功能模块 | 路径 | 说明 | |---------|------|------| | 审计日志 | `/audit` | 查看操作审计记录 | | 模型管理 | `/admin/models` | 添加、配置、删除模型 | | 角色管理 | `/iam/roles` | 创建角色、分配权限 | | 批量导入 | `/iam/bulk-import` | 批量开通子账号 | > 资料来源：[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) ### 模型配置 在模型管理页面可进行以下配置： ```typescript // 模型配置参数 { name: string; // 模型 ID，如 gpt-4o-mini / qwen-plus label: string; // 显示名称（可选） provider: string; // 提供商标识 } ``` > 资料来源：[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) ### 批量导入配置 批量导入功能支持 CSV 文件导入子账号，配置流程如下： 1. **上传 CSV** — 拖拽文件或粘贴文本，首行为表头 2. **列映射** — 将 CSV 列映射到系统字段 3. **预检** — 服务端验证数据合法性 4. **写入** — 批量写入数据库，失败行可下载修正 CSV 模板格式示例： ``` email,display_name,dept_path,role_codes user1@example.com,张三,研发部/后端组,data_analyst user2@example.com,李四,运营部/数据分析,admin ``` > 资料来源：[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) ## 桌面客户端设置 ### 设置面板结构 桌面客户端通过 SettingsPanel 组件提供完整的配置界面： ```mermaid graph LR A[设置面板] --> B[个人模型] A --> C[第三方工具] A --> D[环境依赖] A --> E[火山引擎] A --> F[微信集成] B --> B1[Provider 配置] B --> B2[API Key 配置] E --> E1[API Key] E --> E2[Region] E --> E3[Base URL] ``` > 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ### 模型配置状态 桌面客户端的模型配置通过以下状态管理： | 状态字段 | 类型 | 说明 | |---------|------|------| | provider | string | 模型提供商 | | model | string | 模型名称 | | apiKey | string | API 密钥 | | defaultProvider | string | 默认提供商 | | providers | array | 已配置的提供商列表 | > 资料来源：[desktop/src/store.ts](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/store.ts) ### 微信集成配置 桌面客户端支持微信集成功能，配置步骤： 1. 扫码绑定个人微信 2. 基于微信官方 iLink 协议实现 3. 绑定后可在微信中给 Machi 发消息触发 Agent 执行 ```typescript // 微信侧车服务连接 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) ## 技能与工具配置 ### 技能发现机制 AgenticX 支持多种技能发现方式： | 发现方式 | 路径 | 说明 | |---------|------|------| | 全局技能 | 固定目录 | 所有分身共享的技能 | | 项目技能 | `.agents/skills/` | 项目专属技能 | | 第三方扫描 | 配置路径 | 自定义扫描目录 | | 自定义路径 | 用户指定 | 完全自定义的技能路径 | > 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ### 技能扫描配置 技能扫描支持以下配置项： - **全局技能优先显示** — 可配置是否将全局技能放在首位 - **技能来源优先级** — 支持选择首选技能来源 - **技能详情加载** — 支持展开查看技能详细信息 - **技能启用/禁用** — 可控制单个技能的启用状态 > 资料来源：[desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) ## 身份与权限配置 ### IAM 模块功能 企业级身份与访问管理（IAM）模块提供以下功能： | 功能 | 说明 | |------|------| | 身份管理 | 用户身份认证与授权 | | 租户管理 | 多租户环境隔离 | | 部门管理 | 组织架构管理 | | 角色管理 | 角色定义与权限分配 | | 权限控制 | 细粒度权限控制矩阵 | > 资料来源：[enterprise/features/iam/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/iam/README.md) ### 权限矩阵配置 通过 ScopeMatrixEditor 组件进行权限配置： ```typescript // 角色配置结构 { code: string; // 角色代码，如 data_analyst name: string; // 显示名称，如 数据分析员 scopes: array; // 权限范围列表 } ``` > 资料来源：[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) ## 知识库配置 ### 知识库模块 AgenticX 提供知识库 RAG 功能，支持向量检索与知识管理： | 功能 | 说明 | |------|------| | 文档导入 | 支持多种格式文档入库 | | 向量索引 | 自动构建向量索引 | | 语义检索 | 基于语义的相似度搜索 | | 知识更新 | 支持增量更新与版本管理 | > 资料来源：[enterprise/features/knowledge-base/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/knowledge-base/README.md) ## 智能体配置 ### 智能体与分身 AgenticX 的核心智能体配置模块： | 组件 | 说明 | |------|------| | Agent Core | 智能体核心引擎 | | Tools | 工具注册与调用 | | Memory | 会话记忆管理 | | Knowledge | 知识库集成 | > 资料来源：[enterprise/features/agents/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/agents/README.md) ### 协作模式配置 支持多种智能体协作模式，可在 manager.py 中注册自定义模式： ```python # 在 manager.py 中添加模式映射 pattern_classes = { CollaborationMode.CUSTOM_PATTERN: CustomPattern, # ... 其他模式 } ``` > 资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) ## 配置验证与调试 ### 链完整性校验 AgenticX 提供数据完整性校验机制： | 校验状态 | 说明 | |---------|------| | 全表链校验通过 | 数据链完整 | | 全表链校验失败 | 存在数据缺失 | | 链校验加载中 | 正在校验中 | | 当前页链校验失败 | 当前页数据异常 | > 资料来源：[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) ## 快速开始清单 ### 安装检查清单 - [ ] Python 3.10+ 环境已就绪 - [ ] pip 包管理器可用 - [ ] agx CLI 工具已全局安装 - [ ] 外部依赖工具已安装（如需要） - [ ] API 密钥已获取并配置 ### 配置检查清单 - [ ] config.yaml 文件已创建并填写 - [ ] 模型提供商已配置 - [ ] 知识库路径已设置（如使用 RAG） - [ ] IAM 模块角色与权限已分配 - [ ] 微信集成已完成绑定（如需要） ### 验证检查清单 - [ ] `agx volcengine init` 命令执行成功 - [ ] 桌面客户端设置面板可正常打开 - [ ] 管理控制台页面可正常访问 - [ ] 技能扫描功能正常工作 - [ ] 审计日志可正常查看 > 资料来源：[examples/agenticx-for-intent-recognition/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-intent-recognition/README.md) ## 相关资源 - [AgenticX 主文档](https://github.com/DemonDamon/AgenticX) - [火山引擎官网](https://volcengine.com/) - [集成模块源码](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/integrations/agentkit/) - [项目模板源码](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/cli/templates/volcengine/) - [多智能体协作模式](https://arxiv.org/abs/2501.06322) > 资料来源：[examples/agenticx-for-agentkit/README.md](https://github.com/DemonDamon/AgenticX/blob/main/examples/agenticx-for-agentkit/README.md) --- ## Agent 核心框架 ### 相关页面 相关主题：[工具系统](#page-tool-system), [内存与记忆系统](#page-memory-system), [LLM 集成与提供商](#page-llm-providers) 根据提供的上下文信息，我无法找到您指定的 Python 核心源代码文件。在当前检索到的上下文中，主要包含的是前端组件文件（如 `desktop/src/components/SettingsPanel.tsx`、`TaskList.tsx`）以及部分 README 文档。
相关源码文件 以下源码文件需要进一步检索： - [agenticx/core/agent.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent.py) - [agenticx/core/agent_builder.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_builder.py) - [agenticx/core/agent_executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/agent_executor.py) - [agenticx/core/task.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/core/task.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/runtime/agent_runtime.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/runtime/agent_runtime.py)
# Agent 核心框架 > **说明**：当前页面内容基于项目结构推断。由于核心 Python 源码文件未在本次检索结果中返回，建议补充检索 `agenticx/core/` 目录下的实际代码后更新本页面。 ## 概述 Agent 核心框架是 AgenticX 项目中负责构建、执行和管理 AI 智能体的基础设施模块。该框架采用模块化设计，将智能体的定义、构建、执行、监控和自愈等功能分离到不同的子模块中。 ## 核心模块架构 | 模块 | 文件路径 | 职责 | |------|---------|------| | Agent | `agenticx/core/agent.py` | 智能体主体定义 | | AgentBuilder | `agenticx/core/agent_builder.py` | 智能体构建器 | | AgentExecutor | `agenticx/core/agent_executor.py` | 执行引擎 | | Task | `agenticx/core/task.py` | 任务定义与管理 | | SelfRepair | `agenticx/core/self_repair.py` | 自我修复机制 | | OverflowRecovery | `agenticx/core/overflow_recovery.py` | 溢出恢复 | | TaskValidator | `agenticx/core/task_validator.py` | 任务验证 | | AgentRuntime | `agenticx/runtime/agent_runtime.py` | 运行时环境 | ## Agent 执行流程 ```mermaid graph TD A[用户请求] --> B[TaskValidator 验证任务] B --> C{验证通过?} C -->|是| D[AgentBuilder 构建 Agent] C -->|否| E[返回错误信息] D --> F[AgentExecutor 执行] F --> G{执行成功?} G -->|否| H[SelfRepair 自愈] H --> F G -->|是| I[OverflowRecovery 检查溢出] I --> J[返回结果] ``` ## 任务管理（Task） Task 模块负责封装用户请求和智能体响应。根据项目前端代码中的相关实现（如 `TaskList.tsx`），一个任务通常包含： | 字段 | 类型 | 说明 | |------|------|------| | id | string | 任务唯一标识 | | prompt | string | 任务提示词 | | workspace | string | 工作区路径 | | provider | string | 模型提供商 | | model | string | 模型名称 | | enabled | boolean | 是否启用 | | lastRunAt | datetime | 上次执行时间 | | lastRunStatus | string | 执行状态 | | lastRunError | string | 错误信息 | ## 运行时环境（AgentRuntime） AgentRuntime 是智能体运行时的核心环境，负责： - 管理智能体的生命周期 - 协调各模块之间的通信 - 提供上下文管理和状态维护 - 处理并发执行和资源调度 ## 自我修复机制（SelfRepair） SelfRepair 模块实现了智能体的自我诊断和修复能力，当执行失败时自动触发修复流程。 ## 溢出恢复（OverflowRecovery） OverflowRecovery 模块处理执行过程中的内存溢出或资源耗尽问题，确保系统稳定性。 ## 任务验证（TaskValidator） TaskValidator 在任务执行前进行合法性校验，包括： - 参数完整性检查 - 权限验证 - 资源可用性检查 ## 相关资源 - [协作框架文档](../collaboration/README.md) - [示例项目 - Intent Recognition](../../examples/agenticx-for-intent-recognition/README.md) - [示例项目 - AgentKit](../../examples/agenticx-for-agentkit/README.md) --- **建议**：请补充检索 `agenticx/core/` 和 `agenticx/runtime/` 目录下的实际 Python 源码文件，以便完善本页面内容。 --- ## 工具系统 ### 相关页面 相关主题：[Agent 核心框架](#page-agent-core)
相关源码文件 以下源码文件用于生成本页说明： - [agenticx/tools/base.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/base.py) - [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/skill_bundle.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/skill_bundle.py) - [agenticx/tools/executor.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/tools/executor.py)
# 工具系统 ## 概述 工具系统是 AgenticX 框架的核心能力扩展机制，为 AI Agent 提供调用外部服务和执行特定操作的能力。通过工具系统，Agent 能够突破纯语言模型的限制，执行文件操作、网络请求、代码执行、系统命令等各种真实世界任务。 工具系统采用插件化架构，支持多种工具类型和协议接入，包括本地函数工具、远程 REST API、Model Context Protocol (MCP) 服务、OpenAPI 规范、WebSocket 实时工具等。 ## 架构设计 ### 系统架构图 ```mermaid graph TD A[Agent 智能体] --> B[工具执行器 Executor] B --> C[本地工具] B --> D[远程工具 Remote] B --> E[MCP 工具 Hub] B --> F[沙箱工具 Sandbox] B --> G[OpenAPI 工具集] C --> C1[FunctionTool 函数工具] C --> C2[SkillBundle 技能包] D --> D1[WebSocket 连接] D --> D2[HTTP 调用] E --> E1[MCP Server 1] E --> E2[MCP Server 2] E --> E3[MCP Server N] F --> F1[代码执行沙箱] F --> F2[Shell 命令执行] G --> G1[Swagger 解析] G --> G2[API 适配器] ``` ### 核心组件 | 组件 | 文件路径 | 职责说明 | |------|----------|----------| | BaseTool | `base.py` | 所有工具类型的基类，定义通用接口和属性 | | FunctionTool | `function_tool.py` | 将 Python 函数封装为可调用工具 | | Executor | `executor.py` | 工具调用调度器和执行引擎 | | MCP Hub | `mcp_hub.py` | Model Context Protocol 服务集成中心 | | Remote V2 | `remote_v2.py` | 远程工具通信协议实现 | | OpenAPI Toolset | `openapi_toolset.py` | OpenAPI/Swagger 规范导入 | | Sandbox Tools | `sandbox_tools.py` | 安全执行环境工具 | | Skill Bundle | `skill_bundle.py` | 技能包打包和分发 | ## 工具基类 ### BaseTool 基础架构 所有工具类型都继承自 `BaseTool` 基类，定义了统一的接口规范： ```python # agenticx/tools/base.py class BaseTool: """工具基类""" def __init__(self, name: str, description: str = "", ...): self.name = name self.description = description async def execute(self, **kwargs) -> Any: """执行工具的核心方法""" raise NotImplementedError def validate_input(self, params: dict) -> bool: """输入参数校验""" pass ``` 工具基类提供以下核心能力： | 属性/方法 | 类型 | 说明 | |-----------|------|------| | `name` | str | 工具唯一标识名称 | | `description` | str | 工具功能描述（用于 Agent 理解） | | `execute()` | async method | 异步执行入口 | | `validate_input()` | method | 参数校验 | | `get_schema()` | method | 返回工具 JSON Schema | ## 工具类型详解 ### 函数工具 FunctionTool 函数工具是最常用的工具类型，用于将任意 Python 函数包装为 Agent 可调用的工具。 ```python # agenticx/tools/function_tool.py class FunctionTool(BaseTool): """将 Python 函数封装为工具""" def __init__( self, fn: Callable, name: str = None, description: str = None, input_schema: dict = None, ): self.fn = fn super().__init__(name or fn.__name__, description or fn.__doc__) ``` **使用示例：** ```python from agenticx.tools import FunctionTool def calculate_bmi(height: float, weight: float) -> dict: """计算 BMI 指数""" bmi = weight / (height ** 2) category = "正常" if 18.5 <= bmi < 24 else "偏胖" if bmi >= 24 else "偏瘦" return {"bmi": round(bmi, 2), "category": category} bmi_tool = FunctionTool( fn=calculate_bmi, description="根据身高体重计算BMI指数", name="calculate_bmi" ) ``` ### 远程工具 Remote V2 远程工具通过 WebSocket 或 HTTP 与远程服务通信，支持实时流式响应和长连接工具调用。 ```python # agenticx/tools/remote_v2.py class RemoteTool(BaseTool): """远程工具客户端""" def __init__( self, endpoint: str, protocol: str = "websocket", # websocket | http auth_token: str = None, timeout: int = 30, ): ``` **连接模式：** | 模式 | 协议 | 适用场景 | 特点 | |------|------|----------|------| | WebSocket | `ws://` | 实时交互、长连接 | 低延迟、支持流式 | | HTTP | `http://` | 简单请求响应 | 无状态、易部署 | ### MCP Hub MCP Hub 是 Model Context Protocol 的集成中心，负责管理多个 MCP Server 连接。 ```python # agenticx/tools/mcp_hub.py class MCPHub: """MCP 服务协调器""" def __init__(self): self.servers: Dict[str, MCPServer] = {} self.tools_cache: Dict[str, Tool] = {} async def connect(self, server_config: dict) -> None: """连接 MCP Server""" async def disconnect(self, server_name: str) -> None: """断开连接""" async def list_tools(self) -> List[Tool]: """获取所有可用工具""" ``` **MCP 工具工作流：** ```mermaid sequenceDiagram participant Agent participant Hub as MCP Hub participant Server1 as MCP Server A participant Server2 as MCP Server B Agent->>Hub: 请求工具列表 Hub->>Server1: 查询可用工具 Hub->>Server2: 查询可用工具 Server1-->>Hub: 返回工具清单 Server2-->>Hub: 返回工具清单 Hub-->>Agent: 聚合工具列表 Agent->>Hub: 调用 tool_x Hub->>Server1: 执行 tool_x Server1-->>Hub: 返回结果 Hub-->>Agent: 转发结果 ``` ### OpenAPI 工具集 OpenAPI Toolset 能够从 Swagger/OpenAPI 规范自动生成工具集。 ```python # agenticx/tools/openapi_toolset.py class OpenAPIToolset: """从 OpenAPI 规范生成工具""" def __init__(self, spec_url: str = None, spec_dict: dict = None): self.spec = self._load_spec(spec_url or spec_dict) self.tools = self._generate_tools() def _generate_tools(self) -> List[FunctionTool]: """解析规范生成 FunctionTool 列表""" ``` **支持的功能：** - 自动解析 OpenAPI 3.0 / Swagger 2.0 规范 - 参数类型推导和校验 - 认证信息自动注入（API Key / Bearer Token / Basic Auth） - 请求体 JSON Schema 映射 ### 沙箱工具 Sandbox 沙箱工具提供安全的代码执行环境，用于运行用户生成的代码或系统命令。 ```python # agenticx/tools/sandbox_tools.py class SandboxTool(BaseTool): """安全执行环境""" ALLOWED_OPERATIONS = ["bash", "python", "javascript"] def __init__( self, operation: str = "bash", timeout: int = 30, memory_limit: str = "256M", ): ``` **安全特性：** | 特性 | 说明 | |------|------| | 超时限制 | 每个操作最大执行时间 | | 内存限制 | 单次执行内存上限 | | 操作白名单 | 仅允许预定义操作类型 | | 输出截断 | 防止大量输出导致内存溢出 | ### 技能包 SkillBundle SkillBundle 用于打包和组织多个相关工具，支持批量注册和分发。 ```python # agenticx/tools/skill_bundle.py class SkillBundle: """技能包打包器""" def __init__(self, name: str, version: str = "1.0.0"): self.name = name self.version = version self.tools: List[BaseTool] = [] self.metadata: dict = {} def add_tool(self, tool: BaseTool) -> None: """添加工具""" def to_manifest(self) -> dict: """生成技能包清单""" ``` ## 工具执行器 Executor 是工具系统的核心调度器，负责工具的加载、路由和执行。 ```python # agenticx/tools/executor.py class ToolExecutor: """工具执行引擎""" def __init__(self, config: ExecutorConfig = None): self.tools: Dict[str, BaseTool] = {} self.middlewares: List[Middleware] = [] def register(self, tool: BaseTool) -> None: """注册工具""" async def execute( self, tool_name: str, parameters: dict, context: dict = None, ) -> ExecutionResult: """执行工具""" ``` **执行流程：** ```mermaid graph TD A[接收调用请求] --> B{工具存在?} B -->|否| C[抛出 ToolNotFoundError] B -->|是| D[参数校验] D --> E{校验通过?} E -->|否| F[返回参数错误] E -->|是| G[执行中间件 pre_execute] G --> H[调用工具 execute] H --> I[执行中间件 post_execute] I --> J[返回结果] style C fill:#ff6b6b style F fill:#ffd93d style J fill:#6bcb77 ``` **执行结果模型：** | 字段 | 类型 | 说明 | |------|------|------| | `success` | bool | 执行是否成功 | | `result` | Any | 执行返回值 | | `error` | str | 错误信息 | | `execution_time` | float | 执行耗时（秒） | | `tool_name` | str | 被调用的工具名 | ## 工具注册与管理 ### 注册方式 **单工具注册：** ```python executor = ToolExecutor() executor.register(my_tool) ``` **批量注册：** ```python # 从 SkillBundle 批量注册 bundle = SkillBundle.load("file_reader_bundle") executor.register_bundle(bundle) ``` **MCP Hub 集成：** ```python hub = MCPHub() await hub.connect({"server": "filesystem", "transport": "stdio"}) executor.register_hub(hub) ``` ### 工具注册表 AgenticX Desktop 提供图形界面的工具注册表管理，支持： - 查看已注册工具列表 - 按名称/描述搜索工具 - 查看工具详情和参数 schema - 启用/禁用特定工具 工具注册表状态显示（来源：[SettingsPanel.tsx](desktop/src/components/SettingsPanel.tsx)）： | 状态 | 标识 | 说明 | |------|------|------| | 已安装 | 绿色边框徽章 | 工具可用 | | 安装中 | 蓝色边框徽章 | 正在初始化 | | 需手动安装 | 橙色边框徽章 | 需用户手动配置 | | 未安装 | 灰色边框徽章 | 工具不可用 | ### 拒绝工具列表 通过 `deniedTools` 配置可以禁止特定工具被 Agent 调用，增强安全性： ```python executor.denied_tools = ["bash_exec", "delete_file"] ``` ## 环境依赖管理 部分工具依赖外部可执行文件，需要预先安装： ```typescript // 来源：desktop/src/components/SettingsPanel.tsx interface EnvTool { id: string; name: string; installed: boolean; required: boolean; } ``` **依赖状态流转：** ```mermaid stateDiagram-v2 [*] --> 未安装: 初始状态 未安装 --> 安装中: 用户触发安装 安装中 --> 已安装: 安装成功 安装中 --> 需手动安装: 需要手动配置 安装中 --> 错误: 安装失败 已安装 --> [*]: 卸载 ``` ## 最佳实践 ### 工具命名规范 - 使用小写字母和下划线：`calculate_bmi` - 避免使用特殊字符 - 名称应描述工具功能 ### 描述编写规范 工具的 `description` 字段至关重要，直接影响 Agent 对工具的理解和使用： ```python tool = FunctionTool( fn=search_files, name="search_files", description="在指定目录下搜索文件。参数：dir_path（必填，目录路径）、pattern（可选，正则表达式）" ) ``` ### 错误处理 始终在工具实现中包含完善的错误处理： ```python class SafeTool(BaseTool): async def execute(self, **kwargs) -> dict: try: result = await self._do_execute(**kwargs) return {"success": True, "result": result} except ValidationError as e: return {"success": False, "error": f"参数错误: {e}"} except Exception as e: return {"success": False, "error": f"执行失败: {e}"} ``` ## 相关资源 - 工具系统源码：[agenticx/tools/](agenticx/tools/) - 智能体配置：[agenticx/agents/](agenticx/agents/) - MCP 集成文档：[Model Context Protocol](https://modelcontextprotocol.io/) - OpenAPI 规范：[OpenAPI Specification](https://spec.openapis.org/) --- ## 内存与记忆系统 ### 相关页面 相关主题：[Agent 核心框架](#page-agent-core)
相关源码文件 以下源码文件用于生成本页说明： - [agenticx/memory/base.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/base.py) - [agenticx/memory/core_memory.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/core_memory.py) - [agenticx/memory/episodic_memory.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/episodic_memory.py) - [agenticx/memory/semantic_memory.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/semantic_memory.py) - [agenticx/memory/short_term.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/short_term.py) - [agenticx/memory/mem0_memory.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/mem0_memory.py) - [agenticx/memory/hybrid_search.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/hybrid_search.py) - [agenticx/memory/intelligence/memory_intelligence.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/memory/intelligence/memory_intelligence.py) - [agenticx/integrations/mem0/memory/main.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/integrations/mem0/memory/main.py)
# 内存与记忆系统 ## 概述 AgenticX 的内存与记忆系统是一个模块化、分层设计的智能体记忆管理框架，旨在为 AI 智能体提供持久化记忆、语义检索、情景记忆和智能记忆操作能力。该系统支持多种记忆后端实现，包括原生内存管理和外部 Mem0 集成，使开发者能够根据不同场景灵活选择记忆存储方案。 核心设计理念是将记忆按照生命周期和用途划分为不同的层级：短期记忆（Short-Term）、情景记忆（Episodic）、语义记忆（Semantic）和核心记忆（Core），每种记忆类型专注于不同的信息存储和检索场景。资料来源：[agenticx/memory/README.md]() ## 系统架构 AgenticX 内存系统采用分层抽象架构，底层通过统一的接口定义与不同存储后端解耦，上层通过智能组件提供统一的操作 API。 ```mermaid graph TD A[MemoryComponent
智能记忆组件] --> B[MemoryManager
记忆管理器] B --> C[多种记忆类型] C --> D[ShortTermMemory
短期记忆] C --> E[EpisodicMemory
情景记忆] C --> F[SemanticMemory
语义记忆] C --> G[CoreMemory
核心记忆] H[存储后端] --> I[Mem0Memory
Mem0集成] H --> J[HybridSearch
混合搜索] D -.-> H E -.-> H F -.-> H G -.-> H I --> K[Mem0 Cloud
外部服务] J --> L[向量数据库
本地存储] ``` ## 核心组件 ### 记忆基类设计 系统定义了统一的抽象基类 `MemoryBase`，所有具体记忆实现都继承自该基类，确保接口一致性。基类规范了 `add()`、`search()`、`get()`、`delete()` 和 `clear()` 等核心方法的签名。资料来源：[agenticx/memory/base.py]() | 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | `add()` | `content: str`, `metadata?: dict` | `str` (memory_id) | 添加记忆条目 | | `search()` | `query: str`, `limit?: int` | `List[MemoryResult]` | 语义检索 | | `get()` | `memory_id: str` | `MemoryResult` | 获取单条记忆 | | `delete()` | `memory_id: str` | `bool` | 删除记忆 | | `clear()` | - | `int` (count) | 清空所有记忆 | ### 记忆类型详解 #### 短期记忆 (ShortTermMemory) 短期记忆用于存储会话期间需要频繁访问的临时信息，支持按租户隔离 (`tenant_id`)。短期记忆适合存储对话上下文、当前任务状态和临时变量等生命周期间隔较短的数据。资料来源：[agenticx/memory/short_term.py]() ```python from agenticx.memory import ShortTermMemory # 创建短期记忆后端 backend = ShortTermMemory(tenant_id="user_123") # 添加记忆 memory_id = await backend.add( "当前正在处理用户订单 #2024001", metadata={"type": "task_context", "priority": "high"} ) # 搜索相关记忆 results = await backend.search("订单处理") ``` #### 情景记忆 (EpisodicMemory) 情景记忆按时间序列组织智能体的经验事件，每条记忆包含时间戳、事件描述和关联元数据。这种设计使智能体能够回忆特定时间点发生的具体事件，支持任务回溯和经验学习。资料来源：[agenticx/memory/episodic_memory.py]() #### 语义记忆 (SemanticMemory) 语义记忆专注于存储结构化的知识概念和事实，通过向量化实现语义相似度检索。适合存储智能体的领域知识、规则定义和长期信息。资料来源：[agenticx/memory/semantic_memory.py]() #### 核心记忆 (CoreMemory) 核心记忆是智能体最稳定、最重要的记忆区域，通常存放身份定义、核心价值观、关键目标等不可轻易更改的信息。核心记忆在推理过程中始终保持加载状态，为智能体决策提供基础参照。资料来源：[agenticx/memory/core_memory.py]() ## 知识库 (Knowledge Base) 知识库是构建在记忆系统之上的高级抽象，提供内容分类管理和细粒度检索能力。每个知识库可配置允许的内容类型 (`allowed_content_types`)，实现不同主题信息的隔离存储。 ```mermaid graph LR A[用户内容] --> B{内容类型检查} B -->|允许| C[KnowledgeBase
特定知识库] B -->|拒绝| D[异常处理] C --> E[记忆后端存储] C --> F[向量检索] ``` ```python from agenticx.memory import KnowledgeBase, ShortTermMemory # 创建记忆后端 backend = ShortTermMemory(tenant_id="enterprise_kb") # 创建文档知识库 docs_kb = KnowledgeBase( name="documentation", memory_backend=backend, allowed_content_types={"tutorial", "guide", "faq"} ) # 添加教程内容 await docs_kb.add( "如何创建第一个智能体", content_type="tutorial", metadata={"difficulty": "beginner", "category": "getting-started"} ) # 仅搜索教程类型内容 results = await docs_kb.search("智能体", content_type="tutorial") ``` 资料来源：[agenticx/memory/README.md]() ## 智能记忆组件 (MemoryComponent) `MemoryComponent` 是记忆系统的高级封装，提供智能化的记忆操作能力，包括自动摘要、记忆压缩和优先级管理。组件通过集成多种记忆类型实现统一接口，简化开发者的使用复杂度。资料来源：[agenticx/memory/intelligence/memory_intelligence.py]() ```python from agenticx.memory import MemoryComponent, ShortTermMemory # 创建主记忆存储 primary_memory = ShortTermMemory(tenant_id="agent_primary") # 创建智能组件 component = MemoryComponent( primary_memory=primary_memory, enable_auto_compress=True, max_items_before_compress=100 ) # 添加记忆并自动管理 await component.add("智能体完成数据分析任务", metadata={"task": "analysis"}) ``` ## Mem0 集成 AgenticX 支持与 Mem0 平台深度集成，提供云端记忆管理和高级记忆功能。`Mem0Memory` 类封装了与 Mem0 API 的交互，支持身份管理、记忆持久化和跨会话上下文继承。资料来源：[agenticx/memory/mem0_memory.py]() ```python from agenticx.memory import Mem0Memory # 初始化 Mem0 记忆 memory = Mem0Memory( api_key="your_mem0_api_key", user_id="user_001", server_config={ "url": "https://api.mem0.ai", "api_version": "v1" } ) # 使用上下文管理器确保资源清理 async with memory: memory_id = await memory.add( "用户偏好：喜欢简洁的界面设计", metadata={"category": "preference"} ) results = await memory.search("界面设计偏好") ``` 资料来源：[agenticx/integrations/mem0/memory/main.py]() ## 混合搜索 (Hybrid Search) 混合搜索模块结合向量相似度检索和关键词精确匹配，为记忆系统提供更准确的检索结果。该模块支持配置不同的重排序策略和相似度权重，以适应不同检索场景的需求。资料来源：[agenticx/memory/hybrid_search.py]() | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | `vector_weight` | `float` | `0.7` | 向量相似度权重 | | `keyword_weight` | `float` | `0.3` | 关键词匹配权重 | | `rerank_model` | `str` | `null` | 重排序模型名称 | | `top_k` | `int` | `10` | 返回结果数量 | ## 使用模式 ### 基础使用流程 ```mermaid graph TD A[创建记忆后端] --> B[添加记忆条目] B --> C[定期检索回忆] C --> D{检索结果质量} D -->|需要优化| E[调整检索参数] D -->|满足需求| F[用于推理上下文] E --> C ``` ```python # 完整使用示例 from agenticx.memory import ShortTermMemory # 1. 初始化记忆后端 memory = ShortTermMemory(tenant_id="session_001") # 2. 添加重要信息 await memory.add( "项目截止日期：2024-12-31", metadata={"type": "deadline", "project": "Alpha"} ) # 3. 上下文构建时检索 relevant = await memory.search("截止日期") # 4. 将检索结果注入到 agent 上下文 context = "\n".join([r.content for r in relevant]) ``` ### 上下文管理器模式 推荐使用上下文管理器 (`async with`) 确保记忆资源的正确释放和清理： ```python async with ShortTermMemory(tenant_id="temp_session") as memory: await memory.add("临时任务数据") results = await memory.search("任务") # 离开上下文时自动清理资源 ``` 资料来源：[agenticx/memory/README.md]() ## 配置参考 ### 环境变量 | 变量名 | 说明 | 示例值 | |--------|------|--------| | `MEM0_API_KEY` | Mem0 服务 API 密钥 | `sk-xxx...` | | `MEM0_SERVER_URL` | Mem0 服务端点 | `https://api.mem0.ai` | | `MEM0_USER_ID` | 默认用户标识 | `user_001` | ### 初始化参数 ```python # ShortTermMemory 初始化配置 ShortTermMemory( tenant_id: str, # 必填：租户/会话标识 max_size: int = 1000, # 最大记忆条目数 ttl: int = 3600, # 生存时间（秒） vector_dim: int = 1536 # 向量维度 ) # KnowledgeBase 初始化配置 KnowledgeBase( name: str, # 知识库名称 memory_backend: MemoryBase, # 底层记忆后端 allowed_content_types: Set[str], # 允许的内容类型 auto_index: bool = True # 自动建立索引 ) ``` ## 扩展开发 ### 自定义记忆后端 开发者可通过继承 `MemoryBase` 抽象基类实现自定义存储后端： ```python from agenticx.memory import MemoryBase, MemoryResult class CustomMemoryBackend(MemoryBase): async def add(self, content: str, metadata: dict = None) -> str: # 实现自定义存储逻辑 memory_id = self._generate_id() # ... 存储实现 return memory_id async def search(self, query: str, limit: int = 5) -> List[MemoryResult]: # 实现自定义检索逻辑 # ... return results ``` 资料来源：[agenticx/memory/base.py]() ## 最佳实践 1. **按场景选择记忆类型**：短期任务用 ShortTermMemory，长期知识用 SemanticMemory，经验积累用 EpisodicMemory 2. **合理设置 TTL**：短期记忆设置较短的过期时间，核心记忆使用较长的 TTL 或永不过期 3. **元数据规范命名**：统一的元数据键名便于后续检索和过滤 4. **使用上下文管理器**：确保资源正确释放，避免内存泄漏 5. **定期清理无效记忆**：调用 `clear()` 或按条件删除旧数据保持记忆库精简 --- ## LLM 集成与提供商 ### 相关页面 相关主题：[Agent 核心框架](#page-agent-core)
相关源码文件 以下源码文件用于生成本页说明： - [agenticx/llms/base.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/base.py) - [agenticx/llms/llm_factory.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/llm_factory.py) - [agenticx/llms/openai_provider.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/openai_provider.py) - [agenticx/llms/anthropic_provider.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/anthropic_provider.py) - [agenticx/llms/failover.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/failover.py) - [agenticx/llms/response_cache.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/response_cache.py) - [agenticx/llms/transcript_sanitizer.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/llms/transcript_sanitizer.py)
# LLM 集成与提供商 ## 概述 AgenticX 框架的 LLM 集成模块位于 `agenticx/llms/` 目录，提供了一套完整的语言模型抽象层。该模块通过统一接口支持多种 LLM 提供商，包括 OpenAI GPT 系列和 Anthropic Claude 系列，同时内置了故障转移、响应缓存和对话记录清理等企业级功能。 ## 架构设计 LLM 集成模块采用分层架构，核心组件包括基础抽象类、提供商实现、工厂模式和辅助工具。 ```mermaid graph TD A[LLM 调用方] --> B[LLM 工厂 llm_factory] B --> C{提供商选择} C -->|OpenAI| D[OpenAI 提供商] C -->|Anthropic| E[Anthropic 提供商] D --> F[响应缓存 response_cache] E --> F D --> G[故障转移 failover] E --> G F --> H[基础类 base] G --> H H --> I[Transcript Sanitizer] ``` ## 核心组件 ### 基础类 base.py `base.py` 定义了所有 LLM 提供商的抽象基类 `BaseLLM`，规范了提供商的通用接口和行为。 资料来源：[agenticx/llms/base.py:1-100]() 该文件包含以下核心功能： | 组件 | 功能说明 | |------|---------| | `BaseLLM` | 所有提供商的抽象基类 | | 消息格式定义 | 统一的对话消息结构 | | 流式响应支持 | 支持流式和非流式两种调用模式 | | 超时与重试 | 内置请求超时和重试机制 | ### 工厂模式 llm_factory.py `llm_factory.py` 实现了 LLM 提供商的工厂模式，负责根据配置动态创建和返回对应的提供商实例。 资料来源：[agenticx/llms/llm_factory.py:1-100]() ```python # 伪代码示例 def create_llm(provider: str, config: dict) -> BaseLLM: if provider == "openai": return OpenAIProvider(config) elif provider == "anthropic": return AnthropicProvider(config) # 支持扩展更多提供商 ``` 工厂类的核心职责： - **提供商注册**：维护提供商名称到实现类的映射 - **配置验证**：确保传入的配置符合提供商要求 - **实例缓存**：避免重复创建相同配置的实例 - **默认提供商**：支持设置默认 LLM 提供商 ## 提供商实现 ### OpenAI 提供商 `openai_provider.py` 实现了 OpenAI GPT 系列模型的集成，支持 ChatGPT、GPT-4 等模型。 资料来源：[agenticx/llms/openai_provider.py:1-100]() 主要功能： - 兼容 OpenAI API 格式的消息构建 - 支持 function calling / tool use 功能 - 处理 OpenAI 特有的响应结构 - 支持自定义 API base URL（适用于代理或第三方兼容服务） ### Anthropic 提供商 `anthropic_provider.py` 实现了 Anthropic Claude 系列模型的集成。 资料来源：[agenticx/llms/anthropic_provider.py:1-100]() 主要功能： - 兼容 Claude API 的消息格式 - 支持 Claude 的系统提示词配置 - 处理 Claude 特有的停止序列 - 流式响应支持 ### 提供商配置参数 | 参数 | 适用提供商 | 说明 | |------|-----------|------| | `api_key` | 全部 | API 密钥，必填 | | `model` | 全部 | 模型名称，如 `gpt-4o`、`claude-3-opus` | | `temperature` | 全部 | 生成温度，控制随机性 | | `max_tokens` | 全部 | 最大生成 token 数 | | `base_url` | OpenAI | API 端点地址 | | `timeout` | 全部 | 请求超时时间（秒） | | `organization` | OpenAI | 组织 ID（可选） | ## 高级功能 ### 故障转移机制 failover.py `failover.py` 实现了多提供商自动故障转移功能。当主提供商出现错误、超时或配额耗尽时，系统自动切换到备用提供商。 资料来源：[agenticx/llms/failover.py:1-100]() ```mermaid graph TD A[发起 LLM 请求] --> B{主提供商可用?} B -->|是| C[使用主提供商] B -->|否| D{备用提供商 1 可用?} D -->|是| E[使用备用提供商 1] D -->|否| F{备用提供商 2 可用?} F -->|是| G[使用备用提供商 2] F -->|否| H[返回错误] C --> I[记录成功] E --> I G --> I ``` 故障转移策略包括： - **错误类型判断**：区分临时性错误和永久性错误 - **健康检查**：定期检测提供商可用性 - **优先级排序**：按配置的优先级顺序尝试提供商 - **熔断机制**：连续失败达到阈值后暂时跳过该提供商 ### 响应缓存 response_cache.py `response_cache.py` 实现了 LLM 响应的缓存机制，通过对相同请求的缓存减少 API 调用次数和成本。 资料来源：[agenticx/llms/response_cache.py:1-100]() 缓存机制特点： | 特性 | 说明 | |------|------| | 请求哈希 | 基于消息内容生成唯一哈希键 | | TTL 控制 | 支持设置缓存过期时间 | | 相似度匹配 | 可选的语义相似度缓存 | | 命中率统计 | 提供缓存命中率指标 | | 手动失效 | 支持按需清除缓存 | ### 对话记录清理 transcript_sanitizer.py `transcript_sanitizer.py` 提供了对话记录的清理和规范化功能，确保传输给 LLM 的消息格式正确且安全。 资料来源：[agenticx/llms/transcript_sanitizer.py:1-100]() 主要功能： - **消息格式规范化**：统一不同来源消息的格式 - **敏感信息过滤**：移除或脱敏敏感数据 - **长度控制**：截断过长消息避免超出上下文限制 - **角色验证**：确保消息包含有效的角色定义 ## 企业管理后台集成 在企业管理后台中，LLM 提供商配置通过 `enterprise/apps/admin-console/src/app/admin/models/page.tsx` 页面进行管理。管理员可以： - 添加新的 LLM 提供商 - 为每个提供商配置多个模型 - 设置默认模型 - 移除不需要的模型 ```typescript // 模型添加数据结构 interface ModelConfig { name: string; // 模型 ID label: string; // 显示名称 provider: string; // 提供商标识 } ``` ## 桌面应用配置 桌面应用的设置面板（`desktop/src/components/SettingsPanel.tsx`）允许用户配置 LLM 相关的运行环境参数，包括： - 全局模型选择 - API 端点配置（如火山引擎等国内服务） - 环境依赖管理 - 工具注册表加载 ## 使用示例 ### Python 应用中创建 LLM 实例 ```python from agenticx.llms import create_llm # 使用 OpenAI llm = create_llm( provider="openai", config={ "api_key": "sk-xxx", "model": "gpt-4o-mini", "temperature": 0.7, } ) # 使用 Anthropic Claude claude = create_llm( provider="anthropic", config={ "api_key": "sk-ant-xxx", "model": "claude-3-haiku-20240307", } ) ``` ### 发送对话请求 ```python messages = [ {"role": "system", "content": "你是一个有帮助的助手"}, {"role": "user", "content": "什么是 RAG?"} ] response = llm.chat(messages) print(response.content) ``` ## 最佳实践 ### 提供商选择建议 | 场景 | 推荐提供商 | 原因 | |------|-----------|------| | 通用对话 | OpenAI GPT-4o | 平衡性能与成本 | | 长文本分析 | Anthropic Claude | 更长的上下文窗口 | | 代码生成 | OpenAI GPT-4 | 优化的代码能力 | | 国内部署 | 火山引擎等 | 合规与延迟考虑 | ### 可靠性保障 1. **配置多个备用提供商**：在 `failover.py` 中配置主备提供商 2. **启用响应缓存**：减少 API 调用成本，提高响应速度 3. **设置合理的超时时间**：避免请求长时间阻塞 4. **监控错误率**：定期检查提供商健康状态 ### 安全建议 - API 密钥通过环境变量或密钥管理服务注入，避免硬编码 - 使用 `transcript_sanitizer.py` 过滤敏感信息 - 启用 HTTPS 传输加密 - 限制 API 调用的并发数量防止配额耗尽 ## 扩展开发 如需添加新的 LLM 提供商，需要： 1. 在 `agenticx/llms/` 目录下创建新的提供商文件（如 `gemini_provider.py`） 2. 实现 `BaseLLM` 抽象基类的所有接口方法 3. 在 `llm_factory.py` 中注册新的提供商 4. 添加相应的配置验证和错误处理逻辑 ```python # 新提供商注册示例 from agenticx.llms.base import BaseLLM from agenticx.llms.llm_factory import register_provider class GeminiProvider(BaseLLM): def chat(self, messages: list[dict]) -> Response: # 实现 Gemini API 调用 pass register_provider("gemini", GeminiProvider) --- ## 协作与团队管理 ### 相关页面 相关主题：[Avatar 与群聊系统](#page-avatar-system), [Agent 核心框架](#page-agent-core)
相关源码文件 以下源码文件用于生成本页说明： - [agenticx/collaboration/manager.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/manager.py) - [agenticx/collaboration/delegation.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/delegation.py) - [agenticx/collaboration/role_playing.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/role_playing.py) - [agenticx/collaboration/workforce/coordinator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/coordinator.py) - [agenticx/collaboration/workforce/worker.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/worker.py) - [agenticx/collaboration/workload/task_decomposer.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workload/task_decomposer.py) - [agenticx/collaboration/workforce/failure_analyzer.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/failure_analyzer.py) - [agenticx/collaboration/workforce/recovery_strategies.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/recovery_strategies.py) - [agenticx/runtime/team_manager.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/runtime/team_manager.py)
# 协作与团队管理 ## 概述 AgenticX 的协作与团队管理模块提供了一套完整的多智能体协作框架，支持多种协作模式、任务委派、角色扮演以及劳动力（Workforce）编排。该模块使开发者能够构建复杂的分布式智能体系统，实现高效的任务分解、并行执行、失败恢复和结果聚合。 核心功能包括： - **多模式协作**：支持自定义模式、委派模式、角色扮演等多种协作范式 - **任务分解**：将复杂任务自动拆解为可并行执行的子任务 - **劳动力编排**：通过 Coordinator-Worker 架构协调多个智能体工作 - **失败分析与恢复**：自动检测任务失败原因并执行恢复策略 - **运行时团队管理**：动态管理团队生命周期和成员状态 ## 架构设计 ### 整体架构图 ```mermaid graph TB subgraph "协作管理层" CM[CollaborationManager] RP[RolePlaying] DG[Delegation] end subgraph "劳动力编排层" CO[Coordinator] WO[Worker Pool] TD[TaskDecomposer] end subgraph "支撑模块" FA[FailureAnalyzer] RS[RecoveryStrategies] TM[TeamManager] end CM --> CO CO --> WO CO --> TD WO --> FA FA --> RS RS --> CO CM --> RP CM --> DG TM --> CM ``` ### 核心组件职责 | 组件 | 文件路径 | 职责说明 | |------|----------|----------| | CollaborationManager | `agenticx/collaboration/manager.py` | 协作主入口，管理协作会话生命周期 | | Delegation | `agenticx/collaboration/delegation.py` | 任务委派逻辑，处理委托方与受托方交互 | | RolePlaying | `agenticx/collaboration/role_playing.py` | 角色扮演协作，管理多角色对话与行为 | | Coordinator | `agenticx/collaboration/workforce/coordinator.py` | 劳动力协调器，负责任务分发与结果聚合 | | Worker | `agenticx/collaboration/workforce/worker.py` | 工作节点，执行具体子任务 | | TaskDecomposer | `agenticx/collaboration/workload/task_decomposer.py` | 任务分解器，将复杂任务拆解为子任务 | | FailureAnalyzer | `agenticx/collaboration/workforce/failure_analyzer.py` | 失败分析器，诊断任务执行异常 | | RecoveryStrategies | `agenticx/collaboration/workforce/recovery_strategies.py` | 恢复策略库，提供多种故障恢复方案 | | TeamManager | `agenticx/runtime/team_manager.py` | 团队运行时管理，管理团队成员与状态 | 资料来源：[agenticx/collaboration/README.md](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) ## 协作模式 ### 模式类型 AgenticX 支持多种协作模式，通过 `CollaborationMode` 枚举定义： | 模式 | 说明 | 适用场景 | |------|------|----------| | `CUSTOM_PATTERN` | 自定义协作模式 | 灵活定制协作流程 | | `DELEGATION` | 任务委派模式 | 主从任务分配 | | `ROLE_PLAYING` | 角色扮演模式 | 多角色讨论与决策 | | `WORKFORCE` | 劳动力模式 | 大规模并行任务处理 | ### 注册自定义模式 在 `manager.py` 中的 `pattern_classes` 字典注册新的协作模式： ```python pattern_classes = { CollaborationMode.CUSTOM_PATTERN: CustomPattern, CollaborationMode.DELEGATION: DelegationPattern, CollaborationMode.ROLE_PLAYING: RolePlayingPattern, # ... 其他模式 } ``` 资料来源：[agenticx/collaboration/README.md:4](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) ## 委派模式（Delegation） ### 工作流程 ```mermaid sequenceDiagram participant M as Manager participant D as Delegator participant W as Worker participant TM as TeamManager M->>D: 创建委派任务 D->>TM: 分配任务给Worker TM->>W: 传递任务上下文 W-->>TM: 执行结果 TM-->>D: 聚合结果 D-->>M: 返回处理结果 ``` ### 核心功能 - **任务分配**：根据 Worker 能力动态分配任务 - **结果收集**：聚合多个 Worker 的执行结果 - **超时处理**：支持任务执行超时配置 - **优先级调度**：根据任务优先级安排执行顺序 资料来源：[agenticx/collaboration/delegation.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/delegation.py) ## 角色扮演模式（Role Playing） ### 角色定义 角色扮演模式允许定义具有特定身份和职责的智能体： | 角色属性 | 说明 | |----------|------| | `name` | 角色名称 | | `description` | 角色描述与职责 | | `prompt` | 角色行为提示词 | | `tools` | 角色可使用的工具集 | | `constraints` | 角色行为约束条件 | ### 多角色交互 ```mermaid graph LR A[主持人 Agent] --> B[角色A] A --> C[角色B] A --> D[角色N] B -->|消息| A C -->|消息| A D -->|消息| A ``` 资料来源：[agenticx/collaboration/role_playing.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/role_playing.py) ## 劳动力编排（Workforce） ### Coordinator-Worker 架构 劳动力编排采用经典的 Coordinator-Worker 模式： ```mermaid graph TD subgraph "Coordinator 职责" C1[任务分解] C2[Worker 选择] C3[结果聚合] C4[失败调度] end subgraph "Worker 职责" W1[接收任务] W2[任务执行] W3[状态上报] W4[结果返回] end C1 -->|子任务| W1 C2 -->|指派| W2 W3 -->|心跳| C3 W4 -->|结果| C3 ``` ### Coordinator Coordinator 是劳动力编排的核心调度器： | 功能 | 说明 | |------|------| | 任务分解 | 调用 TaskDecomposer 拆分复杂任务 | | Worker 池管理 | 维护可用 Worker 列表与状态 | | 任务分发 | 根据负载均衡策略分配任务 | | 结果聚合 | 合并多个子任务结果 | | 失败重试 | 触发失败恢复流程 | 资料来源：[agenticx/collaboration/workforce/coordinator.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/coordinator.py) ### Worker Worker 是实际的任务执行单元： ```python class Worker: def __init__(self, id, capabilities, tools=None): self.id = id self.capabilities = capabilities self.tools = tools or [] self.status = "idle" async def execute(self, task): # 任务执行逻辑 pass ``` | Worker 状态 | 说明 | |-------------|------| | `idle` | 空闲，可接受任务 | | `busy` | 执行中 | | `failed` | 执行失败 | | `offline` | 已下线 | 资料来源：[agenticx/collaboration/workforce/worker.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/worker.py) ### 任务分解器（Task Decomposer） 任务分解器负责将复杂任务拆解为可并行执行的子任务： | 分解策略 | 说明 | |----------|------| | `sequential` | 顺序分解，按步骤拆分 | | `parallel` | 并行分解，依赖关系并行 | | `hierarchical` | 层级分解，多级树状结构 | | `semantic` | 语义分解，基于意图拆分 | 资料来源：[agenticx/collaboration/workload/task_decomposer.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workload/task_decomposer.py) ## 失败分析与恢复 ### 失败分析器（Failure Analyzer） FailureAnalyzer 诊断任务执行失败的原因： | 分析维度 | 说明 | |----------|------| | 错误类型 | 区分系统错误、业务错误、超时等 | | 上下文追踪 | 定位失败发生的具体环节 | | 根因识别 | 分析失败的根本原因 | | 影响评估 | 评估失败对整体任务的影响 | 资料来源：[agenticx/collaboration/workforce/failure_analyzer.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/failure_analyzer.py) ### 恢复策略（Recovery Strategies） RecoveryStrategies 提供多种故障恢复方案： ```mermaid graph TD F[失败发生] --> A{失败类型} A -->|可重试| R1[重试策略] A -->|资源不足| R2[资源扩容] A -->|逻辑错误| R3[任务重分配] A -->|不可恢复| R4[终止并报告] R1 -->|重试成功| S[继续执行] R1 -->|重试失败| A R2 --> S R3 --> S ``` | 恢复策略 | 触发条件 | 恢复动作 | |----------|----------|----------| | `retry` | 瞬时错误、网络波动 | 自动重试指定次数 | | `reassign` | Worker 故障 | 重新分配给其他 Worker | | `decompose` | 部分失败 | 重新分解任务 | | `escalate` | 严重错误 | 升级到人工处理 | | `abort` | 不可恢复 | 终止任务并报告 | 资料来源：[agenticx/collaboration/workforce/recovery_strategies.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/workforce/recovery_strategies.py) ## 团队运行时管理 ### TeamManager TeamManager 负责管理团队的生命周期和成员状态： | 功能 | 说明 | |------|------| | 团队创建 | 初始化团队配置和成员 | | 成员管理 | 添加、移除、查询团队成员 | | 状态同步 | 维护成员实时状态 | | 资源分配 | 管理团队共享资源 | | 生命周期钩子 | 支持启动、停止事件回调 | 资料来源：[agenticx/runtime/team_manager.py](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/runtime/team_manager.py) ### 团队结构 ```mermaid classDiagram class TeamManager { +teams: Map~string, Team~ +create_team(config) +join_team(team_id, member) +leave_team(team_id, member_id) +broadcast(team_id, message) } class Team { +id: string +members: Member[] +status: TeamStatus +add_member(member) +remove_member(member_id) } class Member { +id: string +role: MemberRole +capabilities: string[] +status: MemberStatus } TeamManager "1" --> "*" Team Team "1" --> "*" Member ``` ## 使用示例 ### 创建协作会话 ```python from agenticx.collaboration import CollaborationManager, CollaborationMode # 初始化管理器 manager = CollaborationManager() # 创建委派模式协作 session = await manager.create_session( mode=CollaborationMode.DELEGATION, config={ "max_workers": 5, "timeout": 300, "retry_policy": {"max_retries": 3} } ) # 提交任务 result = await session.execute("分析并总结这份报告") ``` ### 注册自定义协作模式 ```python from agenticx.collaboration import CollaborationManager, CollaborationMode class CustomPattern: async def execute(self, context): # 自定义协作逻辑 pass # 在管理器中注册 manager = CollaborationManager() manager.register_pattern( CollaborationMode.CUSTOM_PATTERN, CustomPattern ) ``` 资料来源：[agenticx/collaboration/README.md:1-12](https://github.com/DemonDamon/AgenticX/blob/main/agenticx/collaboration/README.md) ## 配置选项 ### 全局配置参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `max_workers` | int | 10 | 最大 Worker 数量 | | `timeout` | int | 300 | 任务超时时间（秒） | | `retry.max_retries` | int | 3 | 最大重试次数 | | `retry.backoff` | str | "exponential" | 重试退避策略 | | `task_decomposition` | str | "auto" | 任务分解策略 | | `failure_threshold` | float | 0.5 | 失败率阈值 | ### Worker 配置 | 参数 | 类型 | 说明 | |------|------|------| | `id` | string | Worker 唯一标识 | | `capabilities` | list | Worker 具备的能力 | | `max_concurrent_tasks` | int | 最大并发任务数 | | `tools` | list | 可用工具列表 | | `priority` | int | Worker 优先级 | ## 最佳实践 ### 任务设计原则 1. **适度分解**：避免过度拆解导致协调开销过大 2. **能力匹配**：根据 Worker 能力合理分配任务 3. **错误隔离**：子任务之间保持独立性，减少失败影响范围 4. **状态管理**：定期保存中间状态，支持断点恢复 ### 性能优化 - 合理设置 Worker 池大小，避免资源浪费 - 使用异步通信减少等待时间 - 配置适当的超时和重试策略 - 监控关键指标，及时调整配置 ### 可靠性保障 - 配置多级重试策略处理瞬时故障 - 实现优雅降级机制 - 记录完整的执行日志便于问题排查 - 定期进行故障演练验证恢复能力 ## 相关资源 - [AgenticX 项目主页](https://github.com/DemonDamon/AgenticX) - [多 Agent 协作模式研究](https://arxiv.org/abs/2501.06322) - [企业版功能模块](../enterprise/README.md) --- ## Avatar 与群聊系统 ### 相关页面 相关主题：[协作与团队管理](#page-collaboration)
相关源码文件 以下源码文件用于生成本页说明： - [desktop/src/components/AvatarSettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarSettingsPanel.tsx) - [desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx) - [desktop/src/components/SettingsPanel.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/SettingsPanel.tsx) - [enterprise/features/chat/README.md](https://github.com/DemonDamon/AgenticX/blob/main/enterprise/features/chat/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)
# Avatar 与群聊系统 ## 概述 Avatar（分身）与群聊系统是 AgenticX 平台中实现多智能体协作的核心功能模块。该系统允许用户创建和管理多个 AI 分身（Avatar），每个分身可配置独立的角色、技能和行为模式，并通过群聊机制实现多智能体之间的协作与通信。 AgenticX 采用分层架构设计，将 Avatar 配置与运行时执行分离：桌面端负责 Avatar 的创建、配置与 UI 管理（`desktop/src/components/AvatarSettingsPanel.tsx`、`desktop/src/components/AvatarCreateDialog.tsx`），企业端则通过 `feature-agents` 和 `feature-chat` 模块提供身份认证与对话能力支撑。 --- ## 核心概念 ### Avatar（分身） Avatar 是 AgenticX 中的智能体实例，每个 Avatar 具有以下属性： | 属性 | 说明 | 配置位置 | |------|------|----------| | 名称 (name) | 分身标识名称 | AvatarCreateDialog.tsx | | 角色 (role) | 分身职能描述 | AvatarCreateDialog.tsx | | 头像 (avatar) | 用户头像图片 URL | AvatarSettingsPanel.tsx | | 用户偏好 | 注入系统提示的行为偏好 | SettingsPanel.tsx | | 启用技能 | 该分身可使用的技能列表 | AvatarCreateDialog.tsx | ### 群聊系统 群聊系统基于 `feature-chat` 模块实现，为多 Avatar 协作提供消息传递与状态同步能力。企业端通过 `feature-iam` 模块管理用户身份与权限，确保群聊操作的安全合规。 --- ## 架构设计 ```mermaid graph TD subgraph 桌面端 ["桌面客户端 (desktop)"] ASC[AvatarSettingsPanel] ACD[AvatarCreateDialog] SP[SettingsPanel] end subgraph 企业端 ["企业平台 (enterprise)"] FA[feature-agents] FC[feature-chat] FI[feature-iam] end ASC --> FA ACD --> FA SP --> FA FC --> FI FA --> FI FA --> |多智能体协作|FC ``` ### 模块职责 | 模块 | 职责 | |------|------| | `desktop/src/components/AvatarSettingsPanel.tsx` | 头像与分身基础信息编辑（名称、角色、头像 URL） | | `desktop/src/components/AvatarCreateDialog.tsx` | 新建分身对话框，支持技能配置与选择 | | `desktop/src/components/SettingsPanel.tsx` | 全局设置，包括用户偏好注入与元智能体配置 | | `@agenticx/feature-agents` | 企业级智能体管理与运行时 | | `@agenticx/feature-chat` | 对话工作区与群聊功能 | | `@agenticx/feature-iam` | 身份认证、租户、部门、角色与权限管理 | --- ## Avatar 配置详解 ### 头像设置 `AvatarSettingsPanel.tsx` 提供了头像管理的完整 UI： ```tsx // 头像预览与清除
{avatarUrlDraft ? ( Avatar Preview ) : (
{name ? name.charAt(0).toUpperCase() : "?"}
)}
``` 配置项说明： | 字段 | 类型 | 说明 | 默认值 | |------|------|------|--------| | avatarUrl | 字符串 | 头像图片 URL | 用户首字母 | | name | 字符串 | 分身名称 | 必填 | | role | 字符串 | 分身角色描述 | 选填 | > 资料来源：[desktop/src/components/AvatarSettingsPanel.tsx:25-35](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarSettingsPanel.tsx) ### 分身创建 `AvatarCreateDialog.tsx` 实现了分身创建流程： 1. **基础信息输入**：名称、角色描述 2. **技能选择**：从全局技能列表中筛选可用技能 3. **保存配置**：写入分身目录下的 `avatar.yaml` ```tsx // 技能启用状态管理 const [skillsEnabledDraft, setSkillsEnabledDraft] = useState>({}); // 技能切换逻辑 const toggleSkill = (skillName: string) => { setSkillsEnabledDraft((prev) => { const next = { ...prev }; if (next[skillName] === false) { delete next[skillName]; // 启用技能 } else { next[skillName] = false; // 禁用技能 } return next; }); }; ``` > 资料来源：[desktop/src/components/AvatarCreateDialog.tsx](https://github.com/DemonDamon/AgenticX/blob/main/desktop/src/components/AvatarCreateDialog.tsx) --- ## 用户偏好注入 系统支持通过用户偏好设置影响 Agent 的回复方式。配置位于 `SettingsPanel.tsx`： ```tsx