bzzz-cli 0.1.0

# Bzzz

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-540%2B%20passing-brightgreen.svg)]()
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)]()
[![GitHub release](https://img.shields.io/github/v/release/fengjunhui/bzzz?include_prereleases)](https://github.com/fengjunhui/bzzz/releases)

**The trusted middleware for Agent capabilities.**

Define → Orchestrate → Execute

From single agents to complex swarms, across any runtime.

---

## What is Bzzz?

Bzzz is **not** another developer-first multi-agent workflow framework. It is:

- **Protocol-first**: AgentSpec, SwarmFile, RuntimeAdapter define clear contracts
- **Runtime-agnostic**: Execute on Local, Docker, HTTP, or custom runtimes
- **Pattern-based**: 9 orchestration patterns for any scenario
- **Agent-ready**: Designed to be called by your primary Agent

### Ecosystem Position

```
┌─────────────────────────────────────────┐
│  Agent Products                         │  Claude Code, Codex, Cursor
├─────────────────────────────────────────┤
│  Agent Orchestration ← Bzzz 在这里      │  SwarmFile + 编排引擎
├─────────────────────────────────────────┤
│  Agent Communication                    │  A2A 协议（Agent 发现 + 通信）
├─────────────────────────────────────────┤
│  Agent-Tool Connection                  │  MCP（Agent 用工具）
├─────────────────────────────────────────┤
│  Agent Frameworks                       │  LangGraph, CrewAI, Claude SDK
├─────────────────────────────────────────┤
│  LLM APIs                              │  Claude API, OpenAI API
└─────────────────────────────────────────┘
```

**类比**：
- **MCP**: Agent 怎么调用工具
- **A2A**: Agent 怎么被发现、怎么互相通信
- **Bzzz**: 多个 Agent 怎么按工作流协作 ← **A2A 生态里缺的这一块**

## Quick Start

```bash
# Clone
git clone https://github.com/fengjunhui/bzzz.git
cd bzzz

# Build
cargo build --release

# Run an example
cargo run -- run -f examples/basics/sequence.swarm.yaml
```

## Demo

### CLI Demo Recording

View the CLI demo using asciinema:

```bash
asciinema play docs/demos/bzzz-demo.cast
```

Or view the plain text output:

```text
$ bzzz run --help

Run an Agent or Swarm

Usage: bzzz run [OPTIONS] --file <FILE>

Options:
  -f, --file <FILE>      Path to Agent Spec or SwarmFile
  -b, --background       Run in background
  -t, --timeout <TIMEOUT> Timeout in seconds
  -r, --runtime <RUNTIME> Runtime to use (local, docker, http)
  ...

$ bzzz run -f examples/basics/sequence.swarm.yaml

🚀 Running: examples/basics/sequence.swarm.yaml
  Swarm: simple-sequence (simple task)
  Worker: worker-a
  Runtime: Local
  Status: Completed
  Output: {"stdout": "done"}
```

## Core Concepts

| Concept | Purpose |
|---------|---------|
| **AgentSpec** | Declare a single agent's capability |
| **SwarmFile** | Orchestrate multiple agents with patterns |
| **RuntimeAdapter** | Execute across different runtimes |
| **Pattern** | 9 modes: sequence, parallel, conditional, loop, delegate, supervisor, compete, escalation, alongside |

## Example

```yaml
# agent.yaml
apiVersion: bzzz.dev/v1
kind: agent
id: my-agent
runtime:
  kind: Local
  config:
    command: "echo 'Hello from Bzzz!'"
```

```yaml
# swarm.yaml
apiVersion: bzzz.dev/v1
kind: swarm
id: my-swarm
workers:
  - name: my-agent
    spec: agent.yaml
flow:
  type: sequence
  steps:
    - my-agent
```

```bash
# Execute
bzzz run -f swarm.yaml
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `bzzz run -f <file>` | Run AgentSpec or SwarmFile |
| `bzzz run --background` | Run in background |
| `bzzz status --id <id>` | Query execution status |
| `bzzz stop --id <id>` | Stop execution |
| `bzzz list` | List all executions |
| `bzzz validate -f <file>` | Validate configuration |

## Documentation

📖 **Full Documentation**: [docs-site/content/](docs-site/content/) (mdBook format)

### Quick Links
- [Getting Started](docs-site/content/getting-started.md)
- [SwarmFile Protocol](docs-site/content/protocol/swarmfile.md)
- [Pattern Reference](docs-site/content/patterns/README.md)

### Specification Docs

- [Acceptance Spec](docs-site/specs/2026-04-05-bzzz-acceptance-spec.md)
- [Design Principles](docs-site/specs/2026-04-05-bzzz-first-principles-design.md)
- [Roadmap](docs-site/specs/2026-04-05-bzzz-roadmap.md)
- [AgentSpec Protocol](docs-site/specs/protocols/agent-spec.md)
- [SwarmFile Protocol](docs-site/specs/protocols/swarmfile.md)
- [RuntimeAdapter Protocol](docs-site/specs/protocols/runtime-adapter.md)

## Status

| Phase | Status |
|-------|--------|
| Phase 0: Data Flow | ✅ Complete |
| Phase 1: Protocol Freeze | ✅ Complete |
| Phase 2: First Demo | ✅ Complete |
| Phase 3: CLI Context | ✅ Complete |
| Phase 4: Cross-Framework | ✅ Complete |
| Phase 5: Developer Experience | ✅ Complete |
| Phase 6: Open Source Release | ✅ Complete |

## License

Licensed under [MIT License](LICENSE).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

**Bzzz** - Turning compute capabilities into Agent capabilities.