AgentTeams README

The project's README from github.com/agentscope-ai/AgentTeams. As one markdown file: README.md.

AgentTeams

English | 中文 | 日本語

DeepWiki Discord

AgentTeams is an open-source collaborative multi-agent runtime platform. It enables multiple Agents to collaborate in a controlled and auditable room, with full human visibility and intervention capabilities throughout the process.

Built on a Manager-Workers architecture, AgentTeams features a Manager that centrally orchestrates multiple Workers, focusing on collaboration scenarios between humans and Agents, as well as among Agents within enterprise environments.

AgentTeams does not compete with other Agent runtimes. Instead of implementing Agent logic itself, it orchestrates and manages multiple Agent containers (including the Manager and numerous Workers).

Key Features

News

Why AgentTeams

Quick Start

Prerequisites: Docker Desktop (Windows/macOS) or Docker Engine (Linux).

Resources: 2 CPU cores + 4 GB RAM minimum. For multiple Workers, 4 cores + 8 GB recommended.

Install

macOS / Linux:

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

Windows (PowerShell 7+ recommended):

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')

The installer walks you through:

  1. Choose your LLM provider (OpenAI-compatible APIs supported)
  2. Enter your API key
  3. Select network mode (local-only or external access)
  4. Wait for setup to complete

Access

Open http://127.0.0.1:18088 in your browser and log in to Element Web. The Manager will greet you and explain how to create your first Worker.

Mobile: Use any Matrix client (Element, FluffyChat) and connect to your server address.

That's it. No bot applications. No external services. Your AI team runs entirely on your machine.

Upgrade

# Upgrade to latest (preserves all data)
bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh)

# Upgrade to specific version
AGENTTEAMS_VERSION=v1.2.2 bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh)

Uninstall

macOS / Linux:

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

Windows (PowerShell):

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

This removes all AgentTeams containers (Manager, Workers, docker-proxy), Docker volume, network, env file, workspace directory, and install log.

Install on Kubernetes (Helm)

For shared / production deployments you can install AgentTeams on any Kubernetes cluster via the official Helm chart. The default profile bundles the Higress AI gateway, Tuwunel (Matrix), MinIO and the AgentTeams controller — no external dependencies required.

The commands below provide a quick installation path. See the Kubernetes Deployment Guide for cluster planning, values files, model services, runtimes, persistence, Ingress, and operations.

Prerequisites

Install (OpenAI / OpenAI-compatible)

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

For non-OpenAI providers that expose an OpenAI-compatible API, also set llmBaseUrl:

helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace \
  --render-subchart-notes \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \
  --set credentials.defaultModel=your-model-name \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080
Using Qwen (通义千问) instead 
helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace \
  --render-subchart-notes \
  --set credentials.llmApiKey=<your-qwen-api-key> \
  --set credentials.llmProvider=qwen \
  --set credentials.defaultModel=qwen3.5-plus \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080
Value Required Description
credentials.llmApiKey yes API key for your LLM provider
gateway.publicURL yes Public URL where users will reach Element Web (e.g. http://localhost:18080 for port-forward, or https://agentteams.example.com for an Ingress)
credentials.adminPassword recommended Matrix admin password; auto-generated if left empty (you'll have to read it back from the Secret)
credentials.llmProvider no LLM provider name, defaults to openai-compat
credentials.defaultModel no Default model, defaults to gpt-5.4
credentials.llmBaseUrl no OpenAI-compatible base URL (e.g. https://api.deepseek.com/v1). Leave empty for official OpenAI API
preflight.llm.enabled no Run an install/upgrade hook that validates the LLM API key, base URL, and model before the controller starts. Defaults to true
preflight.llm.strict no Fail the Helm install/upgrade when the LLM preflight fails. Defaults to true; set to false to emit a warning and continue
preflight.llm.timeoutSeconds no Per-request timeout for the LLM preflight HTTP probe. Defaults to 30
preflight.llm.retries no Retry count for transient LLM preflight failures such as rate limits and provider 5xx responses. Defaults to 2
preflight.llm.activeDeadlineSeconds no Kubernetes Job active deadline for the preflight hook. Defaults to 120
preflight.llm.resources no Optional Kubernetes resource requests/limits for the preflight hook container
manager.runtime no Manager runtime: OpenClaw uses openclaw (default); CoPaw uses qwenpaw in the current chart, with copaw retained as a compatibility alias. Managers do not support Hermes or DeepSeek Harness
worker.defaultRuntime no The chart provides default image values for openclaw (default), copaw, hermes, experimental deepseek-harness, and openhuman; the current CRD rejects an explicit spec.runtime: openhuman, and QwenPaw Workers require an explicit spec.image

Helm installs run an LLM preflight hook by default. The hook sends a minimal OpenAI-compatible /chat/completions request using credentials.llmApiKey, credentials.llmBaseUrl, and credentials.defaultModel; invalid keys, unreachable base URLs, unsupported models, quota errors, and provider outages fail the install before the controller starts. To bypass this check for restricted or offline clusters:

helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080 \
  --set preflight.llm.enabled=false
Using alternative runtimes (CoPaw Manager + Hermes Workers) 
helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace --devel \
  --set manager.runtime=qwenpaw \
  --set manager.image.repository=higress-registry.cn-hangzhou.cr.aliyuncs.com/agentteams/agentteams-manager-qwenpaw \
  --set worker.defaultRuntime=hermes \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \
  --set credentials.defaultModel=your-model-name \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080

When selecting the CoPaw Manager, set both manager.runtime=qwenpaw and the agentteams-manager-qwenpaw image. Configure Worker default images through worker.defaultImage.<runtime>.

Multi-Region Image Registry

Images point to the China region by default. When deploying outside China, use a nearby registry for faster pulls:

Region Registry
China (default) higress-registry.cn-hangzhou.cr.aliyuncs.com/higress
North America higress-registry.us-west-1.cr.aliyuncs.com/higress
Southeast Asia higress-registry.ap-southeast-7.cr.aliyuncs.com/higress

global.imageRegistry affects only subcharts that consume that global value. The Controller, Manager, Workers, Tuwunel, MinIO, and Element Web use their own complete image.repository values. Override every relevant image in a values file when switching regions or using a private registry. See the Kubernetes Deployment Guide and helm/agentteams/values.yaml for the complete configuration.

Access

For a temporary local admin session, forward the Higress Gateway:

kubectl port-forward -n agentteams-system svc/higress-gateway 18080:80

Then open http://localhost:18080 and log in to Element Web. The port-forward ends when the command exits and is not suitable for shared access.

For company or Internet access, expose only svc/higress-gateway through an HTTPS Ingress or LoadBalancer. gateway.publicURL is written into the Element Web configuration as its Matrix homeserver URL, so it must exactly match the public origin that users open (for example, https://agentteams.example.com).

  1. Point the public DNS name at your Ingress controller or load balancer.
  2. Provision a TLS certificate Secret in agentteams-system.
  3. Set the same origin on the Helm release:
helm upgrade agentteams higress.io/agentteams \
  -n agentteams-system --reuse-values \
  --set gateway.publicURL=https://agentteams.example.com
  1. Route that host to the Higress Gateway. This generic example assumes an NGINX IngressClass and an existing agentteams-tls Secret; replace both to match your cluster:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: agentteams
  namespace: agentteams-system
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - agentteams.example.com
      secretName: agentteams-tls
  rules:
    - host: agentteams.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: higress-gateway
                port:
                  number: 80

Verify both the web entry point and Matrix routing after DNS and TLS are ready:

curl -fsS

AgentTeams (agentscope-ai/AgentTeams)

Searching Database…

5.8K ·GitHub
AgentTeams
这是什么？AgentTeams 是一个开源的协作式多智能体运行平台，让多个 AI 智能体在一个可审计的聊天室中协同工作，人类可以随时全程查看并介入。
它是智能体框架，还是管理其他智能体的工具？它本身不实现智能体逻辑，而是一个编排层：由 Manager 智能体通过 Matrix 聊天室运行并协调众多 Worker 智能体容器（OpenClaw、QwenPaw、Hermes 等）。
我该怎么把 AgentTeams 跑起来？在 macOS/Linux 和 Windows 上，只需一条命令即可完成安装（macOS/Linux 使用 curl | bash，Windows 使用 PowerShell 脚本），部署 AI 网关、Matrix 服务器、文件存储、网页客户端和 Manager 智能体；若用于生产环境，则可改用官方 Helm Chart 在 Kubernetes 上部署。
运行之前需要先安装什么？Windows/macOS 需安装 Docker Desktop，Linux 需安装 Docker Engine；至少 2 个 CPU 核心和 4GB 内存；另外还需要在安装向导中填写一个兼容 OpenAI 的 LLM API 密钥。
在依赖它之前，有哪些需要注意的坑？通过 Helm 安装时，默认会执行严格的 LLM 预检。如果你的 API 密钥、Base URL 或模型无法正常使用，安装将失败。此外，Manager 角色无法使用 Hermes 或 DeepSeek Harness 运行时，这两者仅限 Worker 使用。
我的数据和凭证究竟会去哪里？Matrix 是一个去中心化的开放协议，由你自行托管。Worker 智能体只会拿到消费令牌，真正的 API 密钥和 GitHub PAT（个人访问令牌）始终留在网关内部，Worker 和攻击者都无法看到。
skills.sh 是什么？Worker 怎么使用它？skills.sh 是一个社区技能市场，拥有超过 8 万个技能，Worker 可以按需拉取，从而扩展其能力，且无需接触任何真实凭证。
Worker 实际能运行哪些智能体运行时？Worker 可以运行 OpenClaw、QwenPaw、Hermes，或实验性的 DeepSeek Harness，并且不同运行时可以在同一个 Matrix 房间中并存。
为什么选择 Matrix，而不是 Slack 或钉钉？Matrix 是一个开放且可自行托管的协议，因此 AgentTeams 无需经过机器人应用审批，也省去了企业即时通讯集成的繁琐工作，同时你还能在 Element Web 中实时查看每一次智能体对话。
我能不只在自己的笔记本上，而是为整个团队运行 AgentTeams 吗？可以。官方 Helm Chart 内置了 Higress AI 网关、Tuwunel Matrix 服务器、MinIO 存储以及 AgentTeams 控制器，适用于共享或生产环境的 Kubernetes 集群（需要 1.24+ 版本和 Helm 3.7+）。
What are similar projects?evenfire, trueforge, brigade, ruflo, LocalAI, harbor, nomad, openclaw-enterprise
Which topics is it in?agent-os, helm, human-in-the-loop, containers, cloud-native, openclaw, enterprise, openai-compatible, orchestration, kubernetes, multi-agent, agents
Creator
agentscope-ai
Size
21.2 MB
Stars
5.8K
Updated
CommitOct 16Releasev1.2.5Oct 16
Age
7mo
Commits · 90 Days