English | 中文 | 日本語

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

• 🧬 Manager-Workers Architecture: Eliminates the need for human oversight of individual Worker Claws by enabling Agents to manage other Agents.

• 🤝 Multi-Runtime Collaboration: OpenClaw, QwenPaw, and Hermes Workers coexist in the same IM room. Use deterministic agents (OpenClaw/QwenPaw) as Leaders to orchestrate tasks, and Hermes Workers for autonomous code execution — each runtime does what it's best at.

• 📦 MinIO Shared File System: Introduces a shared file system for inter-Agent information exchange, significantly reducing token consumption in multi-Agent collaboration scenarios.

• 🔐 Higress AI Gateway: Centralizes traffic management and mitigates credential-related risks, alleviating user concerns about security vulnerabilities in the native Lobster framework.

• ☎️ Element IM Client + Tuwunel IM Server (both Matrix protocol-based): Eliminating DingTalk/Lark integration overhead and enterprise approval workflows. Enables rapid user onboarding to experience the "delight" of model services within an IM environment, while maintaining compatibility with native OpenClaw IM integration.

• 🧬 Integrate AgentLoop ：Provides capabilities such as full-stack Agent observability and auditing, Agent evaluation and experimentation, and Agent asset management and continuous optimization.

• 2026-07-17: Release Notes — AgentTeams v1.2.0-beta.1 (prerelease): completes the public rename from the retired predecessor across images, Kubernetes APIs, Helm, Matrix, storage, and runtime contracts; adds the plugin platform, TeamHarness and WorkerFlow integrations, Matrix AppService and Human SSO, model-provider routing and LLM preflight, plus richer controller observability. Beta installation requires explicit opt-in, while the stable default remains v1.1.2.
• 2026-05-27: Release Notes — AgentTeams v1.1.2: QwenPaw-first installer with keep-all upgrade flow, Team human coordinators and refreshed Team Leader coordination tools, Nacos remote skills with sts-agentteams / ai-registry STS scope, Worker CR-name decoupled from runtime name, controller reconcile metrics and graceful shutdown.
• 2026-05-07: Release Notes | Changelog — AgentTeams v1.1.1: declarative MCP on Worker/Manager/Team CRDs (breaking) and on Team Leader, custom spec.env for CRs, Token Plan + Qwen Cloud international + qwen3.6-plus, namespace-scoped controller RBAC, optional SOUL.md in Worker packages.
• 2026-04-24: English | 中文 — AgentTeams v1.1.0: Kubernetes-native control plane, Hermes autonomous coding agent runtime, 1.7 GB image shrink, agt CLI replaces shell scripts.
• 2026-04-14: English | 中文 — Deep dive: AgentTeams as a Kubernetes-native multi-agent collaboration orchestration system.
• 2026-04-03: English | 中文 — AgentTeams 1.0.9: Kubernetes-style declarative resource management (YAML for Worker, Team, Human); Worker Template Marketplace; Manager QwenPaw runtime; Nacos Skills Registry and more.
• 2026-03-14: English | 中文 — AgentTeams 1.0.6: enterprise-grade MCP Server management, zero credential exposure.
• 2026-03-10: English | 中文 — AgentTeams 1.0.4: QwenPaw (formerly CoPaw) Worker support, 80% less memory.
• 2026-03-04: English | 中文 — AgentTeams open sourced under its former name.

• Enterprise-Grade Security: Worker Agents operate with consumer tokens only. Real credentials (API keys, GitHub PATs) stay in the gateway — Workers can't see them, and neither can attackers.

• Fully Private: Matrix is a decentralized, open protocol. Host it yourself, federate with others if you want. No vendor lock-in, no data harvesting.

• Human-in-the-Loop by Default: Every Matrix room includes you, the Manager, and the relevant Workers. Watch everything. Jump in anytime. No black boxes.

• Zero Configuration IM: Built-in Matrix server means no bot applications, no API approvals, no waiting. Just open Element Web and start chatting.

• One Command Setup: curl | bash and you're done — AI gateway, Matrix server, file storage, web client, and Manager Agent.

• Skills Ecosystem: Workers pull from skills.sh (80,000+ community skills) on demand. Safe because Workers can't access real credentials.

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.

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

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 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.0.5 bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh)

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.

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.

Prerequisites

• Kubernetes 1.24+ (kind / minikube / k3s / managed K8s — all work)
• Helm 3.7+
• A default StorageClass (for the Tuwunel + MinIO PVCs)

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

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

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

helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace --devel \
  --set manager.runtime=copaw \
  --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

Multi-Region Image Registry

The default global.imageRegistry points to the China region (higress-registry.cn-hangzhou.cr.aliyuncs.com/higress). If you are deploying outside China, override it for faster image pulls:

# Example: deploy from the North America registry
helm install agentteams higress.io/agentteams \
  -n agentteams-system --create-namespace \
  --render-subchart-notes \
  --set global.imageRegistry=higress-registry.us-west-1.cr.aliyuncs.com/higress \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080

For all configurable values (gateway/storage providers, image tags, resources, persistence, etc.) see helm/agentteams/values.yaml.

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

4. 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 -fsSI https://agentteams.example.com/
curl -fsS https://agentteams.example.com/_matrix/client/versions

Keep the controller API, Tuwunel, MinIO, and the Higress Console private unless you apply separate authentication and network policy. Use HTTPS for shared access because Matrix login credentials and access tokens pass through this endpoint. A LoadBalancer Service can replace the Ingress, but the DNS, TLS, and gateway.publicURL requirements remain the same.

Upgrade

helm repo update
helm upgrade agentteams higress.io/agentteams -n agentteams-system --reuse-values

Uninstall

helm uninstall agentteams -n agentteams-system
kubectl delete namespace agentteams-system

For the Kubernetes-native architecture (CRDs, controller, declarative Worker / Team / Human resources), see docs/k8s-native-agent-orch.md.

You: Create a Worker named alice for frontend development

Manager: Done. Worker alice is ready.
         Room: Worker: Alice
         Tell alice what to build.

You: @alice implement a login page with React

Alice: On it... [a few minutes later]
       Done. PR submitted: https://github.com/xxx/pull/1

_{① Manager creates a Worker and assigns tasks                    ② You can also direct Workers directly in the room}

Worker (consumer token only)
    → Higress AI Gateway (holds real API keys, GitHub PAT)
        → LLM API / GitHub API / MCP Servers

Workers see only their consumer token. The gateway handles all real credentials. The Manager knows what Workers are doing but never touches the actual keys.

Every Matrix Room includes you, the Manager, and relevant Workers:

You: @bob wait, change the password rule to minimum 8 chars
Bob: Got it, updated.
Alice: Frontend validation updated too.

No hidden agent-to-agent calls. Everything is visible and intervenable.

AgentTeams supports three Worker runtimes that can coexist in the same IM room, collaborating on tasks together:

• OpenClaw (Node.js) — General-purpose agent with rich skills ecosystem, ideal for task orchestration and tool calling
• QwenPaw (Python) — Lightweight runtime, suited for browser automation and quick tasks
• Hermes (hermes-agent) — Autonomous coding agent with terminal sandbox, self-improving skills, and persistent memory

Each runtime excels at different tasks. A common pattern: use deterministic agents (OpenClaw/QwenPaw) as Leaders to decompose and assign work, and Hermes Workers for autonomous code execution. All runtimes communicate via Matrix m.mentions in the same room — fully visible, fully intervenable.

# Switch any worker's runtime in place
agt update worker --runtime hermes

┌───────────────────────────────────────────────┐
│            agentteams-controller                  │
│  Higress │ Tuwunel │ MinIO │ Element Web      │
└──────────────────┬────────────────────────────┘
                   │ Matrix + HTTP Files
┌──────────────────┴──────────┐
│     agentteams-manager-agent     │
│     Manager (OpenClaw/       │
│       QwenPaw)               │
└──────────────────┬──────────┘
                   │
┌──────────────────┼────────────────────────────┐
│                  │                            │
▼                  ▼                            ▼
Worker Alice    Worker Bob              Worker Charlie
(OpenClaw)      (QwenPaw)               (Hermes)

docker exec -it agentteams-manager cat /var/log/agentteams/manager-agent.log

See docs/zh-cn/faq.md for common issues.

Export your Matrix message logs and let an AI tool analyze them against the codebase before filing an issue — this helps us fix bugs much faster.

# Export debug logs (Matrix messages + agent sessions, PII auto-redacted)
python scripts/export-debug-log.py --range 1h

Then open the AgentTeams repo in Cursor, Claude Code, or similar AI tool and ask:

"Read the JSONL files in debug-log/. Analyze the Matrix message logs and agent session logs together. Cross-reference with the AgentTeams codebase to identify the root cause of [describe your bug]."

Include the AI's analysis in your bug report.

You can also let the AI tool submit the issue or PR directly. Install GitHub CLI, run gh auth login to authenticate in your browser, then add the OpenClaw GitHub skill to your AI coding tool (Cursor, Claude Code, etc.). After that, just ask it to file the issue or open a PR based on its analysis.

make build          # Build all images
make test           # Build + run all integration tests
make test-quick     # Smoke test only

make replay TASK="Create a Worker named alice for frontend development"
make uninstall
make help

• Discord
• GitHub Issues

Apache License 2.0