agentbyte 0.2.7__tar.gz → 0.3.0__tar.gz

{agentbyte-0.2.7 → agentbyte-0.3.0}/.github/copilot-instructions.md

@@ -503,6 +503,69 @@ src/agentbyte/
 ## Conding Tips and Tricks
 - When picking certain topics from certain sections of the book, first only focus on that section and not the whole chapter if not relevant to the current implementation phase
 
+## Local Jaeger Trace Inspection
+
+Agentbyte ships a trace inspector script at `examples/otel/inspect_trace.py` that fetches a trace from local Jaeger and pretty-prints every span with its full AI messages (input, tool calls, tool results, output).
+
+### Setup
+
+1. **Start Jaeger** (clears all old traces):
+   ```bash
+   docker compose -f docker/jaeger-compose.yml down && docker compose -f docker/jaeger-compose.yml up -d
+   ```
+
+2. **Run an OTel example** to generate traces (service names: `agentbyte-example`, `agentbyte-stream`, `agentbyte-debug`):
+   ```bash
+   uv run python examples/otel/agent_with_stream_telemetry.py
+   ```
+
+3. **List all traces** for a service and see their span structure:
+   ```bash
+   curl -s "http://localhost:16686/api/traces?service=agentbyte-stream&limit=10&lookback=1h" | python3 -c "
+   import json, sys
+   data = json.load(sys.stdin)
+   for t in data.get('data', []):
+       print(t['traceID'], 'spans=', len(t['spans']))
+       for s in sorted(t['spans'], key=lambda x: x['startTime']):
+           print('   ', s['operationName'], f'({s[\"duration\"]//1000}ms)')
+   "
+   ```
+
+4. **Inspect a specific trace** (full messages per span):
+   ```bash
+   uv run python examples/otel/inspect_trace.py <trace_id>
+   ```
+
+### What the inspector shows per span
+- **`agent <name>`** — root span, total duration
+- **`chat <model>`** — `INPUT MESSAGES` (full context sent to LLM), `OUTPUT MESSAGES` (model reply), tokens/cost/finish_reason
+- **`tool <name>`** — `TOOL PARAMETERS` (args), `TOOL RESULT` (return value), success flag
+
+### OTel environment variables
+| Variable | Default | Purpose |
+|---|---|---|
+| `AGENTBYTE_ENABLE_OTEL` | `false` | Enable OTel instrumentation |
+| `AGENTBYTE_OTEL_CAPTURE_CONTENT` | `false` | Capture full message content in spans (needed for inspector to show messages) |
+| `OTEL_SERVICE_NAME` | — | Service label shown in Jaeger |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP endpoint (e.g. `http://localhost:4318`) |
+
+### Trace structure
+```
+agent city_assistant          ← root span (one per run_stream/run call)
+  └─ chat gpt-4.1-mini        ← LLM call: tokens, cost, finish_reason, messages
+  └─ tool get_weather          ← tool execution: params, result
+  └─ tool get_population       ← tool execution: params, result
+  └─ chat gpt-4.1-mini        ← final LLM call with all tool results
+```
+
+### Jaeger UI
+View at **http://localhost:16686** — use service dropdown to select `agentbyte-stream`, `agentbyte-example`, or `agentbyte-debug`.
+
+### Message format note
+Agentbyte serializes messages with a `parts` array (not OpenAI-style `content` string). The inspector handles both formats automatically.
+
+---
+
 ## Script Execution Rule
 - Assume Python scripts are run from the repository root. Use `.envs/local.env` with a root-relative path (e.g., `Path(".envs") / "local.env"`) instead of traversing parents.
 

{agentbyte-0.2.7 → agentbyte-0.3.0}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.3.0] - 2026-03-06
+
+### Breaking Changes
+- `BaseAgent` no longer stores a context instance. `self.context`, `reset_context()`, `clear_messages()`, `window_messages()`, and `reset()` are removed. `Agent.__init__` no longer accepts a `context=` keyword argument.
+- Multi-turn sessions must now be managed by the caller: pass `context=` to each `run()`/`run_stream()` call and capture the returned context from `AgentResponse.context`.
+
+### Changed
+- `Agent.run(task=None, context=None, ...)` and `Agent.run_stream(task=None, context=None, ...)` accept a per-call `AgentContext`. When `None`, a fresh context is created automatically.
+- `AgentResponse.context` returns the fully-populated working context to the caller after every run.
+- `AgentAsTool.execute(parameters, context=None)` and `execute_stream(parameters, context=None, ...)` thread the caller-supplied context through to the underlying agent.
+- `AgentToolCompatible` protocol updated to include `context=None` on both `execute` and `execute_stream`.
+
+### Documentation
+- `topic_agents.md`: Parts 2.5 (lock-free context threading) and 2.6 (agent-as-tool context) added.
+- `topic_approval.md`: Tool approval resume pattern updated to `agent.run(context=first_response.context)`.
+- `topic_otel_spans.md`: Dummy trace ID notes added; `args: {}` vs `TOOL PARAMETERS` discrepancy explained; known limitation section for parsed args not captured in chat span attributes.
+- Notebooks `04-agent-with-context`, `07-agent-as-tool-coordinator`, `04.2-metadata-extraction-large-doc` updated to caller-owned context pattern.
+
 ## [0.2.7] - 2026-03-03
 
 ### Added

{agentbyte-0.2.7 → agentbyte-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.2.7
+Version: 0.3.0
 Summary: A toolkit for designing multiagent systems
 Project-URL: Homepage, https://gitlab.com/pyninja/aiengineering/agentbyte
 Project-URL: Repository, https://gitlab.com/pyninja/aiengineering/agentbyte
@@ -30,24 +30,24 @@ Requires-Dist: opentelemetry-sdk>=1.39.1; extra == 'otel'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.2.7/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.3.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.2.7**
+Current release: **0.3.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
-## What's New in 0.2.7
+## What's New in 0.3.0
 
-- `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.
+- **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](CHANGELOG.md) for the complete release history.
 
@@ -68,37 +68,22 @@ 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:
+Enable telemetry:
 
 ```bash
 export AGENTBYTE_ENABLE_OTEL=true
-export AGENTBYTE_OTEL_CAPTURE_USAGE=true
 ```
 
-Then inspect attributes such as:
+Per-call span attributes emitted by `OTelMiddleware`:
 
-- `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.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`
 
-## Debug Traces Without Jaeger UI
-
-If the Jaeger UI search page is slow or stuck, debug directly via APIs:
-
-```bash
-# 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>
-```
+## 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:
 
@@ -195,5 +180,4 @@ MIT — see [LICENSE](LICENSE).
 
 - [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
 - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-- [Pydantic AI](https://ai.pydantic.dev/)
 

{agentbyte-0.2.7 → agentbyte-0.3.0}/README.md

@@ -1,22 +1,22 @@
 <p align="center">
-  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.2.7/logo/agent-byte-avatar-low.png" alt="Agentbyte" width="200"/>
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.3.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.2.7**
+Current release: **0.3.0**
 
 Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
 
-## What's New in 0.2.7
+## What's New in 0.3.0
 
-- `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.
+- **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](CHANGELOG.md) for the complete release history.
 
@@ -37,37 +37,22 @@ 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:
+Enable telemetry:
 
 ```bash
 export AGENTBYTE_ENABLE_OTEL=true
-export AGENTBYTE_OTEL_CAPTURE_USAGE=true
 ```
 
-Then inspect attributes such as:
+Per-call span attributes emitted by `OTelMiddleware`:
 
-- `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.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`
 
-## Debug Traces Without Jaeger UI
-
-If the Jaeger UI search page is slow or stuck, debug directly via APIs:
-
-```bash
-# 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>
-```
+## 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:
 
@@ -164,5 +149,4 @@ MIT — see [LICENSE](LICENSE).
 
 - [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
 - [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
-- [Pydantic AI](https://ai.pydantic.dev/)
 

agentbyte-0.3.0/docs/progress.md

@@ -0,0 +1,81 @@
+# Progress Log (Compact)
+
+This file keeps a concise, high-signal history of major milestones only.
+
+## 2026-03-06 — v0.3.0 (Breaking) Lock-Free Context Threading
+
+### Scope
+- Refactored agent execution to caller-owned context.
+- Removed agent-held mutable session state.
+- Updated docs/notebooks to match the new usage pattern.
+
+### Design Decision
+- `AgentContext` is passed per call and returned via `AgentResponse.context`.
+- This removes shared mutable state from agents and enables safe concurrent reuse.
+
+### Breaking Changes
+- Removed agent-owned context API:
+  - `self.context`
+  - `reset_context()`
+  - `clear_messages()`
+  - `window_messages()`
+  - `reset()`
+- `Agent.__init__(context=...)` no longer supported.
+
+### New Usage Pattern
+- `run(task=None, context=None, ...)`
+- `run_stream(task=None, context=None, ...)`
+- Continue multi-turn sessions by reusing `response.context`.
+
+### Related Updates
+- Agent-as-tool context threading updated.
+- Study docs and notebooks aligned with caller-owned context.
+- OTel trace guide clarified `args: {}` vs tool-parameter spans.
+
+### Validation
+- Ruff: passed.
+- Pytest: 256 passed.
+
+---
+
+## 2026-03-05 — OTel Simplification + Trace Inspector
+
+### Scope
+- Simplified OTel architecture and removed unnecessary root-span usage aggregation.
+- Added local Jaeger trace inspection utility.
+
+### Outcomes
+- Per-call `chat` and `tool` spans remain the primary observability surface.
+- Added `examples/otel/inspect_trace.py` for full trace/message inspection.
+- Updated tests and docs; suite remained green.
+
+---
+
+## 2026-03-02 — Session Model Unification
+
+### Scope
+- Unified conversation/workspace into a single session model.
+
+### Outcomes
+- Consolidated to `Session`, `BaseSession`, and `InMemorySession`.
+- Removed redundant conversation/workspace modules.
+- Updated context and package exports accordingly.
+
+---
+
+## 2026-02-26 to 2026-02-27 — Middleware/Memory/OTel Foundation
+
+### Scope
+- Completed Chapter 4.9/4.10-aligned foundations for middleware, memory operations, and telemetry.
+
+### Outcomes
+- Middleware streaming and approval flow integrated.
+- Memory tool and memory middleware routing added.
+- OTel middleware + auto instrumentation introduced and hardened.
+
+---
+
+## Current Status
+- Current release target in repository: **0.3.0**.
+- Primary branch is release-ready with validated tests.
+- Next: create release commit, tag `v0.3.0`, and push branch/tag.