agentbyte 0.1.2
A toolkit for designing multiagent systems
Requires Python: >=3.12

# Agentbyte: Experimental Multiagent Systems Toolkit

**Agentbyte** is an **experimental** Python toolkit for designing scalable multiagent systems. This project is a learning-driven build and is **not enterprise-ready**.

This project serves a dual purpose:

1. **Learning Journey:** Master advanced AI engineering concepts by studying [picoagents](https://github.com/openai/picoagents) architecture, patterns, and design decisions
2. **Knowledge Application:** Build Agentbyte step-by-step based on personal knowledge and preferences, deepening expertise in multiagent systems
3. **Enterprise Library (future):** Create a production-ready library with multi-framework and multi-LLM support
4. **Cross-Framework Compatibility:** Enable seamless composition of agents from Agentbyte, [Microsoft Agent Framework](https://github.com/microsoft/agent-framework), and [Pydantic AI](https://ai.pydantic.dev/)

The development approach is iterative and intentional: understand a pattern → implement it in Agentbyte with custom enhancements → validate with examples → move to next pattern. This methodology builds both library quality and deep AI engineering expertise.

## Status

- **In progress:** Project is actively evolving
- **Implemented:** LLM client classes built from scratch
- **Next step:** Create the agent base

## Core Stack

- **Python 3.12+**
- [picoagents](https://github.com/openai/picoagents) >= 0.2.3 (reference framework for learning agent orchestration patterns)
- [pydantic](https://docs.pydantic.dev/) for data validation and settings management
- **LLM Providers:**
  - OpenAI API (GPT-4, GPT-5 series models)
  - AWS Bedrock (future integration)
- **Frameworks:**
  - Microsoft Agent Framework (integration in progress)
  - Pydantic AI (integration in progress)

## Architecture

### Directory Structure

```
src/agentbyte/           # Main package
├── agent/              # Agent base classes and abstractions
│   └── base.py         # BaseAgent ABC - extend this for custom agents
├── settings/           # Environment and configuration management
│   └── core.py         # Settings classes (AppSettings, PostgresSettings, AgentbyteBaseSettings)
└── __init__.py         # Package exports

examples/               # Working examples and use patterns
├── pico-agent-test.py  # Simple agent with tool usage
└── round-robin.py      # Multi-agent orchestration with termination conditions

notebooks/              # Development/exploration notebooks
└── pico-init-agent-test.ipynb  # Interactive testing environment

external_lib/           # External reference implementations
└── designing-multiagent-systems/  # picoagents reference (git submodule)
```

### Key Components

#### 1. **Settings System** (`src/agentbyte/settings/core.py`)

**Purpose:** Centralized environment variable management with Pydantic

**Key Classes:**
- `AgentbyteBaseSettings`: Base class for all agentbyte configuration
  - Provides `.from_env_file(Path)` classmethod for notebook/custom environments
  - Automatically prefixes environment variables (e.g., `APP_`, `POSTGRES_`)
- `AppSettings`: Application-level config (log_level, environment)
- `PostgresSettings`: Database connection with `.url` property for connection strings

**Pattern:** All settings classes use Pydantic's `SettingsConfigDict` with `env_prefix` to organize environment variables by domain. Settings can be loaded from custom paths—essential for notebooks that don't run from project root.

```python
# In notebooks or custom paths:
settings = PostgresSettings.from_env_file(Path("../../../.env"))
```

#### 2. **Agent Base** (`src/agentbyte/agent/base.py`)

**Purpose:** Abstract base for custom agent implementations

**Current State:** Planned work. The agent base will be implemented next.

### External Dependency: picoagents (Reference Framework)

**picoagents** serves as the reference implementation for understanding agent orchestration patterns. Key concepts to study and potentially abstract:
- **Agents:** Named, instruction-driven with optional tools and model clients
- **Orchestrators:** RoundRobinOrchestrator for multi-agent conversations
- **Termination Conditions:** MaxMessageTermination, TextMentionTermination for conversation flow control
- **Tools:** Functions exposed to agents via function introspection

**Learning Goal:** Extract generalizable patterns from picoagents that can be reused across Autogen/Pydantic AI frameworks. See [external_lib/designing-multiagent-systems/picoagents](external_lib/designing-multiagent-systems/picoagents) for full reference source and [examples/round-robin.py](examples/round-robin.py) for application patterns.

## License

This project is licensed under the MIT License.

## Development Workflows

### Environment Setup

```bash
# Project uses UV for dependency management (uv.lock present)
# Python 3.12+ required (see .python-version)
# Copy .env template for API keys: OPENAI_API_KEY required, optional: POSTGRES_*, HF_TOKEN, etc.

# Clone with submodules:
git clone --recursive git@github.com:yourusername/agentbyte.git
cd agentbyte

# Or if already cloned:
git submodule update --init --recursive
```

### Testing & Validation

```bash
# Test dependencies available (pytest, pytest-cov)
# Run: pytest tests/ -v --cov=src/agentbyte
# (tests/ directory not yet created—add test files here)
```

### Development in Notebooks

The project uses Jupyter notebooks for interactive development:
- **Kernel:** ipykernel configured for Python 3.12+
- **Pattern:** Import agentbyte modules, load settings with `.from_env_file()`, test agent interactions
- **Example:** [notebooks/pico-init-agent-test.ipynb](notebooks/pico-init-agent-test.ipynb) demonstrates agent initialization and response handling

### Running Examples

```bash
# Simple agent example (requires OPENAI_API_KEY in .env):
# Supports: gpt-4o, gpt-4-turbo, gpt-4, gpt-5 (as available)
python examples/pico-agent-test.py

# Multi-agent orchestration:
python examples/round-robin.py
```

## References

This library is built from combined learning from the references below and ongoing study of Design Multi-Agent AI Systems Using MCP and A2A.

- [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
- *Build a Multi-Agent System (from Scratch)* (Manning) by Val Andrei Fajardo
- [llm-agents-from-scratch](https://github.com/nerdai/llm-agents-from-scratch)