agentbyte 0.4.3

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

Repository: gitlab.com/pyninja/aiengineering/agentbyte

What's New in 0.4.3

• Added a new agentbyte-plan-based-orchestration Copilot skill for Chapter 7.5 plan-based orchestration.
• Updated the agentbyte-llm-client skill to document EmbeddingResult.embedding versus EmbeddingResult.embeddings.

What's New in 0.4.2

• Rebased the WebUI source frontend on the picoagents frontend snapshot copied into src/agentbyte/webui/frontend/.
• Added the packaged picoagents-style agent_framework_devui assets under src/agentbyte/webui/ for parity/reference work.
• Fixed wheel packaging so the bundled WebUI assets are included once, unblocking PyPI publish.

What's New in 0.4.1

• Extended EmbeddingResult with a single-vector embedding field while preserving embeddings, usage, model, and metadata.
• Updated OpenAI and Azure embedding clients so single-input calls are easier to consume without losing batch compatibility.
• Added and validated focused embedding client coverage for the new dual-field result contract.

What's New in 0.4.0

• Added multi-agent orchestration foundations with BaseOrchestrator.
• Added RoundRobinOrchestrator, AIOrchestrator, and PlanBasedOrchestrator.
• Added a full termination system for autonomous orchestration flows.
• Added plan-based orchestration examples, tests, and study/tutorial docs.
• Expanded OpenTelemetry coverage across agents, workflows, and orchestration roots with aggregate usage summaries.
• Added a packaged Chapter 8 WebUI with FastAPI + SSE, session handling, discovery, and a browser UI for agents, workflows, and orchestrators.

What's New in 0.3.5

• Added first-class async embeddings clients in agentbyte.llm for OpenAI and Azure OpenAI.
• Added separate single/batch embedding methods:
  • create(input_text: str) -> list[float]
  • create_batch(input_texts: list[str]) -> list[list[float]]
• Added Azure embedding deployment setting support: AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME.

What's New in 0.3.2

• Python baseline lowered: package runtime requirement is now Python 3.11+.
• CI release pipeline now builds/tests/publishes with Python 3.11.

What's New in 0.3.1

• Interactive CLI wizard: running agentbyte with no arguments launches a guided numbered menu — choose a command, then choose a provider (github-copilot / claude), then confirm before any files are written.
• Non-interactive path (agentbyte create-skills --provider=github-copilot) is fully preserved for scripting and CI.

What's New in 0.3.0

• Breaking: BaseAgent no longer stores context. self.context, reset_context(), clear_messages(), window_messages(), and reset() are removed. Agent.__init__ no longer accepts a context= kwarg.
• Agent.run(task=None, context=None, ...) and Agent.run_stream(task=None, context=None, ...) accept a per-call AgentContext. A fresh context is created automatically when None.
• AgentResponse.context returns the fully-populated working context to the caller — enables clean multi-turn patterns without agent-side state.
• AgentAsTool.execute() and execute_stream() thread the caller-supplied context through to the underlying agent.
• Notebooks, study docs (topic_agents.md, topic_approval.md), and OTel span guide (topic_otel_spans.md) updated to the caller-owned context pattern.

See CHANGELOG.md for the complete release history.

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.

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

Degugging Traces without UI

details can be found in the OTel spans guide.

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 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:

uv sync --extra webui

Step 2. Start the demo app:

uv run python examples/webui/basic_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 still the bundled demo:

uv run python examples/webui/basic_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

License

MIT — see LICENSE.

References

• Designing Multi-Agent Systems
• Microsoft Agent Framework