agentbyte 0.20.4

A toolkit for designing multiagent systems

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.20.4

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.
• Dataset module: file-based, engine-agnostic datasets with single-table (list[dict]) and multi-table (dict[str, list[dict]]) modes; SQLite multi-table loads all tables into one shared connection enabling SQL JOINs; JSON multi-table supported; S3 load and publish for both modes; pluggable engine registry.

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:

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

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+

uv sync --all-groups

Optional extras:

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:

pip install "agentbyte[azureopenai,otel]"

uv add "agentbyte[azureopenai,otel]"

For the browser WebUI:

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

Install all optional features:

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

Note: the Azure extra is azureopenai.

Quick Start

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:

uv sync --extra webui

Step 2. Start the preset-backed app:

uv run python examples/webui/presets_webui.py

Step 3. Open the browser:

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:

uv sync --extra webui

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

uv run agentbyte webui --dir .

Step 3. Open the browser:

http://127.0.0.1:8080

Useful variants:

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:

uv run python examples/webui/presets_webui.py

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

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

Option 3: Run it programmatically

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

from agentbyte.webui import serve

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

Quick Troubleshooting

If the app does not start:

uv sync --extra webui

If port 8080 is already in use:

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

If you do not want the browser to open automatically:

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

Project Layout

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

Development

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