Skip to content

overview.md

Latest commit

 

History

History
122 lines (88 loc) · 7.59 KB

overview.md

File metadata and controls

122 lines (88 loc) · 7.59 KB
Raw

AgentTeams Overview

English | 中文

AgentTeams is a multi-agent collaboration system with humans in the loop. You interact with a Manager through a familiar instant-messaging interface. The Manager can create and organize Workers with different capabilities, break down tasks, track progress, and coordinate multiple agents in shared context.

AgentTeams uses Matrix for communication between humans and agents, Higress as the unified gateway for model and MCP traffic, and shared object storage for agent configuration, task context, and artifacts. A controller manages the creation, update, and deletion of agents.

When to use AgentTeams

AgentTeams is a good fit when you want to:

  • Coordinate specialized Workers for frontend, backend, testing, research, or other roles.
  • Let a Manager break down and track longer-running project work.
  • Add requirements, inspect progress, or take over while agents are working.
  • Control access to models, MCP tools, and external credentials through a unified gateway.
  • Start on a local machine and later deploy a shared instance on Kubernetes.

If you only need a one-off conversation with a single agent and do not need role separation, shared task space, or human oversight, a standalone agent tool is usually simpler.

Core roles

Role Responsibility
Human Sets goals through a Matrix client, observes the full collaboration, and can intervene at any time.
Manager Understands goals, creates or selects Workers, delegates work, tracks progress, and consolidates results.
Worker Executes focused tasks. Each Worker can have its own role, model, runtime, Skills, and MCP configuration.
Team Packages multiple Workers and a Team Leader into a reusable collaboration unit.
Team Leader Coordinates Team members, maintains team context, and moves collaborative work forward.

System components

Component Purpose
agentteams-controller Manages Worker, Manager, Team, and Human resources, agent lifecycles, and related infrastructure configuration.
Matrix / Tuwunel Carries visible communication among Humans, Managers, Workers, and Team Leaders.
Element Web The default Matrix web client. Other compatible Matrix clients can also be used.
Higress Acts as the AI/API gateway for LLM and MCP traffic, identity, and access control.
MinIO or compatible object storage Stores agent workspaces, configuration, shared task context, and artifacts.
Manager and Worker containers/Pods Run the agent runtimes. They are separated from infrastructure and can be created or replaced on demand.

See Architecture for detailed component relationships and data flows.

How collaboration works

  1. A Human describes a goal to the Manager in Matrix.
  2. The Manager decides whether to use an existing Worker, create a Worker, or organize a Team.
  3. The controller prepares the agent's Matrix identity, gateway permissions, shared storage configuration, and runtime environment.
  4. The Manager delegates work to a Worker or Team and tracks progress in Matrix rooms.
  5. Workers use models, Skills, and authorized MCP tools, and write shared context and artifacts to object storage.
  6. The Human can add requirements, correct the direction, or approve decisions during execution.
  7. The Manager consolidates the results and reports back to the Human.

All important communication happens in Matrix rooms, so humans can see how work is decomposed, delegated, and completed.

Two deployment modes

Local deployment Kubernetes deployment
Best for Personal evaluation, development, and single-machine use Shared teams, long-running environments, and production deployments
Infrastructure One embedded controller container runs Higress, Tuwunel, MinIO, Element Web, and the controller Components run as Kubernetes workloads or external services
Agent runtime Manager and Workers run in separate containers Manager and Workers run in separate Pods
Lifecycle management The controller manages agents through Docker or Podman The controller manages agents through Kubernetes CRDs
Installation entry point install/agentteams-install.sh The helm/agentteams Helm chart

For a first evaluation, start with the local path in Quickstart. For a shared or production environment, see the Kubernetes Deployment Guide.

Agent runtimes

Manager currently supports:

  • CoPaw: the current QwenPaw-based Python Manager implementation; the canonical value is qwenpaw, while the local installer still uses copaw as a compatibility alias.
  • OpenClaw: a Node.js runtime.

Worker resources support the following runtimes. Available images depend on the installation method and version:

  • OpenClaw
  • CoPaw
  • QwenPaw
  • Hermes

The Controller and Helm values already contain an OpenHuman backend and image configuration, but the shipped Worker CRD enum does not yet accept an explicit spec.runtime: openhuman. Until a separate business-code change aligns that contract, do not treat OpenHuman as a directly declarable Worker runtime.

The runtime selects the agent framework and image, while AgentTeams manages the Worker's identity, Matrix rooms, and persistent data. Switching runtimes normally recreates the Worker environment and should not be done while the Worker is executing a task.

Resources and management interfaces

AgentTeams models the system through four declarative resources: Worker, Manager, Team, and Human. You can manage them by:

  • Sending natural-language requests to the Manager in Matrix.
  • Using the agt CLI inside the controller or Manager container.
  • Applying YAML manifests with agt apply -f.
  • Managing AgentTeams CRDs directly on Kubernetes.

See Declarative Resource Management for fields and operations.

Security model

  • Workers do not need direct access to real model or MCP service keys.
  • Higress uses separate identities and consumer credentials to control model and tool access.
  • Matrix rooms retain a visible collaboration timeline for Humans, Managers, and Workers.
  • Agent configuration and persistent data live in centralized object storage, so Worker environments can be replaced.
  • Kubernetes deployments can integrate with existing gateways, object storage, and credential providers.

Production deployments should also use HTTPS, network policies, least-privilege access, Secret management, backups, and auditing.

Where to go next

Goal Document
Complete the first task locally Quickstart
Explore reusable multi-agent workflows AgentTeams Use Cases
Review every local installation option Local Deployment Guide
Deploy a shared instance on Kubernetes Kubernetes Deployment Guide
Understand components and communication Architecture
Configure and operate the Manager Manager Guide
Create, deploy, and maintain Workers Worker Guide
Install Skills on an existing Worker Worker Guide: Installing Skills
Manage resources with YAML and agt Declarative Resource Management
Install on Windows Windows Deployment
Troubleshoot common problems FAQ
Contribute to the project Development Guide