AgentTeams: a Manager-Workers multi-agent runtime that lives in Matrix rooms

The coordination problem AgentTeams is aimed at

Most agent frameworks stop at the single agent. You write a loop, give it tools, and it runs. The moment two agents need to hand work to each other, you end up writing your own message bus, your own retry logic, and your own way for a human to see what happened. AgentTeams exists to remove that work. The README describes it as "an open-source collaborative multi-agent runtime platform" that lets multiple agents collaborate "in a controlled and auditable room, with full human visibility and intervention capabilities throughout the process."

The audience is narrow and specific. The README frames it around "collaboration scenarios between humans and Agents, as well as among Agents within enterprise environments." That means platform teams, not solo developers. The project also states plainly that it "does not compete with other Agent runtimes. Instead of implementing Agent logic itself, it orchestrates and manages multiple Agent containers." That sentence is the whole design thesis: AgentTeams is a control plane, not an agent SDK. If you arrived looking for a library to embed in your Go binary, you are in the wrong repository.

Manager-Workers, Matrix rooms, and shared files

The architecture is a Manager-Workers split. A Manager orchestrates multiple Workers, and the README's stated benefit is that this "eliminates the need for human oversight of individual Worker Claws by enabling Agents to manage other Agents." Each agent runs as a container. The Manager and the Workers are separate images, which is visible in the Makefile: agentteams-manager, agentteams-worker, agentteams-qwenpaw-worker, agentteams-hermes-worker, agentteams-copaw-worker, and agentteams-manager-qwenpaw are all built from the same file.

Coordination happens over Matrix. The README pairs "Element IM Client + Tuwunel IM Server (both Matrix protocol-based)" and says this removes DingTalk or Lark integration overhead and enterprise approval workflows. Practically, that means every agent conversation is a room event, which is where the auditability comes from: the room is the log. Release v1.2.2 notes that "Team Leaders and Workers explicitly join Team Rooms after invitation," so room membership is a managed step rather than an assumption.

Inter-agent data exchange goes through a MinIO shared file system. The README claims this "significantly reducing token consumption in multi-Agent collaboration scenarios." That is a plausible mechanism, since passing a file reference costs fewer tokens than pasting content into a prompt, but the README gives no measurement, so treat the size of the saving as unverified. A Higress AI Gateway sits in front of model traffic for "centralizes traffic management" and credential risk reduction. The runtime is pluggable: OpenClaw, QwenPaw, Hermes, and an experimental DeepSeek Harness Worker can coexist in the same room.

Installing AgentTeams and running a first team

The README does not carry a step-by-step quickstart. It points at the repository's install/ directory, the helm/ directory, and the Makefile, so installation is a Kubernetes and Helm exercise rather than a package install. The Makefile documents the local path first. Its usage comment lists a build target that builds all images for the native architecture, and notes the file is used locally and in CI/CD.

make build

That builds Manager and Worker images locally. To check what is running afterwards, the Makefile usage comment lists a status target that shows the status of the Manager and all Worker containers, and a logs target for recent logs.

make status
make logs

For registry work the Makefile usage comment lists two push targets: push builds and pushes multi-architecture images for amd64 and arm64, while push-native pushes native-architecture images only and is annotated as dev use, not recommended for registry. Image coordinates default to the higress-registry.cn-hangzhou.cr.aliyuncs.com registry under the agentteams repository, with the VERSION variable defaulting to latest.

make push

The release notes describe the deployment surface as Kubernetes APIs, Helm, and Matrix contracts, and v1.2.0-beta.1 mentions "Matrix AppService and Human SSO" plus "model-provider routing and LLM preflight." The README does not document the Helm values schema, so the exact chart keys have to come from the helm/ directory itself. Note one upgrade trap the release notes make explicit: v1.2.0's installer supports deploying v1.1.2 with its legacy environment and storage contract, and "earlier releases still require the matching legacy installer." Installer and release version are coupled.

Where AgentTeams is the wrong tool

The clearest limitation is operational weight. Running AgentTeams means running Kubernetes, a Matrix homeserver (Tuwunel), a MinIO instance, and a Higress gateway, plus at least one Manager container and one Worker container per agent. For a two-agent prototype on a laptop, that is a large amount of infrastructure to stand up before the first useful output. A single-process agent library will get you to a working demo faster, and AgentTeams deliberately does not try to win that comparison.

The second limitation is that the project's own documentation is uneven. The README is a feature list and a news feed; it does not document rollback, does not document the Helm values, and does not give a quickstart. The upgrade story is described in release notes as a "keep-all upgrade flow" for v1.1.2, but there is no corresponding downgrade procedure in the README. If your environment requires tested rollback, that gap is a real risk, not a documentation nit.

Third, the runtime stack has moved. v1.2.1 "unifies the Manager and Worker runtime stack on QwenPaw 2.0.1," and v1.2.3 "promotes QwenPaw as the recommended local Manager and Worker runtime." Older releases carried CoPaw, and v1.2.1 adds "CoPaw-to-QwenPaw state migration." Anyone with an existing CoPaw deployment inherits a migration step. Finally, the DeepSeek Harness Worker is labelled experimental in the README, so it should not carry production coordination work.

AgentTeams compared with a subagent-style workflow

The most common alternative is the subagent model found in coding assistants, where one orchestrating model spawns short-lived helper agents inside a single process. The difference is where state lives. A subagent call is ephemeral: the parent holds the context, the child returns a result, and nothing survives the process. AgentTeams inverts that. Workers are containers with their own lifecycle, the conversation is persisted as Matrix room events, and files move through MinIO. You get durability and a readable transcript at the cost of a control plane to operate.

The second alternative is a general workflow orchestrator such as a DAG engine or a queue-based pipeline. Those give you deterministic scheduling and retries, and they are the better choice when the steps are known in advance. AgentTeams is built for the case where the steps are not known in advance and a model decides them, with a human able to step in mid-flight. If your pipeline is a fixed sequence of calls, a DAG engine is simpler and cheaper. If your pipeline is a conversation that needs to be auditable, AgentTeams is aimed at exactly that. The README's own framing supports this: it orchestrates agent containers rather than implementing agent logic, so it layers on top of whatever runtime you already trust.

Maintenance cadence, licence, and upgrade cost

The last push to the default branch was on 2026-09-20, two days before this writing, and the repository is not archived. Release cadence is rapid: v1.2.1 on 2026-08-06, v1.2.2 on 2026-08-08, and v1.2.3 on 2026-08-22, which is three releases in sixteen days. That pace cuts both ways. Fixes arrive quickly, and so do contract changes. v1.1.1 introduced "declarative MCP on Worker/Manager/Team CRDs (breaking)," and v1.2.0-beta.1 completed "the public rename from the retired predecessor across images, Kubernetes APIs, Helm, Matrix, storage, and runtime contracts." Budget for reading changelog entries before each upgrade rather than assuming compatibility.

The licence is Apache-2.0, which permits commercial use, modification, and redistribution, and includes an explicit patent grant. It also requires that you preserve copyright and licence notices and state significant changes. This is a summary of the licence text, not legal advice; the LICENSE file in the repository is the authoritative document, and your own counsel should review anything you redistribute. One practical implication: the images default to a registry under aliyuncs.com, so confirm your network and procurement rules allow pulling from it, or plan to build and host the images yourself with the Makefile's push target.

Editorial conclusion

Adopt AgentTeams if you already run Kubernetes and need multiple agent runtimes (QwenPaw, OpenClaw, Hermes, experimental DeepSeek Harness) collaborating in one auditable Matrix room with human intervention. Do not adopt it if you want a single-process agent library, cannot operate a Matrix homeserver, or need a documented rollback path: the README documents upgrades, not downgrades. Before committing, verify the installer's default target version against the release you intend to run, and confirm which Worker images your registry can pull.

Frequently asked questions

Official sources

1. agentscope-ai/AgentTeams on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases