🧠 代理套件
AgentxSuite是一个开源平台,用于跨多个MCP服务器连接、管理和监控AI代理和工具,所有这些都在一个统一的界面中。
🚀 概述
AgentxSuite为分布式AI代理提供了一致的控制层。
它将代理、工具和策略连接到一个编排系统中,该系统专为安全、多租户和MCP兼容的环境而构建。
🧩 技术栈
| 组件 | 技术 |
|---|---|
| 后端 | Django 5.2+,Django REST框架3.15+ |
| MCP服务 | FastAPI 0.104+(MCP结构层) |
| 数据库 | PostgreSQL(生产)/SQLite(开发) |
| 语言 | Python 3.11+ |
后端/```
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.创建环境文件(可选):**```bash
cp .env.example .env
# Edit .env with your settings (SECRET_KEY, database passwords, etc.)
2.启动所有服务:```bash
docker-compose up -d
这将开始:
- PostgreSQL数据库(端口5432)
- Redis缓存(端口6379)
- Django API(端口8000)
- Next.js前端(端口3000)
**3.运行迁移:**```bash
docker-compose exec backend python manage.py migrate
4.创建超级用户:```bash
docker-compose exec backend python manage.py createsuperuser
**5.启动MCP结构服务(可选):**```bash
docker-compose --profile mcp-fabric up -d mcp-fabric
6.查看日志:```bash
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f mcp-fabric
**7.停止服务:**```bash
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 URLNEXT_PUBLIC_MCP_FABRIC_URL-前端MCP结构URL
方案2:地方发展
1.创建虚拟环境```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
**2.安装依赖项**```bash
cd backend
pip install -r requirements/base.txt
pip install -r requirements/dev.txt
pip install -r requirements/test.txt
3.应用迁移```bash
python manage.py migrate
**4.(可选)创建超级用户**```bash
python manage.py createsuperuser
5.启动服务器
重要提示: 确保虚拟环境已激活(source venv/bin/activate)
Django API```bash
cd backend
python manage.py runserver
**MCP结构(FastAPI)**```bash
cd backend
uvicorn mcp_fabric.main:app --reload --port 8090
同时启动两台服务器:```bash
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**```bash
# Django API
make run
# MCP Fabric
make run-mcp-fabric
🔑 认证
| 端点 | 方法 | 描述 |
|---|---|---|
/api/v1/auth/register/ |
POST | 注册新用户 |
/api/v1/auth/login/ |
POST | 登录并获取令牌 |
/api/v1/auth/logout/ |
POST | 注销当前用户 |
/api/v1/auth/me/ |
GET | 获取当前用户信息 |
头球```
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/`)提供了一种一致的工具执行方式:
**请求:**```json
{
"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兼容格式):```json
{
"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):**
|端点|方法|描述|
|----------|--------|-------------|
| `/mcp/{org_id}/{env_id}/.well-known/mcp/manifest.json` |GET |获取MCP清单|
| `/mcp/{org_id}/{env_id}/.well-known/mcp/tools` |GET |列出已注册的工具|
| `/mcp/{org_id}/{env_id}/.well-known/mcp/run` |POST |执行工具|
**根端点(从JWT令牌中提取的org/env):**
|端点|方法|描述|
|----------|--------|-------------|
| `/.well-known/mcp/manifest.json` |GET |获取MCP清单(来自令牌的org/env)|
| `/.well-known/mcp/tools` |GET |列出已注册的工具(来自令牌的org/env)|
| `/.well-known/mcp/run` |POST |执行一个工具(来自令牌的org/env)|
**身份验证:**```
Authorization: Bearer
JWT令牌必须包括 org_id 和 env_id 根端点的声明。
连接类型
MCP结构支持三种类型的连接:
- 系统工具 (
agentxsuite://system)
- 内部系统工具(例如。,
agentxsuite_list_runs,agentxsuite_create_agent) - 直接通过处理函数执行(无HTTP调用)
- 从数据库中提取工具
- 自有MCP结构 (
http://localhost:8090或配置的MCP结构URL)
- 指向同一MCP结构服务
- 工具直接从数据库中获取(绕过HTTP)
- 用于内部工具执行
- 外部MCP服务器 (任何其他HTTP端点)
- 标准MCP兼容服务器
- 工具通过HTTP(清单端点或默认值)获取
- 全面验证和健康检查
建筑亮点
- fastmcp --用于清单、工具和运行端点的嵌入式MCP服务器
- 注册表.py --使用fastmcp动态注册Django工具,支持直接数据库查询
- 适配器.py --将FastAPI工具处理程序连接到Django服务
- 安全层 --策略检查、JSON模式验证、速率限制、超时和审计日志记录
- 策略模式 --端点类型检测(SYSTEM、OWN_MCP_FABRIC、EXTERNAL_MCP)以实现最佳路由
🧪 测试
运行所有测试:```bash
pytest
**覆盖范围:**```bash
pytest --cov=apps --cov=libs --cov-report=term-missing
运行特定测试:```bash
pytest apps/policies/tests/unit/test_policies_allow_deny.py
**本地测试设置(带模拟MCP服务器):**```bash
python manage.py seed_local_agentsuite
bash dev/run_servers.sh
🧹 代码质量```bash
ruff check .
ruff format .
mypy apps libs
**或者通过Makefile:**```bash
make install
make lint
make typecheck
make test
🔐 策略和访问控制
AgentxSuite使用 默认拒绝 具有明确允许规则的策略模型。
策略规则
策略支持精确匹配和 通配符模式 使用Unix shell样式匹配(fnmatch):
示例:json
{
"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)*-匹配所有工具(小心使用)
政策评估:
- 首先检查拒绝列表 (限制性最强)
- 第二次检查允许列表 (明确许可)
- 默认拒绝 如果没有明确允许
政策范围:
- 策略可以是组织范围内的,也可以是特定于环境的
- 特定于环境的策略优先于整个组织的策略
- 按顺序评估多个策略
系统工具
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许可。
看 许可证 了解详情。
