agentxsuite (Alparn)

🧠 代理套件

AgentxSuite是一个开源平台，用于跨多个MCP服务器连接、管理和监控AI代理和工具，所有这些都在一个统一的界面中。

🚀 概述

AgentxSuite为分布式AI代理提供了一致的控制层。

它将代理、工具和策略连接到一个编排系统中，该系统专为安全、多租户和MCP兼容的环境而构建。

🧩 技术栈

后端/

  config/              # Django project configuration
  apps/
    accounts/          # User model & auth
    tenants/           # Organizations & Environments
    connections/       # MCP server connections
    agents/            # Agent definitions
    tools/             # Tool registry
    runs/              # Run orchestration
    policies/          # Access policies
    audit/             # Audit events (stub)
  libs/
    secretstore/       # Secret storage abstraction
    permissions/       # RBAC utilities
  mcp_fabric/          # FastAPI MCP-compatible service
    routers/           # Manifest, tools, and run endpoints
    tests/             # Unit & integration tests
  requirements/        # Dependencies (base, dev, test)

⚙️ 设置

选项1:Docker（推荐）

最简单的入门方法是使用Docker Compose：

1.创建环境文件（可选）：

cp .env.example .env
# Edit .env with your settings (SECRET_KEY, database passwords, etc.)

2.启动所有服务：

docker-compose up -d

这将开始：

• PostgreSQL数据库（端口5432）
• Redis缓存（端口6379）
• Django API（端口8000）
• Next.js前端（端口3000）

3.运行迁移：

docker-compose exec backend python manage.py migrate

4.创建超级用户：

docker-compose exec backend python manage.py createsuperuser

5.启动MCP结构服务（可选）：

docker-compose --profile mcp-fabric up -d mcp-fabric

6.查看日志：

docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f mcp-fabric

7.停止服务：

docker-compose down

环境变量：

• SECRET_KEY -Django密钥（必填）
• POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD -数据库凭据
• SECRETSTORE_FERNET_KEY -用于秘密加密的Fernet密钥
• CORS_ALLOWED_ORIGINS -允许的CORS来源
• NEXT_PUBLIC_API_URL -前端API URL
• NEXT_PUBLIC_MCP_FABRIC_URL -前端MCP结构URL

方案2：地方发展

1.创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2.安装依赖项

cd backend
pip install -r requirements/base.txt
pip install -r requirements/dev.txt
pip install -r requirements/test.txt

3.应用迁移

python manage.py migrate

4.（可选）创建超级用户

python manage.py createsuperuser

5.启动服务器

重要提示： 确保虚拟环境已激活(source venv/bin/activate)

Django API

cd backend
python manage.py runserver

MCP结构（FastAPI）

cd backend
uvicorn mcp_fabric.main:app --reload --port 8090

同时启动两台服务器：

cd backend
# Terminal 1: Django
python manage.py runserver

# Terminal 2: MCP Fabric (in new terminal, venv must be activated!)
source ../venv/bin/activate  # If not already activated
uvicorn mcp_fabric.main:app --reload --port 8090

替代方案：使用Makefile

# Django API
make run

# MCP Fabric
make run-mcp-fabric

🔑 认证

头球

Authorization: Token 

🧱 核心终点

组织与环境

• GET /api/v1/orgs/
• POST /api/v1/orgs/
• GET /api/v1/orgs/:org_id/environments/
• POST /api/v1/orgs/:org_id/environments/

连接

• GET /api/v1/orgs/:org_id/connections/
• POST /api/v1/orgs/:org_id/connections/
• POST /api/v1/connections/:id/test/
• POST /api/v1/connections/:id/sync/

代理、工具和运行

• GET /api/v1/orgs/:org_id/agents/
• POST /api/v1/orgs/:org_id/agents/
• GET /api/v1/orgs/:org_id/tools/
• POST /api/v1/orgs/:org_id/tools/
• POST /api/v1/orgs/:org_id/runs/execute/ - 统一工具执行端点 （推荐）
• POST /api/v1/tools/:id/run/ -旧端点（已弃用，请使用 /runs/execute/ 相反）
• GET /api/v1/orgs/:org_id/runs/

统一运行API

统一运行端点(POST /api/v1/orgs/:org_id/runs/execute/)提供了一种一致的工具执行方式：

请求：

{
  "tool": "uuid-or-name",      // Tool UUID or name
  "agent": "uuid",              // Optional if Agent-Token is used
  "input": {...},               // Input data
  "environment": "uuid",        // Optional, derived from tool if not provided
  "timeout_seconds": 30         // Optional timeout
}

响应（MCP兼容格式）：

{
  "run_id": "uuid",
  "status": "succeeded",
  "content": [{"type": "text", "text": "..."}],
  "isError": false,
  "agent": {"id": "...", "name": "..."},
  "tool": {"id": "...", "name": "..."},
  "execution": {
    "started_at": "2025-01-01T12:00:00Z",
    "ended_at": "2025-01-01T12:00:02Z",
    "duration_ms": 2000
  }
}

代理选择：

• 如果使用代理令牌：代理将自动从令牌中提取（最高优先级）
• 如果没有代理令牌： agent 请求中的字段是必需的（无自动回退）
• 出于安全原因，不允许自动选择代理

🧬 MCP结构（FastAPI服务）

MCP结构将标准化的MCP端点暴露给来自连接环境的访问工具。它支持基于多租户URL的路由和基于JWT令牌的身份验证。

端点

多租户端点（URL路径中的org/env）：

根端点（从JWT令牌中提取的org/env）：

身份验证：

Authorization: Bearer 

JWT令牌必须包括 org_id 和 env_id 根端点的声明。

连接类型

MCP结构支持三种类型的连接：

1. 系统工具 (agentxsuite://system)

- 内部系统工具（例如。， agentxsuite_list_runs, agentxsuite_create_agent) - 直接通过处理函数执行（无HTTP调用） - 从数据库中提取工具

1. 自有MCP结构 (http://localhost:8090 或配置的MCP结构URL）

- 指向同一MCP结构服务 - 工具直接从数据库中获取（绕过HTTP） - 用于内部工具执行

1. 外部MCP服务器 （任何其他HTTP端点）

- 标准MCP兼容服务器 - 工具通过HTTP（清单端点或默认值）获取 - 全面验证和健康检查

建筑亮点

• fastmcp --用于清单、工具和运行端点的嵌入式MCP服务器
• 注册表.py --使用fastmcp动态注册Django工具，支持直接数据库查询
• 适配器.py --将FastAPI工具处理程序连接到Django服务
• 安全层 --策略检查、JSON模式验证、速率限制、超时和审计日志记录
• 策略模式 --端点类型检测（SYSTEM、OWN_MCP_FABRIC、EXTERNAL_MCP）以实现最佳路由

🧪 测试

运行所有测试：

pytest

覆盖范围：

pytest --cov=apps --cov=libs --cov-report=term-missing

运行特定测试：

pytest apps/policies/tests/unit/test_policies_allow_deny.py

本地测试设置（带模拟MCP服务器）：

python manage.py seed_local_agentsuite
bash dev/run_servers.sh

🧹 代码质量

ruff check .
ruff format .
mypy apps libs

或者通过Makefile：

make install
make lint
make typecheck
make test

🔐 策略和访问控制

AgentxSuite使用 默认拒绝 具有明确允许规则的策略模型。

策略规则

策略支持精确匹配和 通配符模式 使用Unix shell样式匹配(fnmatch):

示例：

{
  "allow": ["agentxsuite_*", "custom_special_tool"],
  "deny": ["dangerous_*", "*_delete_all"]
}

通配符模式：

• agentxsuite_* -匹配所有系统工具（例如。， agentxsuite_list_runs, agentxsuite_create_agent)
• *_delete -匹配以结尾的工具 _delete （例如。， user_delete, tool_delete)
• tool-* -匹配以开头的工具 tool- （例如。， tool-123, tool-test)
• * -匹配所有工具（小心使用）

政策评估：

1. 首先检查拒绝列表 （限制性最强）
2. 第二次检查允许列表 （明确许可）
3. 默认拒绝 如果没有明确允许

政策范围：

• 策略可以是组织范围内的，也可以是特定于环境的
• 特定于环境的策略优先于整个组织的策略
• 按顺序评估多个策略

系统工具

AgentxSuite包括用于管理的内置系统工具：

• agentxsuite_list_runs -列出某个环境的所有运行
• agentxsuite_create_agent -创建新代理
• agentxsuite_get_agent -获取代理详细信息
• agentxsuite_list_agents -列出所有代理
• agentxsuite_list_connections -列出所有连接
• agentxsuite_list_tools -列出所有工具

系统工具通过特殊的连接端点访问： agentxsuite://system

开发人员文档：

• 令牌使用跟踪 -如何在系统工具和外部MCP服务器中实现令牌使用跟踪和成本计算

🌟 特性

• 多租户架构 -完全隔离的组织和环境
• 基于策略的访问控制 -通配符支持、默认拒绝模型、特定于环境的规则
• 系统工具 -用于代理、运行、连接和工具的内置管理工具
• 令牌使用跟踪 -LLM驱动工具的自动令牌使用和成本计算
• MCP兼容的FastAPI网关 -具有JWT身份验证的标准MCP端点
• 连接类型 -支持系统工具、自己的MCP结构和外部MCP服务器
• 工具执行结果 -带有run_id、持续时间和内容的MCP格式响应
• 秘密商店 -Fernet加密用于秘密，从不以明文形式存储
• 服务层架构 -关注点的清晰分离，服务中的业务逻辑
• 高测试覆盖率 -带pytest的全面测试套件
• 严格类型检查 -mypy完全支持类型安全
• 代理设计师 -基于节点图的可视化工作流编辑器，用于设计代理架构
• 审计和日志 -全面的审计日志系统，用于跟踪所有系统事件和操作
• 成本分析 -高级成本跟踪和分析仪表板，具有详细的细分和可视化功能

🎨 用户界面功能

代理设计师

这 代理设计师 提供了一个强大的可视化工作流编辑器，用于设计和管理代理架构。此基于节点的界面允许您：

• 视觉建筑设计：使用直观的基于节点的图表编辑器创建和可视化复杂的代理工作流
• 组件管理：通过拖放交互添加和连接代理、环境、策略和系统组件
• 关系映射：使用交互式连接线可视化不同组件之间的连接和依赖关系
• 自动排列：自动组织和对齐节点以提高可读性
• 导出功能：导出您的设计以供记录或共享
• 过滤和分组：按类型、环境或自定义条件组织和筛选组件
• 交互式导航：使用小地图概览缩放、平移和导航大图

设计器支持多种节点类型，包括：

• 代理 -AI代理定义和配置
• 环境 -部署环境（暂存、生产、开发）
• 政策 -访问控制和安全策略
• 系统组件 -核心系统服务和基础设施

审计和日志

这 审计和日志 系统提供对所有系统事件和动作的全面跟踪和监控：

• 完整的事件历史记录：跟踪所有系统事件，包括工具执行、策略决策、代理操作和管理更改
• 详细活动信息：每个日志条目包括：

- 时间戳 -事件的精确时间 - 主题 -触发动作的实体（例如。， agent:AgentCore@ITO/dev) - 男演员 -执行该操作的用户或代理 - 行动 -动作类型（例如。， tool.run.success, policy.check) - 目标 -受行动影响的资源或实体 - 决定 -政策决定（允许/拒绝） - 规则ID -已评估的策略规则 - 详情 -完整的上下文，包括运行ID、代理ID、工具ID、组织/环境ID和请求ID

• 筛选和搜索：按时间范围、参与者、操作类型或决策筛选日志
• 导出功能：出于合规、分析或存档目的导出审计日志
• 实时监控：实时查看系统活动

这种全面的审计跟踪确保了AgentxSuite中所有操作的完全透明度和合规性。

成本分析

这 成本分析 仪表板提供了有关AI代理成本和资源使用情况的详细见解：

• 关键指标概述:

- 总成本 -投入/产出成本明细的总体支出 - 总跑动 -成功率跟踪的执行次数 - 代币总数 -令牌消耗与输入/输出令牌计数 - 每次运行的平均成本 -每次执行的成本效益指标

• 灵活的时间范围：分析7天、30天或90天内的成本

• 多维分析：查看按以下方式分组的成本：

- 由代理商提供 -每个代理的成本明细 - 按环境 -跨环境（生产、开发、暂存）的成本分配 - 按型号 -使用的每个AI模型的成本 - 按工具 -工具特定成本分析

• 可视化分析:

- 条形图 -显示成本分布的水平进度条 - 饼图 -按类别分列的成本百分比 - 趋势指标 -显示成本随时间变化的可视化趋势图

• 详细分解：对于每个类别，请查看：

- 总成本 - 运行次数 - 令牌使用（输入和输出） - 成功率 - 每次执行成本

成本分析仪表板可帮助您优化支出，识别成本驱动因素，并就整个AI代理基础设施的资源分配做出明智的决策。

📚 文档

• 令牌使用跟踪 -在系统工具和外部MCP服务器中实现自动令牌使用和成本跟踪的指南

📄 许可证

根据AGPL-3.0许可。

看 许可证 了解详情。