agentbyte 0.2.7

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

Repository: gitlab.com/pyninja/aiengineering/agentbyte

What's New in 0.2.7

• run_stream() is now fully instrumented with an OTel root span — every streaming task gets a correctly nested agent <name> root span identical to run().
• Root span is created via a native _root_span() context manager in Agent; auto_instrument() no longer monkey-patches run or run_stream.
• New streaming example examples/otel/agent_with_stream_telemetry.py (service: agentbyte-stream).
• New examples/otel/inspect_traces.py CLI utility — inspect Jaeger traces by traceID without opening the UI.
• All OTel instrumentation logic centralized in otel.py; _annotate_root_span() is now a module-level function.

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 root-level usage aggregation:

export AGENTBYTE_ENABLE_OTEL=true
export AGENTBYTE_OTEL_CAPTURE_USAGE=true

Then inspect attributes such as:

• gen_ai.agent.finish_reason
• gen_ai.agent.llm_calls
• gen_ai.usage.duration_ms
• gen_ai.usage.input_tokens
• gen_ai.usage.output_tokens
• gen_ai.usage.total_tokens
• gen_ai.usage.cost_estimate_usd

Debug Traces Without Jaeger UI

If the Jaeger UI search page is slow or stuck, debug directly via APIs:

# List services
curl -sS http://localhost:16686/api/services

# Find traces for a service
curl -sS 'http://localhost:16686/api/traces?service=agentbyte-example&lookback=1h&limit=20'

# Fetch a specific trace
curl -sS http://localhost:16686/api/traces/<trace_id>

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

uv sync --all-groups

Optional extras:

uv sync --extra openai
uv sync --extra azureopenai
uv sync --extra otel

Install in another project (pip / uv add)

Use extras to enable provider + telemetry support:

pip install "agentbyte[azureopenai,otel]"

uv add "agentbyte[azureopenai,otel]"

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()],
)

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
• Pydantic AI