agentbyte 0.7.0__tar.gz → 0.9.0__tar.gz

{agentbyte-0.7.0 → agentbyte-0.9.0}/.github/skills/agentbyte-plan-based-orchestration/SKILL.md

@@ -19,6 +19,7 @@ import asyncio
 from agentbyte import (
     Agent,
     AgentHistoryPolicy,
+    FinalResultPolicy,
     HistoryContextPolicy,
     PlanBasedOrchestrator,
     ReviewGatePolicy,
@@ -84,7 +85,11 @@ async def main():
             revision_agent_name="writer",
             approval_signal="APPROVED",
             max_revision_rounds=2,
-            prefer_final_result_from_agent="writer",
+        ),
+        final_result_policy=FinalResultPolicy(
+            prefer_agent="writer",
+            strip_signals=["APPROVED"],
+            strip_mode="trailing",
         ),
     )
 

{agentbyte-0.7.0 → agentbyte-0.9.0}/.github/skills/agentbyte-workflow/SKILL.md

@@ -82,7 +82,7 @@ Use `run_stream()` when you need logging, live progress, or execution telemetry.
 - `FunctionStep`: wrap sync/async Python functions
 - `TransformStep`: map fields between schemas
 - `HttpStep`: perform HTTP requests
-- `AgentbyteAgentStep`: wrap an Agentbyte agent inside a deterministic workflow
+- `AgentStep`: wrap an Agentbyte agent inside a deterministic workflow
 - `EchoStep`: simple testing/demo step
 
 ## Construction Process
@@ -97,7 +97,7 @@ Use `run_stream()` when you need logging, live progress, or execution telemetry.
 - `StepCompletedEvent` and `StepFailedEvent` include `duration_seconds`.
 - `StepStartedEvent` includes `input_data`.
 - `StepCompletedEvent` includes `output_data`.
-- `Context.emit_progress(...)` inside a step produces `StepProgressEvent`.
+- `context.emit_progress(...)` (`WorkflowContext` method) inside a step produces `StepProgressEvent`.
 - The runner also creates per-step OTel spans when tracing is enabled.
 
 ## Defaults
@@ -105,10 +105,57 @@ Use `run_stream()` when you need logging, live progress, or execution telemetry.
 - Use `WorkflowRunner.run_stream(...)` when debugging or logging execution.
 - Use `context.emit_progress(...)` for long-running steps that should report intermediate status.
 
-## Pattern: AgentContext Opt-In with AgentbyteAgentStep
+## Pattern: WorkflowContext — Cross-Step State Sharing
+
+Each `FunctionStep` receives a `WorkflowContext` as its second argument.
+Use `context.set()` / `context.get()` to pass values between steps without
+embedding them in typed Pydantic output models.
+
+```python
+from agentbyte.workflow import Workflow, WorkflowConfig, WorkflowRunner, WorkflowContext
+from agentbyte.workflow.steps import FunctionStep, StepMetadata
+from pydantic import BaseModel
+
+
+class MyInput(BaseModel):
+    value: str
+
+
+class MyOutput(BaseModel):
+    value: str
+
+
+def step_a(input_data: MyInput, context: WorkflowContext) -> dict:
+    context.set("shared_value", input_data.value.upper())
+    return {"value": input_data.value}
+
+
+def step_b(input_data: MyOutput, context: WorkflowContext) -> dict:
+    shared = context.get("shared_value", "")
+    return {"value": f"Got: {shared}"}
+
+
+workflow = Workflow(WorkflowConfig(name="state_sharing"))
+workflow.chain(
+    FunctionStep("step_a", StepMetadata(name="step_a"), MyInput, MyOutput, step_a),
+    FunctionStep("step_b", StepMetadata(name="step_b"), MyOutput, MyOutput, step_b),
+)
+```
+
+`WorkflowContext` API:
+- `context.set(key, value)` — write into shared workflow state
+- `context.get(key, default)` — read from shared workflow state
+- `context.update({...})` — bulk write
+- `context.emit_progress(message, completed, total)` — emit a `StepProgressEvent`
+- `context.request_input(...)` — suspend and request typed external input
+- `context.request_approval(...)` — suspend and request human approval
+
+Import path: `from agentbyte.workflow import WorkflowContext`
+
+## Pattern: AgentContext Opt-In with AgentStep
 
 Workflows are pipelines — they do not thread conversation history by default.
-When an `AgentbyteAgentStep` needs session continuity (e.g., the same agent is
+When an `AgentStep` needs session continuity (e.g., the same agent is
 called across multiple workflow invocations), pass an `AgentContext` via
 `agent_context` on the input model.
 
@@ -118,7 +165,8 @@ import asyncio
 from agentbyte.context import AgentContext
 from agentbyte.session_store import CachedFileSessionStore
 from agentbyte.workflow import Workflow, WorkflowConfig, WorkflowRunner
-from agentbyte.workflow.steps import AgentbyteAgentStep, AgentbyteAgentInput, StepMetadata
+from agentbyte.workflow.steps import AgentStep, StepMetadata
+from agentbyte.workflow.steps.agentbyte_agent import AgentbyteAgentInput
 
 # Retrieve or create a persistent context for the agent in this step
 store = CachedFileSessionStore(".sessions")
@@ -126,7 +174,7 @@ session_id = "user-abc"
 ctx = await store.get(session_id) or AgentContext(session_id=session_id)
 
 # Pass context as part of the step input — it is not coupled to the workflow graph
-step = AgentbyteAgentStep("writer", StepMetadata(name="writer"), writer_agent)
+step = AgentStep("writer", StepMetadata(name="writer"), writer_agent)
 workflow = Workflow(WorkflowConfig(name="draft_pipeline"))
 workflow.add_step(step)
 
@@ -143,7 +191,7 @@ await store.save(session_id, ctx)
 Two distinct context types coexist in a workflow:
 | Type | Scope | Purpose |
 |------|-------|---------|
-| `Context` (workflow) | One workflow run | Pass state between steps |
+| `WorkflowContext` | One workflow run | Pass state between steps |
 | `AgentContext` | Across runs | Persist agent conversation history |
 
 `agent_context` is always optional. Omit it (or pass `None`) for a stateless
@@ -154,4 +202,4 @@ step that starts fresh every time.
 - Do not skip typed input/output models for non-trivial steps.
 - Do not assume workflow has agent-style middleware; logging should currently be done from streamed workflow events.
 - Prefer checkpoint/resume only when the workflow graph is stable and long-running execution makes it worthwhile.
-- Do not thread `AgentContext` through the workflow `Context` dict — keep it in `AgentbyteAgentInput.agent_context`.
+- Do not thread `AgentContext` through the `WorkflowContext` state dict — keep it in `AgentbyteAgentInput.agent_context`.

{agentbyte-0.7.0 → agentbyte-0.9.0}/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.9.0] - 2026-04-14
+
+### Added
+
+- Added `FinalResultPolicy` Pydantic model to the orchestration layer with `prefer_agent`, `strip_signals`, and `strip_mode` fields for explicit control over which agent message becomes the canonical `final_result`.
+- Added `_generate_final_result`, `_select_final_message`, and `_strip_signals` methods to `BaseOrchestrator`, replacing the bare last-assistant-message read with a policy-driven selection algorithm.
+- Wired `FinalResultPolicy` into `RoundRobinOrchestrator`, `AIOrchestrator`, and `PlanBasedOrchestrator` constructors and into all three preset builders in `agentbyte.presets`.
+- Added `FinalResultPolicy` to the `agentbyte.orchestration` and root `agentbyte` public exports.
+- Added `final_result` and `stop_reason` fields to `SessionMessagesResponse` so orchestrator session reloads include the persisted primary answer.
+- Added orchestrator-specific final-first presentation to the WebUI: the main chat surface shows only the user prompt and `final_result`, with agent turn-taking inside a collapsible inline Thinking section.
+- Added `final_result` and `stop_reason` persistence to orchestrator session metadata on both streaming and non-streaming paths in the execution engine.
+
+### Changed
+
+- Tightened writer preset prompt to prevent coordinator drift: writer now produces the final draft immediately without asking questions or suggesting additions.
+- Tightened reviewer preset prompt to enforce binary output: reviewer outputs only the approval signal or one specific revision sentence, no production or formatting suggestions.
+- Updated all three preset orchestrators to supply a `FinalResultPolicy` aligned with their control flow (TERMINATE strip for round-robin, APPROVED strip for AI-driven and plan-based).
+- Updated notebook `08.1-default-presets.ipynb` and `agentbyte-plan-based-orchestration` skill to use `FinalResultPolicy` instead of the removed `prefer_final_result_from_agent` field.
+
+### Fixed
+
+- Fixed orchestrator `final_result` always returning the reviewer's approval signal instead of the writer's output by implementing `FinalResultPolicy.prefer_agent` selection logic.
+- Fixed `_strip_signals` anywhere-mode to be truly case-insensitive using `re.IGNORECASE` instead of string replace variants.
+
+### Breaking Changes
+
+- Removed `ReviewGatePolicy.prefer_final_result_from_agent`. Migrate to `FinalResultPolicy(prefer_agent=...)` passed directly to the orchestrator constructor.
+
+## [0.8.0] - 2026-04-13
+
+### Added
+
+- Added SQL-backed usage logging middleware with a typed persistence contract plus SQLModel-backed storage for LLM usage records.
+- Added `examples/webui/in_memory.py` and `examples/webui/presets_webui.py` as concrete launchers for the packaged AgentByte WebUI.
+- Added plan-based orchestration to the preset-backed WebUI catalog so round-robin, AI-driven, and plan-based teams are all selectable from the same real-entities launcher.
+
+### Changed
+
+- Completed the `agentbyte.webui` session contract: WebUI sessions now support `user_id`, stricter session/entity binding, and injected durable session stores for persisted `AgentContext` reload across restarts.
+- Rebased and adapted the packaged WebUI frontend to AgentByte's backend contracts, including fixed session query handling, stable post-stream message refresh, richer workflow result rendering, cleaner orchestration event classification, and improved debug-panel payload inspection.
+- Extended agent and orchestrator WebUI usage surfaces to show both token counts and cost estimates when providers supply pricing data.
+- Removed the unused bundled examples-gallery flow and other stale picoagents-only frontend assumptions from the packaged WebUI.
+
+### Fixed
+
+- Fixed agent stream completion handling in the WebUI so final agent state events no longer fall through to `unknown`, immediate UI finalization works again, and post-stream session refresh reliably recalculates session totals.
+- Fixed round-robin and other orchestrator debug events so lifecycle payloads render as labeled orchestration events instead of opaque `unknown` entries.
+- Fixed workflow completion rendering so the WebUI shows terminal workflow outputs directly instead of dumping the raw completion envelope.
+
 ## [0.7.0] - 2026-04-09
 
 ### Added

agentbyte-0.9.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: agentbyte
+Version: 0.9.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
+Project-URL: Issues, https://gitlab.com/pyninja/aiengineering/agentbyte/-/issues
+Project-URL: Changelog, https://gitlab.com/pyninja/aiengineering/agentbyte/-/blob/main/CHANGELOG.md
+Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
+License-Expression: MIT
+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: boto3; 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'
+Requires-Dist: boto3; 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: 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: 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'
+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
+
+<p align="center">
+  <img src="https://gitlab.com/pyninja/aiengineering/agentbyte/-/raw/v0.9.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.9.0** — see [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+Repository: [gitlab.com/pyninja/aiengineering/agentbyte](https://gitlab.com/pyninja/aiengineering/agentbyte)
+
+## 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 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:
+
+```bash
+uv sync --extra webui
+```
+
+Step 2. Start the demo app:
+
+```bash
+uv run python examples/webui/basic_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 still the bundled demo:
+
+```bash
+uv run python examples/webui/basic_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
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## References
+
+- [Designing Multi-Agent Systems](https://github.com/victordibia/designing-multiagent-systems/tree/main)
+- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)