mate (Antiv)

MATE——人工智能代理的指挥中心

停止重新部署以调整循环。

    

由...创建 伊万 安东尼耶维奇

你建立了一个代理。现在，您需要调整提示。交换模型。限制特定用户的访问。弄清楚它实际上花了你多少钱。确保昨天的行为在今天的改变后仍然有效。

如果没有控制层，每一个都是代码更改、提交和重新部署。

MATE就是控制层。 它基于Google ADK构建，添加了生产所需的一切——实时配置、RBAC、成本跟踪、回归测试和可嵌入的聊天小部件——而无需触及您的代理代码。

______________________________________________________________________

生产中的代理问题

笔记本中的单个代理很容易。服务于真实用户的代理层次结构并非如此。

• 迭代很慢。 调整提示意味着编辑代码、提交和重新部署。当你测试了三种变体时，你已经浪费了半天时间。
• 治理是混乱的。 谁可以呼叫管理员代理？财务代理人？您需要每个代理的访问控制，但ADK不附带RBAC。
• 成本是看不见的。 你知道代币正在被使用，但你看不出哪个代理是昂贵的，也看不出是提示代币、响应代币还是消耗你预算的推理代币。
• 悔恨是无声的。 你改进了一个提示，却在不知不觉中破坏了另一个代理的逻辑。只有当用户抱怨时，你才会知道。

______________________________________________________________________

MATE给你的三件事

🎨 Studio——在不接触代码的情况下构建和迭代

一个拖放画布，您可以在其中创建代理、绘制父对象→无需编写JSON或Python，即可创建子连接和附加工具。更改提示、交换模型（从Gemini到GPT-4o再到本地Ollama）或重组整个层次结构——这些都会立即生效，无需重新部署。

每个代理都存在于数据库中。每一个变化都是版本化的。一键回滚到任何以前的配置。

🏛️ 控制室——管理生产中的运行

每个代理的RBAC意味着，在没有任何自定义中间件的情况下，财务团队的代理永远不会对基本用户可见。令牌跟踪将每个请求分为四个部分——提示、响应、想法和工具使用令牌——这样你就可以准确地看到每个代理、每小时、每个用户的成本来自哪里。

从仪表板添加护栏（幻觉评分、每个用户/项目的费率限制）。审计日志记录每一个配置更改以确保合规性。

🧪 实验室——发货前就知道

Eval Framework会自动针对测试套件运行您的代理。写出预期产出；MATE调用实时代理，对响应进行评分（精确匹配、语义相似性或LLM作为判断），并以图表形式跟踪不同版本的通过率。

设置回归阈值，如果新版本的得分比上一个版本低5分以上，MATE将触发一个webhook。在用户之前捕获提示回归。

______________________________________________________________________

快速开始

git clone https://github.com/antiv/mate.git && cd mate
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Set GOOGLE_API_KEY (or any supported provider key)

python auth_server.py
# Dashboard: http://localhost:8000  — login: admin / mate

或者使用Docker：

docker-compose up

迁移在启动时自动运行。默认数据库是SQLite。

______________________________________________________________________

截图

仪表板概述

监控使用情况、活动代理、系统健康状况和请求趋势。

Dashboard Overview

代理管理

查看和管理您的完整代理层次结构——每个项目的模型、父关系和状态。

Agent Management

代理可视化生成器

拖放画布以构建代理层次结构。请参阅附加到每个代理的工具和MCP节点，单击以内联配置它们，并在不接触JSON的情况下创建连接。

Agent Visual Builder

工作室

仪表板内的内置聊天界面。从卡网格中选择任何根代理并开始对话——没有嵌入代码，也没有浏览器选项卡切换。会话会自动命名，并在页面重新加载时保持不变。登录后的默认登录页面。

Work Room

代理配置

编辑代理的各个方面：模型、指令、RBAC角色、内存块、工具、MCP服务器、计划器和模式。

Agent Configuration

工具配置

切换内置工具或提供自定义JSON——谷歌驱动器、搜索、图像、内存块、代码执行器、文件搜索等。

Tool Configuration

聊天界面

具有事件跟踪、工具调用和持久内存的多代理聊天。

Chat Interface

使用情况分析

令牌使用趋势、代理性能、每小时活动和每个代理的成功率。

Usage Analytics

令牌使用详细信息

深入查看单个请求日志——每个请求的提示/响应/想法/工具使用令牌细分。

Token Usage Details

______________________________________________________________________

为什么选择MATE与原始ADK

______________________________________________________________________

特性

工作室

• 仪表板中的内置聊天界面——从卡网格中选择一个根代理并开始对话，不需要嵌入代码
• 会话会自动命名（生成LLM），并在页面重新加载时保持不变
• 支持与可嵌入小部件相同的流式SSE、工具使用指示器和markdown渲染
• 登录后的默认登录页面——对居住在仪表板中的内部团队很有用

工作室

• 数据库驱动的代理管理——每个字段都可以从仪表板编辑，无需重新部署
• 拖放Visual Builder（React Flow）——创建代理，绘制父级→子边、配置工具和MCP节点内联
• 通过LiteLLM的50多家LLM提供商：Gemini、GPT-4o、Claude、Llama（Ollama）、DeepSeek、OpenRouter等
• 一键回滚的代理版本历史记录
• 自建代理—— create_agent 该工具允许代理在运行时创建、更新和删除其他代理（仅限管理员，RBAC保护）
• 以JSON格式导入/导出代理配置

控制室

• 每个代理的RBAC：在仪表板中分配角色，无需编写中间件
• 谷歌（OIDC）和GitHub OAuth 2.0 SSO，具有自动用户配置功能；基本身份验证始终可用
• 跨四种类型的令牌跟踪：提示、响应、想法、工具使用——每个代理、每个会话、每个用户
• 可从仪表板为每个用户/代理/项目配置速率限制
• 幻觉护栏：LLM根据响应进行事实一致性检查，可配置阈值
• 函数调用和模型级护栏
• 每次配置更改的审计日志（欧盟人工智能法案保留意识）
• 普罗米修斯指标 /metrics
• OpenTetry分布式跟踪

实验室

• Eval框架：每个代理的测试套件具有精确匹配、语义相似性或LLM作为判断评分
• 自动调用——evals调用实时代理；无复制粘贴响应
• 跨版本评分历史图表（chart.js）
• 回归webhooks：当新版本与前一版本相比下降超过5点时触发

可嵌入小部件

• 单身 `` 标签在任何网站上部署浮动聊天按钮
• 按键RBAC、源限制和作用域用户名间距
• 小部件管理面板(/widget/admin?key=...)对于非技术团队：在没有仪表板访问权限的情况下编辑问候语、主题、颜色、内存块和文件
• 浅色/深色/自动主题，可配置强调色，可选文件附件
• 页面上下文注入：小部件自动读取嵌入页面的URL和标题，并将其作为对话上下文传递给代理

基础设施

• SQLite（开发）、PostgreSQL、MySQL——启动时自动迁移
• Docker Compose与健康检查
• 工件存储：本地、S3或Supabase
• MCP：代理暴露为MCP服务器（Claude Desktop、Cursor）+MCP工具消耗

______________________________________________________________________

设置

环境变量

# Minimum required
GOOGLE_API_KEY=your_key_here          # or any supported provider

# Database (SQLite by default)
DATABASE_URL=postgresql://user:pass@localhost:5432/mate
# DB_TYPE=sqlite (default), postgresql, mysql

# Authentication
AUTH_USERNAME=admin
AUTH_PASSWORD=mate

# SSO (optional)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
SECRET_KEY=       # required for SSO sessions

# Additional LLM providers (only set keys for providers you use)
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
OPENROUTER_API_KEY=...
OLLAMA_API_BASE=http://localhost:11434

# Optional features
ROOT_AGENT_NAME=my_root_agent         # override default root agent
MCP_EXPOSED_AGENTS=agent1,agent2      # expose agents as MCP servers
RATE_LIMIT_ENABLED=true
OTEL_TRACING_ENABLED=true
AUDIT_RETENTION_DAYS=365

数据库迁移

python shared/migrate.py status     # check pending migrations
python shared/migrate.py run        # apply manually (auto-runs on startup)
python shared/migrate.py create     # scaffold a new migration
python shared/migrate.py rollback   # roll back last migration

码头工人

docker-compose up --build           # full stack with dashboard
docker-compose up -d --build        # background

______________________________________________________________________

测试

# All tests
python -m unittest discover -s shared/test -p "test_*.py" -v

# With coverage
coverage run -m unittest discover -s shared/test -p "test_*.py"
coverage report --include="shared/utils/*,server/*,auth_server.py"

134+个测试，涵盖代理管理、RBAC、迁移、护栏、跟踪、令牌跟踪等。

______________________________________________________________________

嵌入式聊天小部件——一个后端，多个站点

单个MATE实例可以同时为多个网站上的AI聊天提供支持。每个站点都有自己的小部件密钥，其作用域为特定的代理，具有独立的外观、内存和访问规则。

 on any website -->

一个浮动聊天按钮立即出现。无构建步骤，无框架依赖。

多站点示例

MATE instance
├── key: wk_aaa  →  support_agent    →  company-support.com   (English, light theme)
├── key: wk_bbb  →  sales_agent      →  company-sales.com     (dark theme, no attachments)
└── key: wk_ccc  →  docs_agent       →  docs.company.com      (RAG over product docs)

每个键都是独立的：不同的代理、不同的问候语、不同的允许来源、不同的配色方案。

页面上下文感知

当用户在产品页面上打开小部件时，小部件会自动读取页面URL、标题和元描述，并将其作为对话上下文传递给代理。代理知道用户正在查看哪个页面，而无需任何自定义集成——只需在小部件管理面板中启用“注入页面上下文”即可。

小部件管理面板

每个密钥都有一个独立的管理面板 /widget/admin?key=...非技术团队可以管理外观、问候语、内存块和上传的文件，而无需触摸主仪表板。

完整文档： 文档/WIDGE_INTEGRATION.md

______________________________________________________________________

MCP集成

MATE将代理和工具作为MCP服务器公开，与Claude Desktop、Cursor和任何MCP客户端兼容。

# Expose specific agents as MCP servers
export MCP_EXPOSED_AGENTS=creative_agent,support_agent

每个暴露的代理在以下位置获得端点 /agents/{name}/mcp/*内置MCP服务器：图像生成(/images/mcp)以及谷歌云端硬盘(/gdrive/mcp).

完整文档： 文件/MCP_SERVERS.md

______________________________________________________________________

仪表板路线

______________________________________________________________________

补充文件

• 文档/WIDGE_INTEGRATION.md -嵌入代码，小部件管理面板，JS API，安全性，主题化，页面上下文
• 文档/SSO_OAUTH.md --Google和GitHub SSO设置、企业域限制、会话安全
• 文件/EVALS.md -eval方法、回归警报、LLM-as-Judge配置、API参考
• 文件/MCP_SERVERS.md --MCP服务器配置、客户端设置（Claude Desktop、Cursor）、协议详细信息
• 文档/RATE_LIMITS.md --按用户/代理/项目费率限制
• 文件/TRACING.md --OpenTetry跟踪设置
• 代理商.md --添加新代理或工具的架构模式和指南

______________________________________________________________________

贡献

欢迎捐款。看 贡献.md 用于开发设置、代码风格和PR指南。

安全

有关安全最佳实践和漏洞报告，请参阅 安全.md.

许可证

Apache许可证2.0——请参阅 许可证.