Content
<p align="center">
<h1 align="center">Agent Team</h1>
<p align="center">
<strong>Loop Engineering Engine — Let AI Agent Teams Deliver Verifiable Software</strong>
</p>
<p align="center">
<a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
<a href="https://github.com/PandaKing2021/loop-studio"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
</p>
</p>
---
**Agent Team** is an open-source Loop Engineering engine - you use it to build AI Agent teams, give the team a goal, and the Agents autonomously complete demand analysis, task decomposition, coding, Code Review, test verification, and knowledge precipitation, delivering verifiable and runnable software.
Unlike mainstream multi-Agent frameworks, the core design philosophy of Agent Team is **"Write is not the end, verification is the end"**. Each subtask must go through a structured review by an independent Reviewer, and each delivery must pass a quality gate check. This is not a Demo - it has been verified by 196 systematic tests, and can run on your project, your server, or even your friend's computer (via SSH remote execution).
---
## Table of Contents
- [Why Choose Agent Team](#why-choose-agent-team)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [Key Capabilities](#key-capabilities)
- [Architecture Design](#architecture-design)
- [Protocol and Ecology](#protocol-and-ecology)
- [External Agent Access](#external-agent-access)
- [CLI Command Line](#cli-command-line)
- [Deployment](#deployment)
- [Documentation](#documentation)
- [Test Coverage](#test-coverage)
- [Project Structure](#project-structure)
- [Technical Stack](#technical-stack)
- [Roadmap](#roadmap)
- [Contribution Guide](#contribution-guide)
- [License](#license)
---
## Why Choose Agent Team
### Problems We Solve
Current multi-Agent frameworks perform impressively in demos, but when applied to real projects, they expose common issues:
| Pain Point | Typical Performance | Agent Team's Solution |
|------------|--------------------|----------------------|
| **No Real Verification** | Agent writes code and says "no problem" and it's over | **Verify-Separation**: Independent Reviewer + Tester separation review, forced to run tests |
| **Context Fracture** | Running to the fourth subtask and forgetting the original requirements | **Three-Layer Memory System**: recent full text + distant summary + shared blackboard, persistent and not lost |
| **Parallel Conflict** | Multiple Agents share workspace, writing and covering each other | **Git Worktree Isolation**: each Agent independent work copy + automatic merge |
| **No Recovery Capability** | Intermediate step fails, all progress is discarded | **Breakpoint Recovery**: subtask-level transaction persistence, restart from the unfinished step |
| **Limited Delivery Boundary** | Agent can only run on local development machine | **5 Execution Backends**: SSH remote, Docker, K8s, local, remote service |
### Differentiation Positioning Compared to Mainstream Frameworks
| Dimension | LangGraph | CrewAI | MetaGPT | **Agent Team** |
|------------|-----------|--------|---------|----------------|
| Loop Engineering | Part | None | Part | **Complete Closed Loop** |
| Verify-Separation | None | None | Weak | **Mandatory Independent Review** |
| Quality Gate | None | None | None | **5 Dimensions Go/No-Go** |
| External Agent Dual-Role Access | None | None | None | **Employee + Brain Two Identities** |
| Remote SSH Deployment Execution | None | None | None | **Real and Available** |
| Engine First (No HTTP Dependency) | None | None | None | **`import` and Go** |
| MCP + A2A Dual Protocol | None | None | None | **Complete Implementation** |
| Skill Constraint System | None | None | None | **Markdown Document is Ability** |
---
## Quick Start
### Environmental Requirements
- **Node.js** ≥ 18 (recommended 20+)
- **npm** ≥ 10
- **Git**
- A **LLM API Key** (support DeepSeek, OpenAI, Anthropic, Gemini, and any OpenAI compatible interface)
### Three Steps to Get Started
```bash
# 1. Clone and Install
git clone https://github.com/PandaKing2021/loop-studio.git
cd loop-studio
npm run install:all
# 2. Configure API Key
cp .env.example .env
# Edit .env and fill in DEEPSEEK_API_KEY or LLM_API_KEY
# 3. Start
npm run dev
```
Open the browser to access `http://localhost:5173`:
1. Enter **Settings** → Configure model provider
2. Enter **Team Template** → Select "Engineering Delivery Team"
3. **New Team** → Bind workspace → **Issue Mission** → **Start**
4. View the execution process of Agents in real-time on the **Team Details** page
> **Don't Want to Use the Web Interface?** The engine can be directly imported, or you can operate purely through CLI:
> ```bash
> node src/cli.js list # View team
> node src/cli.js team mission <id> --goal "Implement User Login" # Issue mission
> node src/cli.js team run <id> --watch # Execute and observe
> ```
> See [ENGINE.md](ENGINE.md) for details.
---
## Core Concepts
### Loop Engineering — Loop Engineering
The traditional Plan → Execute → Done linear process cannot handle the basic scenario of "verification failure requires rework". Agent Team adopts the **Discover → Plan → Execute → Verify → Iterate** loop model:
```
┌─────────────────────────────────────────┐
│ │
▼ │
Discover ──→ Plan ──→ Execute ──→ Verify │
▲ │ │ │
│ NOT DONE ◄┘ │ │
│ │ │
└─────────────────────────────────┘ │
DONE ↓ │
Delivery │
```
Each link failure is not a overall failure, but **triggers the next iteration** - this is the meaning of "loop".
### Verify-Separation — Verification Separation
The Agent who writes code and the Agent who reviews must be different instances. This is not "distrust" - but a basic principle of software engineering: **confirmation bias will make self-testing a mere formality**.
Agent Team's Reviewer will review independently from six dimensions:
- Code correctness
- Demand alignment
- Security
- Test coverage
- Code style
- Performance impact
### Engine-First — Engine First
The core logic is a pure JavaScript function library (`src/core.js`, 34 modules, ~280 functions), without HTTP dependency, without front-end. Four calling methods share the same engine:
| Calling Method | Entrance | Applicable Scenario |
|---------------|----------|--------------------|
| **Engine Direct Call** | `import { bootstrap } from './src/core.js'` | Programming integration, CI/CD script |
| **CLI** | `node src/cli.js` | Command line operation, automation |
| **REST API** | `npm start` | External system integration |
| **Web Console** | Optional, need to build front-end | Visual operation |
---
## Key Capabilities
### 1. Deployability — Agent Team "Airborne" to Any Machine
Agent Team supports **5 Execution Backends**, covering all scenarios from local development to remote production:
| Execution Backend | Applicable Scenario | Security Isolation |
|------------------|--------------------|-------------------|
| **native** | Local rapid iteration | Environment variable whitelist |
| **docker** | Standard container deployment | `--network none` + `--read-only` + `--cap-drop=ALL` |
| **kubernetes** | Large-scale cluster | NetworkPolicy + securityContext |
| **ssh** | Remote server (no pre-installed environment) | strictHostKeyChecking + private key permission check |
| **service** | Remote resident HTTP service | Token authentication |
The SSH backend has the strongest "airborne" capability: Agent logs into a machine with no environment → automatically detects and installs missing tools → synchronizes source code → fixes problems → verifies and passes → submits artifacts. The whole process does not require human operation on the remote machine.
### 2. Skill System — Ability is Document
Skill is not a code plugin, but a structured Markdown document, injected into the system prompt when Agent executes. Each Skill contains:
- Intention matching (when to activate)
- Input/output format
- Execution steps
- Constraint rules (`required_files`, `forbidden_patterns`, `test_command`, etc.)
Reviewer will **hard-check** these constraints one by one. What if Coder misses a certain output file? Reviewer directly REJECTS. When multiple Skills are activated simultaneously in the team, the upstream and downstream dependency relationships are automatically declared through the `produces`/`consumes` contract.
36 built-in Skills cover areas such as Express REST API, security coding, code review, API testing, etc. You can create new Skills at any time - without modifying any code.
### 3. External Agent Bidirectional Access — Both as "Hands and Feet" and "Brain"
This capability is extremely rare in similar frameworks.
**As "Hands and Feet"** - Let external AI become a formal member of the team. Supports 4 access channels (HTTP callback, A2A protocol, MCP protocol, Service backend), and is assigned subtasks, injected context, and receives review, just like other Agents.
**As "Brain"** - Let external AI control the platform. Through 35 MCP tools or A2A extension methods, external AI can create teams, issue missions, dialogue with LEAD, approve plans, and inject supplementary messages in the middle. In the most extreme case: humans use natural language to talk to enterprise WeChat → robot calls Agent Team → team autonomously completes the entire development → result automatically returns. The whole process does not require humans to open any interface.
### 4. Self-Evolution and Knowledge Precipitation
Agent Team automatically precipitates three types of knowledge during operation:
- **ERRORS.md** — Records error types, trigger conditions, and solutions
- **LEARNINGS.md** — Extracts reusable experience from successful tasks
- **Pitfall Cards** — Automatically records failure lessons, and injects warnings for similar tasks next time
### 5. Quality Gate System
5-dimensional Go/No-Go quality gate, including one-vote veto:
- Core task quality (success rate red line)
- Performance and concurrency toughness
- Cost and Token (budget breaker)
- Security and sandbox (path traversal / injection detection)
- Delivery and rollback
---
## Architecture Design
```
┌──────────────────────────────────────────────────────────────────┐
│ Engine-First Architecture │
├──────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Core Engine (src/core.js) │ │
│ │ 34 modules / ~280 functions / Pure JS Library │ │
│ │ Zero HTTP dependency, import & go │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ↑ ↑ ↑ ↑ │
│ ┌──────┴──────┐ ┌─────┴─────┐ ┌──────┴──────┐ ┌─────┴─────┐ │
│ │ CLI │ │ Server │ │ MCP │ │ A2A │ │
│ │ 80+ commands │ │ REST API │ │ 35 Tools │ │ External │ │
│ │ Ops & CI/CD │ │187 Endpts │ │ AI Clients │ │ Agents │ │
│ └─────────────┘ └─────┬─────┘ └─────────────┘ └───────────┘ │
│ ┌──┴──┐ │
│ │ Web │ ← Optional Dashboard │
│ │React│ (works without it) │
│ └─────┘ │
├──────────────────────────────────────────────────────────────────┤
│ Team Orchestrator │ Executor Backend │ Context Engine │
│ (Mission → Plan │ (5 Backends: │ (3-Tier Memory: │
│ → Dispatch │ native/docker │ recent full-text │
│ → Maker-Checker │ /k8s/ssh/service)│ + distant summary │
│ → Verify) │ │ + team blackboard) │
├──────────────────────────────────────────────────────────────────┤
│ Quality Gate │ MCP Protocol │ A2A Protocol │ Knowledge DB │
│ Security │ Smart Router │ Self-Improving│ Skill System │
├──────────────────────────────────────────────────────────────────┤
│ OpenClaw Runtime (Real LLM Agent Execution) │
│ ~/.openclaw/agents/<id>/ (SOUL.md / TOOLS.md / SKILL/) │
├──────────────────────────────────────────────────────────────────┤
│ Data Layer (SQLite WAL + FS) │
│ loop-studio.db │ worktrees/ │ blackboards/ │ sessions/ │
└──────────────────────────────────────────────────────────────────┘
```
### Built-in Agent Team
| Role | ID | Responsibility |
|------|----|------|
| Scheduler | `orchestrator` | Cluster scheduling center, task decomposition and allocation |
| Architect | `architect` | Scheme design, acceptance criteria formulation |
| Coder | `coder` | Coding within Worktree, minimal modification principle |
| Reviewer | `reviewer` | 6-dimensional independent review, default REJECT |
| Tester | `tester` | Independent verification, forced to run test commands |
| Documenter | `documenter` | Documentation and Changelog |
| Researcher | `researcher` | Information retrieval, internet search |
| Searcher | `searcher` | Project structure scanning, technical stack identification |
| Bridge Agent | `pm` | User and team's relay, demand clarification and progress reporting |
---
## Protocol and Ecology
Agent Team is not a closed system. It deeply interoperates with the external world through standard protocols:
### REST API — 187 Endpoints
Covers team, Agent, task, workspace, knowledge, quality, cost, container, approval, template, Token, MCP/A2A, Feishu integration, and other fields. Each endpoint has complete request/response documentation and curl examples. See [API Reference](docs/API_REFERENCE.md) for details.
— 35 Standard Tools
Implements a complete MCPprotocol version 2025-06-18), tools are divided categories:
- **Workspace Operations (10)**：File read execution, code search, web crawling
- **Platform Management)**：Team management,, Agent management, conversation monitoring logs, knowledge search, cost estimation
Each tool has a mapping, and limited Tokens can only call tools within their permission scope AI clients (Claude Desktop, Cursor, Feishu robot directly connect to `http://host:3001/mcp control the platform.
### A Protocol — Complete Server + Client Implementation
Supports JSON-RPC.0 standard A2A protocol (tasks/send, tasks/get), and declares **4 extension methods Agent Card:
- `tasks/questions` — Query LEAD questions
- `tasks/answer` — Answer specified questions
- `tasks/confirm` — Approve plans
- `tasks/message` — Inject supplementary messages
External AI brains can complete the entire "issuing missions → → approval → observation" using2A protocol.
### SSE Real-time Event Stream
team execution are pushed in real-time through Server-Sent `agent.started`, `agent.completed`, `agent.failed`, `subtask.started`, `subtask.completed`, `team.completed`, etc. The front-end console and external systems can subscribe to these events.
## External Agent Access
### Joining a Team as an "Employee"
| Access Channel | Suitable Scenarios | External Implementation Required |
|----------|---------|-----------|
| **HTTP Callback**-developed scripts, cloud LangChain | Receive task POST interface |
| **A Protocol** | Another AI Agent platform | Agent Card +/get **MCP Protocol** | Tool-type Agent | tools/list + tools/call |
| **Service** | Rem deployed resident services | /health + /execute |
### Controlling the Platform as a "Brain"
```
Human Users → Feishu/ClEnterprise WeChat → MCP/A2A/REST → Agent Agent Team
↑ ↓
└──────── Questions/Approval ──────┘
```
See the detailed access guide in `skills/external-agent-platform-control/skill.md`.
## CLI Command Line
The CLI directly calls the engine without starting the server, with 80+ subcommands covering all 14 core modules:
```bash
# Global installation can be used after agent-team or at command
npm link
# Team Management
agent-team list # List teams
agent-team team start <id> # Start
agent-team team mission <id> --goal "Implement login"
agent-team team run <id> --watch # Execute and observe in real-time
agent-team team pause <id> | resume <id> # Pause/resume
# Agent Management
agent-team agent list # List agents
agent-team agent create --name "Go Dev" --role coder
agent-team agent clone <id> # Clone agent
# External Agent / MCP / A2A
agent-team a2a list # List external agents
agent-team a2a add --name "my-ai" --url "https://..."
agent-team a2a send <id> --message "Analyze code"
agent-team mcp sync <id> # Sync MCP tools
# Workspace / Knowledge / Quality
agent-team workspace add-url --url "https://github.com/user/repo.git"
agent-team knowledge search --mission "Implement authentication"
agent-team quality report # Quality gate report
agent-team cost estimate --mission "Implement login" --members 5
# Deployment
agent-team deploy-platform --host 192.168.1.100 --user root --key ~/.ssh/id_rsa --llm-key sk-xxx
```
Complete manual: [CLI Reference](docs/CLI_REFERENCE.md)
## Deployment
### Docker
```bash
cd deploy/docker
docker build -t agent-team:latest -f Dockerfile ../..
docker-compose up -d
```
### Kubernetes
```bash
cd deploy/k8s
kubectl apply -f configmap.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
```
### SSH Remote Deployment
```bash
# Deploy the complete platform to a remote server
agent-team deploy-platform --host <ip> --user <user> --key <ssh-key> --llm-key <api-key>
# Deploy a lightweight Agent execution service
agent-team deploy-team-service --host <ip> --user <user> --key <ssh-key>
```
## Documentation
| Document | Description |
|------|------|
| [ENGINE.md](ENGINE.md) | Engine user manual: `import core.js` programming integration + relationship between engine and Server/CLI/MCP/A2A |
| [API Reference](docs/API_REFERENCE.md) | 187 REST endpoints + MCP/A2A protocol complete reference |
| [CLI Reference](docs/CLI_REFERENCE.md) | 80+ subcommands, covering 14 core modules |
| [User Manual](USER_MANUAL.md) | Noun concept explanation + complete operation guide |
| [Technical Blog](blog/tech-blog.md) | Project background, design ideas, and development process (~16,000 words) |
| [External Agent Skill](skills/external-agent-platform-control/skill.md) | MCP guide for external AI brains to control the platform |
| [Open Source Strategy](OPEN_SOURCE_STRATEGY.md) | Differentiated positioning and community operation roadmap |
| [Test Plan](TEST_PLAN.md) | 10 dimensions / 50 scenarios / 215 test case design |
| [Test Report](TEST_REPORT_FINAL.md) | 196 test cases / 94.4% pass rate / production readiness assessment |
## Test Coverage
After systematic full-stack testing:
```
10 dimensions / 12 production scenarios / 196 test cases
188 PASS | 3 FAIL* | 5 SKIP
Pass rate 94.4%
*3 FAILs are all test environment mock-agent not running, non-functional defects
```
| Test Suite | Test Cases | Coverage Domain |
|----------|--------|---------|
| Basic Smoke | 9 | Core interface availability |
| Plan Parsing | 21 | Structured scheme decomposition and quality verification |
| Security Tools | 16 | Path traversal, injection detection, desensitization |
| Cascading Deletion | 9 | Foreign key constraint integrity |
| CLI + API Comprehensive | 75 | CLI 19 modules + API 27 endpoints |
| File Transfer Bidirectional | 26 | Runtime file request, upload, expiration cleanup |
| Concurrency Safety | 6 | Concurrency, lock, SIGTERM→SIGKILL |
| Disaster Recovery | 16 | Crash recovery, Webhook retry, breakpoint continuation |
| Performance Stability | 8 | Response delay, memory usage, long-term stability |
| Production Scenarios | 10 | SSH cross-OS, multi-team concurrency, large file upload |
## Project Structure
```
loop-studio/
├── src/ # Core Engine (34 modules)
│ ├── core.js # Unified entry (re-exports all modules)
│ ├── bootstrap.js # Shared init sequence
│ ├── server.js # HTTP server (Express)
│ ├── routes.js # REST API (~187 endpoints)
│ ├── cli.js # CLI (80+ subcommands)
│ ├── team-orchestrator.js # Mission → Plan → Dispatch → Verify
│ ├── executor-backend.js # 5 execution backends
│ ├── external-agent-executor.js# External agent executor (4 channels)
│ ├── a2a-protocol.js # A2A JSON-RPC (Server + Client)
│ ├── mcp-server.js # MCP protocol (35 tools)
│ ├── context-engine.js # 3-tier memory system
│ ├── smart-router.js # Complexity → model assignment
│ ├── self-improving.js # ERRORS/LEARNINGS/Pitfall Cards
│ ├── quality-gate.js # 5-dimension Go/No-Go
│ ├── knowledge.js # Experience reuse + pitfall cards
│ ├── agent-files.js # OpenClaw standard agent files
│ ├── agents.js # Agent definition + instantiation
│ ├── team-manager.js # Team CRUD + deploy + lifecycle
│ ├── team-template.js # Reusable team templates
│ ├── llm.js # LLM adapter (OpenClaw spawn)
│ ├── security.js # Secrets / Token / Sandbox policy
│ ├── safe-utils.js # Path traversal / injection guards
│ ├── cost-management.js # Token budget + cost estimation
│ └── ... # 16 more modules
├── web/ # Web Console (React 18 + Vite)
│ └── src/
│ ├── pages/ # 15 pages
│ ├── components/ # 16 shared components
│ ├── hooks/ # Custom hooks
│ └── lib/ # Status / format / constants
├── deploy/ # Deployment configs
│ ├── docker/ # Dockerfile + docker-compose + Prometheus
│ ├── k8s/ # Deployment/HPA/Ingress/RBAC/NetworkPolicy
│ └── scripts/ # Cross-platform install/bootstrap scripts
├── skills/ # OpenClaw standard Skills
│ ├── express-rest-api/skill.md
│ └── external-agent-platform-control/skill.md
├── docs/ # Documentation
│ ├── API_REFERENCE.md # 187 endpoints reference
│ └── CLI_REFERENCE.md # 80+ subcommands reference
├── test/ # Test suites (10 suites / 196 cases)
├── blog/ # Technical blog posts
├── experiment/ # Performance test data
└── paper/ # Academic paper
```
## Technology Stack
| Layer | Technology | Description |
|----|------|------|
| **Backend** | Node.js 20+ | ESM, event-driven |
| **Web Framework** | Express 4 | Lightweight HTTP wrapper |
| **Database** | better-sqlite3 | SQLite WAL mode, 22 tables |
| **Frontend** | React 18 + Vite 5 | Pure CSS design system, no UI framework |
| **LLM Runtime** | OpenClaw CLI | `spawn openclaw agent --json --local` |
| **Protocol** | A2A (JSON-RPC 2.0) <br> MCP (2025-06-18) <br> SSE | Three protocols complete support |
| **Container** | Docker / Kubernetes | Security-hardened deployment |
| **Model** | DeepSeek / OpenAI / Anthropic / Gemini / Ollama / Custom | Multi-provider + cross-provider downgrade |
## Roadmap
Contributors from the community are welcome to participate in the development of the following directions:
- [ ] **Vectorized Semantic Search** — Upgrade knowledge precipitation to semantic matching, cross-task type experience reuse
- [ ] **DAG Workflow Engine** — Make Maker-Checker process configurable from hardcoding to directed acyclic graph
- [ ] **Dynamic Role Negotiation** — Agent autonomous evaluation capability, negotiation and division of labor static role allocation
- [ ] **More Execution Backends** — AWS Lambda, GCP Cloud Run, edge computing
- [ ] **VSCode Extension** — Directly manage Agent teams in the editor
- [ ] **More Team Templates** — Out-of-the-box templates for more development scenarios
## Contribution Guide
Contributions of any form are welcome! Whether it's bug reports, feature suggestions, code PRs, or documentation improvements.
Please read [CONTRIBUTING.md](CONTRIBUTING.md) to understand the development process and code specifications.
### Contributors
Thanks to all contributors who have made contributions to this project
## Contact Us
- **GitHub Issues**: [Issue Reporting and Feature Requests](https://github.com/PandaKing2021/loop-studio/issues)
- **GitHub Discussions**: [Discussion and Q&A](https://github.com/PandaKing2021/loop-studio/discussions)
## License
MIT 2026 Agent Team Contributors
<p align="center">
<sub>Built with for the AI Engineering community</sub>
</p>
