① 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: - **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](https://github.com/NousResearch/hermes-agent)) — Autonomous coding agent with terminal sandbox, self-improving skills, and persistent memory - **DeepSeek Harness** (experimental) — Headless coding agent with room-scoped session continuation, Matrix file exchange, and restart recovery; currently pinned to a tested DSH release candidate 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. ```bash # Switch any worker's runtime in place agt update worker --runtime hermes ``` Harness implementations are maintained in independent `agentteams-group` repositories: [OpenClaw](https://github.com/agentteams-group/agentteams-harness-openclaw), [QwenPaw](https://github.com/agentteams-group/agentteams-harness-qwenpaw), [Hermes](https://github.com/agentteams-group/agentteams-harness-hermes), [DeepSeek](https://github.com/agentteams-group/agentteams-harness-deepseek), [OpenHuman](https://github.com/agentteams-group/agentteams-harness-openhuman), [Codex](https://github.com/agentteams-group/agentteams-harness-codex). Core pins their source revisions for builds. ## 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](docs/usage/dashboard.md) for the v1.4.1 workspace, model setup, teams, files, and Tracing. Browse the [documentation directory](docs/), or start with the overview and quickstart: | | | |---|---| | [docs/overview.md](docs/overview.md) | Product overview, core concepts, and documentation map | | [docs/quickstart.md](docs/quickstart.md) | Step-by-step guide | | [docs/usage/use-cases.md](docs/usage/use-cases.md) | Software delivery, research, content, incident analysis, and long-running project collaboration examples | | [docs/usage/deployment/local.md](docs/usage/deployment/local.md) | Local instance creation, installation options, upgrades, and uninstalling | | [docs/design/architecture.md](docs/design/architecture.md) | System architecture deep dive (also available in [中文](docs/zh-cn/design/architecture.md)) | | [docs/design/k8s-native-orchestration.md](docs/design/k8s-native-orchestration.md) | Kubernetes-native multi-Agent orchestration: CRDs, controller, declarative resources (also available in [中文](docs/zh-cn/design/k8s-native-orchestration.md)) | | [docs/usage/manager-guide.md](docs/usage/manager-guide.md) | Manager configuration | | [docs/usage/worker-guide.md](docs/usage/worker-guide.md) | Worker deployment | | [docs/usage/single-and-multi-user.md](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/zh-cn/usage/single-and-multi-user.md)) | | [docs/usage/project-workflow-api.md](docs/usage/project-workflow-api.md) | Project / workflow inspection API (also available in [中文](docs/zh-cn/usage/project-workflow-api.md)) | | [docs/usage/module-update.md](docs/usage/module-update.md) | Module update & distribution: Millforge channels, release index, and the three install planes (also available in [中文](docs/zh-cn/usage/module-update.md)) | | [docs/usage/higress-gateway-api.md](docs/usage/higress-gateway-api.md) | Higress gateway external API reference (LLM / MCP / exposed ports / Console) (also available in [中文](docs/zh-cn/usage/higress-gateway-api.md)) | | [docs/usage/development.md](docs/usage/development.md) | Contributing and local dev (also available in [中文](docs/zh-cn/usage/development.md)) | 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](README.zh-CN.md) — 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 ```bash docker exec -it agentteams-manager cat /var/log/agentteams/manager-agent.log ``` See [docs/usage/troubleshooting/faq.md](docs/usage/troubleshooting/faq.md) for common issues (also available in [中文](docs/zh-cn/usage/troubleshooting/faq.md)). ### 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. ```bash # 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](https://github.com/agentscope-ai/AgentTeams/issues/new?template=bug_report.yml). You can also let the AI tool submit the issue or PR directly. Install [GitHub CLI](https://cli.github.com/), run `gh auth login` to authenticate in your browser, then add the [OpenClaw GitHub skill](https://github.com/openclaw/openclaw/blob/main/skills/github/SKILL.md) 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 ```bash make build # Build all images make test # Build + run all integration tests make test-quick # Smoke test only ``` ## Other Commands ```bash make replay TASK="Create a Worker named alice for frontend development" make uninstall make help ``` ## Community - [Discord](https://discord.gg/NVjNA4BAVw) - [GitHub Issues](https://github.com/agentscope-ai/AgentTeams/issues) ## License Apache License 2.0