Metadata-Version: 2.4
Name: agentbyte
Version: 0.13.1
Summary: A toolkit for designing multiagent systems
Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.13.0
Requires-Dist: pydantic>=2.12.5
Provides-Extra: all
Requires-Dist: aioboto3>=15.5.0; extra == 'all'
Requires-Dist: azure-identity>=1.25.1; extra == 'all'
Requires-Dist: fastapi>=0.135.2; extra == 'all'
Requires-Dist: graphviz>=0.21; extra == 'all'
Requires-Dist: openai>=1.107.1; extra == 'all'
Requires-Dist: opentelemetry-api>=1.39.1; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'all'
Requires-Dist: uvicorn>=0.42.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: aioboto3>=15.5.0; extra == 'aws'
Provides-Extra: azureopenai
Requires-Dist: azure-identity>=1.25.1; extra == 'azureopenai'
Requires-Dist: openai>=1.107.1; extra == 'azureopenai'
Provides-Extra: dev
Requires-Dist: ipykernel>=7.1.0; extra == 'dev'
Requires-Dist: nbclient>=0.10.4; extra == 'dev'
Requires-Dist: nbformat>=5.10.4; extra == 'dev'
Requires-Dist: picoagents>=0.4.0; extra == 'dev'
Requires-Dist: pydantic-settings>=2.13.0; extra == 'dev'
Requires-Dist: pymupdf-layout>=1.26.6; extra == 'dev'
Requires-Dist: pymupdf4llm>=0.2.9; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.107.1; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.39.1; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
Provides-Extra: sql
Requires-Dist: aiosqlite>=0.22.1; extra == 'sql'
Requires-Dist: asyncpg>=0.31.0; extra == 'sql'
Requires-Dist: sqlmodel>=0.0.38; extra == 'sql'
Provides-Extra: test
Requires-Dist: aiosqlite>=0.22.1; extra == 'test'
Requires-Dist: greenlet>=3.0.0; extra == 'test'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
Requires-Dist: pytest>=9.0.1; extra == 'test'
Requires-Dist: ruff>=0.15.0; extra == 'test'
Requires-Dist: sqlmodel>=0.0.38; extra == 'test'
Provides-Extra: viz
Requires-Dist: graphviz>=0.21; extra == 'viz'
Provides-Extra: webui
Requires-Dist: fastapi>=0.135.2; extra == 'webui'
Requires-Dist: uvicorn[standard]>=0.44.0; extra == 'webui'
Description-Content-Type: text/markdown

  Agentbyte

# 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.13.1** — see [CHANGELOG.md](CHANGELOG.md) for the full release history.

Repository: [Bitbucket Enterprise](https://bitbucketenterprise.aws.novartis.net/projects/PROCURECOM/repos/agentbyte-dsai-shared)

## 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 preset-backed app

This is the easiest way to see the WebUI working end to end with real preset entities:
- preset agents
- preset orchestrators
- preset workflow

Step 1. Install the WebUI extra:

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

Step 2. Start the preset-backed app:

```bash
uv run python examples/webui/presets_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 the preset-backed launcher:

```bash
uv run python examples/webui/presets_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
```
