Agent Framework Starter

A minimal Python framework for building multi-agent AI teams using NATS JetStream messaging.

Built by GenBrain AI — the company behind agent.ceo.

---

Architecture

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

Loading

Quick Start

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

git clone https://github.com/genbrain-ai/agent-framework-starter.git
cd agent-framework-starter
pip install -e ".[dev]"

Start NATS

docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest -js

Run the Examples

# 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

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 — how multi-agent systems work, component overview, Mermaid diagrams
• Getting Started — install, run NATS, launch your first agent
• Patterns — 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 — 1 agent-week free.

Full documentation at 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 for details.

---

Built with care by GenBrain AI.