## 项目概述

AgentTeams 是一个开源的协作式多智能体运行时平台，旨在通过 Matrix 房间实现透明、可人工介入的任务协调。它采用 Manager-Workers 架构，由 Manager 集中编排多个 Worker，支持人类与智能体之间以及企业环境中智能体之间的协作。AgentTeams 不与其他智能体运行时竞争，而是通过编排和管理多个智能体容器（包括 Manager 和众多 Worker）来实现其功能。

## 核心功能

- **Manager-Workers 架构**：通过让智能体管理其他智能体，消除人类对单个 Worker 的监督需求。
- **多运行时协作**：OpenClaw、QwenPaw 和 Hermes Worker 可在同一 IM 房间内共存，利用各自优势协同工作。
- **MinIO 共享文件系统**：为智能体间信息交换提供共享文件系统，显著降低多智能体协作场景下的 token 消耗。
- **Higress AI 网关**：集中管理流量并降低凭证相关风险，缓解用户对安全漏洞的担忧。
- **Element IM 客户端 + Tuwunel IM 服务器**（均基于 Matrix 协议）：消除钉钉/飞书集成开销和企业审批流程，支持快速上手。
- **AgentLoop 集成**：提供全栈智能体可观测性、审计、评估、实验以及资产管理和持续优化能力。

## 适用与不适用场景

**适用场景：**

- 需要协调多个专业化 Worker（如前端、后端、测试、研究等）的场景。
- 需要 Manager 分解和跟踪长期项目工作的场景。
- 需要在智能体工作过程中添加需求、检查进度或接管控制的场景。
- 需要通过统一网关控制对模型、MCP 工具和外部凭证的访问。
- 需要从本地机器开始，后续部署到 Kubernetes 共享实例的场景。

**不适用场景：**

- 仅需与单个智能体进行一次性对话，且不需要角色分离、共享任务空间或人工监督的场景，使用独立的智能体工具通常更简单。

## 技术架构与依赖

AgentTeams 采用多容器架构，核心组件包括：

- **agentteams-controller**：Go 编写的 Kubernetes 原生控制平面，负责协调 Worker、Manager、Team 和 Human 资源。
- **Higress AI 网关**：基于 Envoy 的 AI 网关，提供 LLM 代理、MCP 托管和消费者认证。
- **Tuwunel (Matrix)**：自托管的 Matrix 家庭服务器，承载所有智能体和人类通信。
- **Element Web**：默认的 Matrix Web 客户端。
- **MinIO**：集中式对象存储，用于智能体工作区、配置和共享文件。
- **Manager 和 Worker 容器/Pod**：运行智能体运行时，与基础设施分离，可按需创建或替换。

主要依赖包括 Go、Kubernetes、Helm、Docker、Matrix 协议、Higress、MinIO 等。

## 安装与快速开始

**前提条件：** Docker Desktop（Windows/macOS）或 Docker Engine（Linux），至少 2 核 CPU 和 4 GB 内存。

**macOS / Linux 安装：**

```bash
bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh)
```

**Windows (PowerShell 7+ 推荐)：**

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; iex $wc.DownloadString('https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.ps1')
```

安装程序会引导您：
1. 选择 LLM 提供商（支持 OpenAI 兼容 API）
2. 输入 API 密钥
3. 选择网络模式（仅本地或外部访问）
4. 等待设置完成

**访问：** 打开 http://127.0.0.1:18088 并登录 Element Web。Manager 会向您问好并解释如何创建第一个 Worker。

**Kubernetes 安装（Helm）：**

```bash
helm repo add higress.io https://higress.io/helm-charts
helm repo update
helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace \
  --render-subchart-notes \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080
```

## 典型使用方法

1. **创建 Worker：** 在 Element Web 中与 Manager 对话，发送如“创建一个名为 alice 的前端开发 Worker”的指令。
2. **分配任务：** 在 Worker 的房间中直接 @提及 Worker 并描述任务。
3. **人工介入：** 在任务执行过程中，可以随时添加需求或纠正方向。
4. **使用 Team：** 通过 YAML 声明式创建 Team，包含 Leader 和多个 Worker，实现团队协作。
5. **管理资源：** 使用 `agt` CLI 或 YAML 文件（`agt apply -f`）管理 Worker、Team、Human 等资源。

## 配置与部署要点

- **本地部署：** 使用 `install/agentteams-install.sh` 脚本，支持 Quick Start 和 Manual Setup 模式。
- **Kubernetes 部署：** 使用 Helm chart，支持自定义模型服务、存储、网关等配置。
- **模型配置：** 通过 `credentials.llmApiKey`、`credentials.llmProvider`、`credentials.defaultModel` 等参数配置 LLM 提供商。
- **安全模型：** Worker 仅持有消费者令牌，真实凭证存储在网关中；Matrix 房间提供完整可见性和人工介入能力。
- **升级：** 重新运行安装脚本或使用 `helm upgrade` 进行升级，保留数据。
- **卸载：** 使用安装脚本的 `uninstall` 参数或 `helm uninstall` 命令。

## 限制、风险与许可证

**限制：**

- 当前 Worker CRD 不接受显式的 `spec.runtime: openhuman`。
- `agt apply` 不支持 `--prune`、`--dry-run` 和 `--watch`。
- 某些功能（如 DebugWorker）尚未完全实现。

**风险：**

- 文件同步 I/O 放大问题（Issue #1107）已识别并部分修复。
- 容器运行时 socket 挂载具有主机级权限，需谨慎使用。
- 生产环境需配置 HTTPS、网络策略、最小权限访问、Secret 管理、备份和审计。

**许可证：** Apache License 2.0

## 官方链接

- GitHub 仓库：https://github.com/agentscope-ai/AgentTeams
- Discord 社区：https://discord.gg/NVjNA4BAVw
- 最新版本：v1.2.2（2026-08-08 发布）

## 信息来源和分析时间

本指南基于 GitHub 仓库 `agentscope-ai/AgentTeams` 的 README、文档和设计文档编写，分析时间为 2026-08-08。