feat: complete agent framework starter kit

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ -v --tb=short

.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.env.local
+*.pem
+*.key
+.agent_memory/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/

README.md

@@ -0,0 +1,173 @@
+# Agent Framework Starter
+
+[![Tests](https://github.com/genbrain-ai/agent-framework-starter/actions/workflows/test.yml/badge.svg)](https://github.com/genbrain-ai/agent-framework-starter/actions/workflows/test.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**A minimal Python framework for building multi-agent AI teams using NATS JetStream messaging.**
+
+Built by [GenBrain AI](https://genbrain.ai) — the company behind [agent.ceo](https://agent.ceo).
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph Control Plane
+        O[Orchestrator]
+    end
+
+    subgraph Message Bus
+        N[NATS JetStream]
+    end
+
+    subgraph Agent Team
+        A1[Agent 1]
+        A2[Agent 2]
+        AN[Agent N]
+    end
+
+    O -->|delegate & broadcast| N
+    N -->|task assignments| A1
+    N -->|task assignments| A2
+    N -->|task assignments| AN
+    A1 -->|results| N
+    A2 -->|results| N
+    AN -->|results| N
+    N -->|collect results| O
+```
+
+## Quick Start
+
+```python
+import asyncio
+from src.agent import Agent
+from src.messaging import Message
+from src.orchestrator import Orchestrator
+
+class Worker(Agent):
+    async def handle_message(self, message: Message):
+        print(f"Working on: {message.payload['title']}")
+        await self.send_message(message.from_agent, {"status": "done"})
+
+async def main():
+    orch = Orchestrator(org_id="myteam")
+    orch.add_agent(Worker(name="worker", role="analyst"))
+    await orch.start_all()
+    orch.delegate_task("Analyze Q4 data", agent_name="worker")
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Async-first** — built on `asyncio` with `async/await` throughout
+- **NATS JetStream messaging** — durable, at-least-once delivery between agents
+- **Task delegation** — assign, track, and verify work across agents
+- **Orchestrator** — manage agent lifecycles, health monitoring, and broadcasting
+- **Agent memory** — persistent key-value storage with file locking
+- **Status validation** — task lifecycle with enforced state transitions
+- **Extensible** — subclass `Agent` and override `handle_message()` to build anything
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11+
+- Docker (for NATS)
+
+### Install
+
+```bash
+git clone https://github.com/genbrain-ai/agent-framework-starter.git
+cd agent-framework-starter
+pip install -e ".[dev]"
+```
+
+### Start NATS
+
+```bash
+docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest -js
+```
+
+### Run the Examples
+
+```bash
+# Simplest agent — connects and responds to messages
+python -m examples.hello_agent
+
+# Two-agent team — CEO delegates to a Worker
+python -m examples.two_agent_team
+
+# Security scanner agent
+python -m examples.security_agent
+
+# DevOps deployment pipeline agent
+python -m examples.devops_agent
+```
+
+### Run the Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Project Structure
+
+```
+agent-framework-starter/
+  src/
+    agent.py          # Base Agent class
+    messaging.py      # NATS JetStream helpers + Message model
+    task_manager.py   # Task lifecycle management
+    memory.py         # Persistent key-value store
+    orchestrator.py   # Multi-agent coordinator
+  examples/
+    hello_agent.py    # Minimal agent example
+    two_agent_team.py # Delegation pattern demo
+    security_agent.py # Security review agent
+    devops_agent.py   # Deployment pipeline agent
+  tests/
+    test_agent.py
+    test_messaging.py
+    test_orchestrator.py
+    test_task_manager.py
+    test_memory.py
+  docs/
+    architecture.md   # System design & diagrams
+    getting-started.md# Step-by-step setup guide
+    patterns.md       # Common multi-agent patterns
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — how multi-agent systems work, component overview, Mermaid diagrams
+- [Getting Started](docs/getting-started.md) — install, run NATS, launch your first agent
+- [Patterns](docs/patterns.md) — delegation, verification, fan-out, pipelines, heartbeats
+
+## Production Use
+
+This starter kit demonstrates the foundational patterns. For production-grade AI agent orchestration with Kubernetes-native deployment, automatic scaling, built-in security review, LLM integration, and a web dashboard:
+
+**[Try agent.ceo](https://agent.ceo) — 1 agent-week free.**
+
+Full documentation at [docs.agent.ceo](https://docs.agent.ceo).
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`pytest tests/ -v`)
+5. Submit a pull request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+Built with care by [GenBrain AI](https://genbrain.ai).

docs/architecture.md

@@ -0,0 +1,143 @@
+# Architecture
+
+## How Multi-Agent Systems Work
+
+A multi-agent system is a group of autonomous agents that collaborate to solve problems no single agent could handle alone. Each agent has a specific **role** (e.g., CEO, DevOps, Security Reviewer) and communicates with other agents through a shared **message bus**.
+
+This framework uses [NATS JetStream](https://nats.io/) as the message bus — a lightweight, high-performance messaging system that provides:
+
+- **Pub/Sub messaging** — agents publish and subscribe to subjects
+- **Durable delivery** — messages are persisted so agents can reconnect without missing work
+- **At-least-once semantics** — critical for task delegation where you cannot afford to lose a message
+
+## System Diagram
+
+```mermaid
+graph TB
+    subgraph Orchestrator
+        O[Orchestrator]
+        TM[Task Manager]
+        HB[Heartbeat Monitor]
+    end
+
+    subgraph Message Bus
+        NATS[NATS JetStream]
+    end
+
+    subgraph Agents
+        A1[Agent 1<br/>CEO]
+        A2[Agent 2<br/>Worker]
+        A3[Agent 3<br/>DevOps]
+        A4[Agent N<br/>...]
+    end
+
+    O --> TM
+    O --> HB
+    O -->|delegate task| NATS
+    NATS -->|task_assignment| A1
+    NATS -->|task_assignment| A2
+    NATS -->|task_assignment| A3
+    NATS -->|task_assignment| A4
+    A1 -->|task_result| NATS
+    A2 -->|task_result| NATS
+    A3 -->|task_result| NATS
+    A4 -->|task_result| NATS
+    NATS -->|results| O
+    A1 <-->|peer messages| NATS
+    A2 <-->|peer messages| NATS
+```
+
+## Core Components
+
+### Agent (`src/agent.py`)
+
+The base building block. Every agent:
+
+1. **Connects** to NATS on startup
+2. **Subscribes** to its inbox subject (`{org_id}.agents.{name}.inbox`)
+3. **Processes** incoming messages via `handle_message()`
+4. **Sends** messages to other agents via `send_message()`
+
+Subclass `Agent` and override `handle_message()` to build any kind of agent.
+
+### Messaging (`src/messaging.py`)
+
+Handles NATS connection management and message serialization. Every message is a structured `Message` object with:
+
+- `id` — unique identifier
+- `from_agent` / `to_agent` — routing information
+- `type` — message category (e.g., `task_assignment`, `task_result`, `broadcast`)
+- `payload` — arbitrary JSON data
+- `timestamp` — when the message was created
+
+### Task Manager (`src/task_manager.py`)
+
+Tracks units of work flowing through the system. Tasks have a defined lifecycle:
+
+```
+ASSIGNED → IN_PROGRESS → COMPLETED
+    ↓          ↓
+  FAILED ← FAILED
+    ↓
+  ASSIGNED (retry)
+```
+
+Status transitions are validated — you cannot skip from `ASSIGNED` directly to `COMPLETED` without going through `IN_PROGRESS`.
+
+### Orchestrator (`src/orchestrator.py`)
+
+The control plane that manages multiple agents:
+
+- **Registry** — add/remove agents
+- **Lifecycle** — start/stop all agents as a group
+- **Delegation** — assign tasks to specific agents
+- **Broadcasting** — send a message to every agent
+- **Health monitoring** — track agent liveness via heartbeats
+
+### Memory Store (`src/memory.py`)
+
+Persistent key-value storage using JSON files. Agents can save and restore state across restarts. Thread-safe via file locking.
+
+## Message Flow
+
+A typical task delegation flow:
+
+1. **Orchestrator** creates a `Task` and assigns it to an agent
+2. **Orchestrator** publishes a `task_assignment` message to the agent's inbox
+3. **Agent** receives the message, processes the task
+4. **Agent** publishes a `task_result` message back to the assigner
+5. **Assigner** verifies the result and marks the task complete
+
+```mermaid
+sequenceDiagram
+    participant O as Orchestrator
+    participant NATS as NATS JetStream
+    participant W as Worker Agent
+
+    O->>NATS: publish task_assignment
+    NATS->>W: deliver to worker.inbox
+    W->>W: process task
+    W->>NATS: publish task_result
+    NATS->>O: deliver result
+    O->>O: verify & complete task
+```
+
+## Design Principles
+
+1. **Agents are autonomous** — each agent runs independently and makes its own decisions
+2. **Communication is asynchronous** — agents don't block waiting for responses
+3. **Tasks have clear ownership** — every task has an assigner and an assignee
+4. **Verification is separate from execution** — the assigner verifies the assignee's work
+5. **Failure is expected** — agents can fail tasks, and tasks can be retried
+
+## Production Use
+
+This starter kit demonstrates the core patterns. For production-grade agent orchestration with:
+
+- Kubernetes-native deployment
+- Automatic agent scaling
+- Built-in security review
+- LLM integration
+- Web dashboard
+
+Try [agent.ceo](https://agent.ceo) by GenBrain AI.