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: OrbStack, Docker Desktop, Docker Engine, or compatible Podman. If no engine is ready, the installer guides you to install/start one and waits before continuing.

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

Install

macOS / Linux:

bash <(curl -fsSL https://agentteams.cloud/install.sh)

Windows (PowerShell 7+ recommended):

iwr -UseBasicParsing https://agentteams.cloud/install.ps1 | iex

The default command starts the local services and Dashboard without configuration questions. API keys, embedding and Worker runtimes can be configured later. For the interactive setup, add --manual (PowerShell: -Manual).

Access

Dashboard opens automatically at http://127.0.0.1:13000 with admin prefilled and the generated password copied to your clipboard. Paste the password and sign in; if the browser or clipboard is unavailable, use the address and credentials printed in the terminal.

If no model is configured, use the Manager conversation's configuration link to open model management, enter your API key and choose a model. An exported AGENTTEAMS_LLM_API_KEY is preserved. Ask the Manager to create your first Worker and choose its runtime then; Worker images download on demand. See the quickstart for details.

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

Run the same command again and confirm once to keep the original accounts, model settings, data and workspaces. Images are prepared before services are replaced, and the original configuration is backed up. See upgrade instructions for recovery and database backup/rollback options.

# Upgrade to latest (preserves all data)
bash <(curl -fsSL https://agentteams.cloud/install.sh)

# Upgrade to specific version
AGENTTEAMS_VERSION=v1.2.7 bash <(curl -fsSL https://agentteams.cloud/install.sh)

Uninstall

macOS / Linux:

bash <(curl -fsSL https://agentteams.cloud/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://agentteams.cloud/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 Current source chart: openclaw (default), qwenpaw, hermes, deepseek-harness, or openhuman; copaw is a QwenPaw compatibility alias. The Harness image is selected automatically unless overridden
worker.defaultRuntime no openclaw (chart default), qwenpaw, hermes, deepseek-harness, openhuman, or codex; legacy copaw requires an explicitly pinned old 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 (QwenPaw Manager + Hermes Workers)

Run from the root of the current source checkout:

helm dependency build helm/agentteams
helm install agentteams ./helm/agentteams \
  -n agentteams-system --create-namespace \
  --set global.imageTag=v1.2.7 \
  --set manager.runtime=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

The current source chart selects the QwenPaw Harness image automatically. Configure shared Harness images through worker.defaultImage.<runtime> and override manager.image only for custom images. See the Kubernetes guide for chart/image version selection.

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 -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/design/k8s-native-orchestration.md.

How It Works

Manager as Your AI Chief of Staff

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

Security Model

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.

Human in the Loop

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.

Multi-Runtime Collaboration

AgentTeams provides multiple Worker runtime families that can coexist in the same IM room, collaborating on tasks together:

The copaw value remains available for compatibility with existing CoPaw Workers; the current CRD accepts both copaw and qwenpaw. Each runtime excels at different tasks. A common pattern is to use deterministic agents (OpenClaw/QwenPaw) as Leaders to decompose and assign work, and Hermes Workers for autonomous code execution. All runtimes communicate through Matrix rooms—fully visible and fully intervenable.

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

Architecture

┌───────────────────────────────────────────────┐
│            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)
Component Role
agentteams-controller Kubernetes-native control plane, reconciles Worker/Team/Manager CRs
Higress AI Gateway LLM proxy, MCP Server hosting, credential management
Tuwunel (Matrix) Self-hosted IM server for all Agent + Human communication
Element Web Browser client, zero setup
MinIO Centralized file storage, Workers are stateless

AgentTeams vs OpenClaw Native

OpenClaw Native AgentTeams
Deployment Single process Distributed containers
Agent creation Manual config + restart Conversational
Credentials Each agent holds real keys Workers only hold consumer tokens
Human visibility Optional Built-in (Matrix Rooms)
Mobile access Depends on channel setup Any Matrix client, zero config
Monitoring None Manager heartbeat, visible in Room

Documentation

Start with the Dashboard Guide for the v1.4.1 workspace, model setup, teams, files, and Tracing.

Browse the documentation directory, or start with the overview and quickstart:

docs/overview.md Product overview, core concepts, and documentation map
docs/quickstart.md Step-by-step guide
docs/usage/use-cases.md Software delivery, research, content, incident analysis, and long-running project collaboration examples
docs/usage/deployment/local.md Local instance creation, installation options, upgrades, and uninstalling
docs/design/architecture.md System architecture deep dive (also available in 中文)
docs/design/k8s-native-orchestration.md Kubernetes-native multi-Agent orchestration: CRDs, controller, declarative resources (also available in 中文)
docs/usage/manager-guide.md Manager configuration
docs/usage/worker-guide.md Worker deployment
docs/usage/single-and-multi-user.md One deployment for one person or many: roles, permission levels, and what changes when you add people (also available in 中文)
docs/usage/project-workflow-api.md Project / workflow inspection API (also available in 中文)
docs/usage/module-update.md Module update & distribution: Millforge channels, release index, and the three install planes (also available in 中文)
docs/usage/higress-gateway-api.md Higress gateway external API reference (LLM / MCP / exposed ports / Console) (also available in 中文)
docs/usage/development.md Contributing and local dev (also available in 中文)

The remaining design documents (skill catalog, worker channels/chats APIs, room power levels, capability foundation, human update / audit / AI-routes APIs, L2/L3 scoped access, member runtime config contract, team skills, agent pod template, TeamHarness v0.1 boundary) are indexed in the 中文 documentation table — all are also available under docs/zh-cn/design/, except a few (docs/design/internal/, part of docs/design/teamharness/) that are natively written in Chinese upstream.

Troubleshooting

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

See docs/usage/troubleshooting/faq.md for common issues (also available in 中文).

Reporting Bugs

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.

Build & Test

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

Other Commands

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

Community

License

Apache License 2.0

AgentTeams (agentscope-ai/AgentTeams)

agent-teams
Searching Database…

What is this?AgentTeams is an open-source collaborative multi-agent runtime platform that lets multiple AI agents work together in an auditable chat room, with the human fully able to watch and intervene at any point.
Is this an agent framework, or something that manages other agents?It doesn't implement agent logic itself — it's an orchestration layer with a Manager agent that runs and coordinates many Worker agent containers (OpenClaw, QwenPaw, Hermes, etc.) over Matrix chat rooms.
How do I get AgentTeams running?On macOS/Linux and Windows it's a one-command installer (curl | bash, or a PowerShell script on Windows) that stands up the AI gateway, Matrix server, file storage, web client, and Manager agent; for production you can instead deploy it on Kubernetes via the official Helm chart.
What do I need installed before running it?Docker Desktop on Windows/macOS or Docker Engine on Linux, at least 2 CPU cores and 4GB RAM, and an OpenAI-compatible LLM API key entered during the install wizard.
Any gotchas before I rely on this?Helm installs run a strict LLM preflight check by default and will fail if your API key, base URL, or model don't work, and the Manager role can't use the Hermes or DeepSeek Harness runtimes — those are Worker-only.
Where does my data and credentials actually go?Matrix is a decentralized, open protocol you self-host, and Worker agents only ever get consumer tokens — real API keys and GitHub PATs stay inside the gateway, invisible to both Workers and attackers.
What is skills.sh and how do Workers use it?skills.sh is a community marketplace with more than 80,000 skills that Workers can pull on demand, extending what they can do without ever touching real credentials.
What agent runtimes can the Workers actually run on?Workers can run OpenClaw, QwenPaw, Hermes, or the experimental DeepSeek Harness, and different runtimes can coexist side by side in the same Matrix room.
Why build this on Matrix instead of Slack or DingTalk?Matrix is an open, self-hostable protocol, so AgentTeams skips bot-application approvals and enterprise IM integration overhead while letting you watch every agent conversation live in Element Web.
Can I run AgentTeams for a whole team, not just my laptop?Yes — the official Helm chart bundles the Higress AI gateway, Tuwunel Matrix server, MinIO storage and the AgentTeams controller for shared or production Kubernetes clusters (1.24+, Helm 3.7+).
What are similar projects?evenfire, trueforge, ruflo, brigade, harbor, LocalAI, nomad, omnara
Size
27.8 MB
Stars
6K
Age
8mo
Commits · 90 Days