DOCSEARCHbyAlgolia
Submit Docs

AgentTeams Documentation

repository·main·Indexed 26 days ago

https://github.com/agentscope-ai/agentteams

An open-source collaborative multi-agent runtime platform utilizing a Manager-Workers architecture. It enables multiple agents and humans to collaborate within secure, auditable Matrix-based rooms featuring shared file systems. The platform includes support for various worker runtimes such as copaw-worker and hermes-worker, a system for creating and assigning custom Worker Skills, and a Manager Agent for orchestration.

Tokens
182.2K
Snippets
377
Records
947
Agent score
88%

What's inside AgentTeams

  1. Overview of AgentTeams orchestration

    main

    AgentTeams is a declarative orchestration plane designed for multi-Agent collaboration. It functions as a 'collaborative multi-Agent OS' that manages organization, communication policy, delegation, and shared state for teams of autonomous Agents.

    Key architectural principles include:

    • Declarative APIs: Define desired team structures in YAML.
    • Controller Reconcile Loops: A control plane that wires infrastructure and communication topology based on your declarations.
    • Kubernetes-inspired: Uses CRD-style extensions and orchestration patterns to move beyond single-agent runtimes to structured team collaboration.

  2. Overview of AgentTeams

    main

    AgentTeams is an open-source collaborative multi-agent runtime platform designed for controlled and auditable agent collaboration. It uses a Manager-Workers architecture where a Manager agent orchestrates multiple Worker agents within a shared environment.

    Key Features:

    • Manager-Workers Architecture: A Manager agent manages and schedules multiple Worker agents, enabling agent-to-agent orchestration.
    • Multi-Runtime Collaboration: Supports coexistence of different runtimes like OpenClaw, QwenPaw, and Hermes Worker within the same IM (Instant Messaging) room.
    • Shared File System: Uses MinIO for information sharing between agents to reduce token consumption.
    • Secure Gateway: Integrates Higress AI Gateway to manage traffic and protect credentials.
    • Matrix-based Communication: Uses the Matrix real-time communication protocol via Element IM clients and Tuwunel IM servers, allowing humans to monitor, join, and intervene in agent conversations easily.
    • Enterprise Security: Workers use consumer tokens (similar to ID badges) instead of real API keys or GitHub PATs, preventing credential exposure if a worker is compromised.

  3. Overview of HiClaw Agent Runtimes

    main

    HiClaw v1.1.0 supports three primary worker runtimes:

    1. Hermes: An autonomous coding agent designed for complex software tasks. It features a self-improvement loop where it creates reusable 'Skills' and uses FTS5 memory retrieval for cross-session context.
    2. QwenPaw: An upgraded runtime (v1.0.2) used for agent execution.
    3. agent (via openclaw): The standard runtime.

    Architectural Pattern: A common pattern is using a deterministic Manager (using agent/QwenPaw runtime) to handle task decomposition and scheduling, while delegating heavy coding/debugging tasks to a Hermes Worker.

  4. Understand the AgentTeams Three-Tier Organizational Architecture

    main

    AgentTeams uses a three-tier hierarchy to support multi-user collaboration and enterprise team structures:

    1. Admin (Human): Top-level human administrator.
    2. Manager (AI): Manages human resources, top-level task dispatching, and the lifecycle of Teams and Humans. It does not intervene in internal Team coordination.
    3. Team Leader (Special Worker): A specialized Worker that receives tasks from the Manager, decomposes them into sub-tasks, assigns them to Team Workers, and aggregates results.
    4. Team Worker (Worker): Executes sub-tasks and reports back to the Team Leader.
    5. Independent Worker (Worker): Executes tasks directly assigned by the Manager (not part of a Team).
    6. Human Users (Human): Real users who join via Matrix accounts with three permission levels:
      • Level 1: Equivalent to Admin; can interact with all roles.
      • Level 2: Can interact with specific Teams (Leader + Workers) and specific Independent Workers.
      • Level 3: Can only interact with specific assigned Workers.

  5. Understand the relationship between MCP and SKILLS

    main

    In the HiClaw ecosystem, MCP (Model Context Protocol) and SKILLS serve complementary roles:

    • MCP (Model Context Protocol): Provides atomic capabilities. It focuses on standardized tool definitions, rigorous type constraints, and fine-grained permission/credential management. It is used to expose APIs as tools that agents can discover.
    • SKILLS: Provides scenario-oriented capability packages. SKILLS combine atomic tools (often orchestrated via mcporter) into complete, evolving business workflows that include knowledge accumulation and best practices.

    Workflow Pattern: MCP Tools (Atomic Capabilities) $\rightarrow$ mcporter orchestration $\rightarrow$ SKILLs (Scenario-based Capability Packages)

  6. Understand AgentTeams Deployment Modes

    main

    AgentTeams supports two primary deployment architectures depending on your environment:

    1. K8s Incluster Mode: Designed for native Kubernetes environments. The agentteams-controller runs as a standard Deployment, managing resources via CRDs (Worker, Team, Human, Manager, DebugWorker) and utilizing a Worker Backend abstraction layer (K8s/Docker/Cloud). This mode is recommended for production scalability and uses Helm for installation/upgrades.

    2. Embedded Mode (Backward Compatible): Designed for single-container or simplified environments. In this mode, the agentteams-controller runs as an independent container that manages Worker containers directly via a Docker Backend (replacing the old docker-proxy). It includes an embedded kube-apiserver and kine (using SQLite) to provide a K8s API compatibility layer.

  7. Understand the Member Runtime Config Contract

    main

    The Member Runtime Config Contract defines the YAML configuration snapshot that the AgentTeams controller writes to object storage for managed runtime members. Managed runtime workers (like qwenpaw-worker) and TeamHarness plugin adapters consume this file to obtain team and member facts, rather than querying the agt CLI directly.

    Key Characteristics:

    • Non-Secret Data Only: The config carries desired state and team facts. It does not contain secrets. Secrets must be provided via environment variables, mounted files, or service account tokens.
    • Polling Mechanism: The qwenpaw worker polls this file to detect changes and apply updated model, AgentSpec package, MCP, channel, and team context configurations without requiring a pod restart.
    • AgentSpec vs. Plugin: desired.agentPackage refers to the user-deployed AgentSpec package (the business capability bundle), which is distinct from the TeamHarness plugin (the runtime infrastructure).

  8. Understand AgentTeams v1.1.0+ architecture

    main

    Starting with v1.1.0, AgentTeams uses a multi-container architecture managed by agentteams-controller.

    Key components include:

    • agentteams-controller: Contains the Controller and all infrastructure services (Higress, Tuwunel, MinIO, Element Web).
    • agentteams-manager: A lightweight container running the Manager Agent.
    • agentteams-worker-*: Worker containers created on demand.

    Supported worker runtimes are OpenClaw (Node.js), QwenPaw (Python; formerly CoPaw), and Hermes.

  9. Understand HiClaw Manager capabilities

    main

    The HiClaw Manager acts as the central orchestrator for your AI team. It automates the lifecycle of a project through the following roles:

    PhaseManager's role
    Project planningBreaks goals into tasks and identifies dependencies
    Task assignmentUses @mentions to assign Workers with specific task context
    Progress trackingUpdates the project plan upon task completion and triggers subsequent steps
    Issue handlingAutomatically creates revision tasks if a review fails (e.g., status REVISION_NEEDED)
    Status reportingProactively provides updates at key milestones
    Risk flaggingMonitors data/metrics to spot anomalies and suggest optimizations

  10. Understand the HiClaw Architecture

    main

    HiClaw is an evolution of OpenClaw that introduces a Manager Agent (AI Chief of Staff) to manage a team of Worker Agents. Unlike the original OpenClaw where LLM providers and communication channels are external configurations, HiClaw integrates these as built-in components:

    • Manager Agent: Orchestrates tasks and manages Worker Agents (e.g., Worker Alice for frontend, Worker Bob for backend) without performing the work directly.
    • Higress AI Gateway: Acts as the centralized brain access point. It allows switching between LLM providers (Alibaba Cloud Qwen, OpenAI, Claude, etc.) through a single endpoint and manages credentials centrally so Workers never touch raw API keys.
    • Tuwunel Matrix Server: Provides the communication layer (sensory organs) with zero configuration. It includes Element Web as a built-in UI and supports mobile clients like Element and FluffyChat.

  11. Understand TeamHarness Runtime Integration Architecture

    main

    The TeamHarness integration follows a Test-Driven Development (TDD) approach to separate concerns between plugins, workers, and runtime adapters.

    Key Responsibility Boundaries:

    • TeamHarness Plugin: Provides runtime-neutral team collaboration capabilities (prompts, skills, MCP tools). It does not handle worker lifecycle, desired-state apply loops, or runtime configuration reading.
    • Worker (e.g., QwenPaw Worker): Manages the lifecycle, storage recovery, a 5-second desired-state apply loop, and runtime heartbeat reporting. It reads runtime.yaml to apply changes to models, MCP, channels, and AgentSpec packages.
    • Runtime Adapter (e.g., QwenPaw/Claude Code Adapter): Bridges the TeamHarness plugin assets (prompts, skills, MCP) into the specific runtime. It handles runtime-specific wrappers, context installation, and output sanitization.
    • AgentSpec Package: Managed by the worker's desired-state loop. Updates to desired.agentPackage (version or digest) trigger the worker to pull and apply the package without restarting the runtime process.

  12. Understand the AgentTeams Multi-container Layout

    main

    The default embedded installation (v1.1.0+) starts two primary containers:

    1. agentteams-controller: The core infrastructure bundle. It includes Higress (gateway), Tuwunel, MinIO (storage), Element Web (IM client), and the Go controller (REST API on port 8090 inside the Docker network).
    2. agentteams-manager: The lightweight Manager Agent. Depending on the AGENTTEAMS_MANAGER_RUNTIME setting, it runs either OpenClaw or QwenPaw.

    Worker containers (agentteams-worker-*, agentteams-copaw-worker-*, agentteams-hermes-worker-*) are provisioned dynamically when you add Workers.