<p align="center">
  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.9.0/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
</p>

# Agentbyte

Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.

Current release: **0.9.0** — see [CHANGELOG.md](CHANGELOG.md) for the full release history.

Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)

## Current Capabilities

- Agent execution loop with `run()` and `run_stream()` APIs.
- Tooling system (function tools + core tools + memory tool).
- Middleware chain for request/response/error handling.
- Built-in middleware: logging, security, rate limiting, approval, telemetry.
- Memory abstractions: list memory, file memory, context injection.
- OpenAI and Azure OpenAI model client support.
- OpenTelemetry-first tracing with model-call and task-level usage telemetry.
- Multi-agent orchestration: `RoundRobinOrchestrator`, `AIOrchestrator`, `HandoffOrchestrator`, `PlanBasedOrchestrator` with composable termination conditions.
- **Workflow runtime:** typed step graphs (`FunctionStep`, `EchoStep`, `HttpStep`, `TransformStep`, `AgentStep`, `SubWorkflowStep`) with conditional routing, parallel execution, checkpoint/resume, human-in-the-loop suspend/resume, staged state semantics, structured streaming events, and declarative JSON/YAML schema serialisation.

## Observability-First Telemetry

Agentbyte exposes two complementary telemetry layers:

- **Per-call middleware spans** (`chat ...`, `tool ...`) for model/tool-level diagnostics.
- **Task-level root span attributes** (`agent ...`) for final aggregated usage and outcome.

Enable telemetry:

```bash
export AGENTBYTE_ENABLE_OTEL=true
```

Per-call span attributes emitted by `OTelMiddleware`:

- `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.total_tokens`
- `gen_ai.usage.cost_estimate_usd`
- `gen_ai.response.finish_reason`
- `gen_ai.request.model`
- `gen_ai.tool.name`, `gen_ai.tool.success`

## Degugging Traces without UI
details can be found in the [OTel spans guide](docs/study/topic_otel_spans.md#debugging-traces-without-ui).

Practical interpretation:

- `chat gpt-4.1-mini` spans show **per-call** usage/cost/finish reason.
- `agent <name>` span shows **final accumulated** usage and final task outcome.

## Installation

Python requirement: **3.11+**

```bash
uv sync --all-groups
```

Optional extras:

```bash
uv sync --extra openai
uv sync --extra azureopenai
uv sync --extra otel
uv sync --extra webui
```

### Install in another project (pip / uv add)

Use extras to enable provider + telemetry support:

```bash
pip install "agentbyte[azureopenai,otel]"
```

```bash
uv add "agentbyte[azureopenai,otel]"
```

For the browser WebUI:

```bash
pip install "agentbyte[webui]"
# or
uv add "agentbyte[webui]"
```

Install all optional features:

```bash
pip install "agentbyte[all]"
# or
uv add "agentbyte[all]"
```

Note: the Azure extra is `azureopenai`.

## Quick Start

```python
from agentbyte.agents import Agent
from agentbyte.middleware import LoggingMiddleware

# model_client = OpenAIChatCompletionClient(...) or AzureOpenAIChatCompletionClient(...)

def quick_faq_lookup(topic: str) -> str:
    faq = {
        "middleware": "Middleware handles cross-cutting runtime concerns.",
        "memory": "Memory helps agents keep useful context across interactions.",
    }
    return faq.get(topic.lower(), "No FAQ found.")

agent = Agent(
    name="helpful-assistant",
    description="Helpful assistant with middleware",
    instructions="Answer clearly and use tools when needed.",
    model_client=model_client,
    tools=[quick_faq_lookup],
    middlewares=[LoggingMiddleware()],
)
```

## Run The WebUI

### Option 1: Run the included demo app

This is the easiest way to see the WebUI working end to end with:
- one demo agent
- one demo workflow
- one demo orchestrator

Step 1. Install the WebUI extra:

```bash
uv sync --extra webui
```

Step 2. Start the demo app:

```bash
uv run python examples/webui/basic_webui.py
```

Step 3. Open the browser:

```text
http://127.0.0.1:8080
```

If auto-open is enabled in your environment, the browser may open automatically.

### Option 2: Run the WebUI against your current project directory

Use this when you want Agentbyte to scan a directory for exported `agent`, `workflow`, or `orchestrator` objects.

Important: discovery is convention-based. The scanned directory must contain Python modules that expose top-level variables literally named `agent`, `workflow`, or `orchestrator`. If you point `--dir` at a folder that does not export those names, the UI will load but show `No entities found`.

Step 1. Install the WebUI extra:

```bash
uv sync --extra webui
```

Step 2. Launch the WebUI and scan the current directory:

```bash
uv run agentbyte webui --dir .
```

Step 3. Open the browser:

```text
http://127.0.0.1:8080
```

Useful variants:

```bash
uv run agentbyte webui --dir . --port 8080 --host 127.0.0.1 --no-open
uv run agentbyte webui --dir examples --port 8090
```

For this repository, the most reliable first-run path is still the bundled demo:

```bash
uv run python examples/webui/basic_webui.py
```

Use `agentbyte webui --dir ...` when you have a directory of exportable demo modules, for example:

```python
# my_entities.py
agent = ...
workflow = ...
orchestrator = ...
```

### Option 3: Run it programmatically

Use this when you want to serve in-memory entities directly from Python.

```python
from agentbyte.webui import serve

serve(entities=[agent], port=8080, auto_open=True)
```

### Quick Troubleshooting

If the app does not start:

```bash
uv sync --extra webui
```

If port `8080` is already in use:

```bash
uv run agentbyte webui --dir . --port 8090
```

If you do not want the browser to open automatically:

```bash
uv run agentbyte webui --dir . --no-open
```

## Project Layout

```
src/agentbyte/
  agents/
  llm/
  memory/
  middleware/
  tools/
  messages.py
  context.py
  types.py
```

## Development

```bash
uv run ruff check src tests
uv run pytest tests -v
```

## License

MIT — see [LICENSE](LICENSE).

## References

- [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
