agentbyte 0.20.4__tar.gz → 0.20.5__tar.gz

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-agent/SKILL.md

@@ -80,6 +80,38 @@ print(response.final_content)        # assistant's final text
 print(response.messages[-1].content) # same, from message list
 ```
 
+### Operation logging for run()
+
+To see middleware logs from `agent.run(...)`, configure Python logging and add
+`LoggingMiddleware`. The middleware emits records; logging configuration decides
+whether they appear on stdout/stderr.
+
+```python
+import logging
+
+from agentbyte.agents import Agent
+from agentbyte.middleware import LoggingMiddleware
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+
+agent = Agent(
+    name="my-agent",
+    description="Answers simple questions.",
+    instructions="Answer concisely.",
+    model_client=client,
+    middlewares=[LoggingMiddleware()],
+)
+
+response = await agent.run("hello")
+```
+
+Use `model_client=...` and `middlewares=[...]` in Agentbyte. Passing only
+`LoggingMiddleware()` is not enough if the host application has not configured
+Python logging to show `INFO` records.
+
 ### Multi-turn (stateful — caller owns context)
 
 ```python
@@ -108,6 +140,27 @@ async for event in agent.run_stream(
 # Final AgentResponse is the last item yielded
 ```
 
+### Console stream printing
+
+Use the preset printer for readable notebook or terminal debugging instead of
+writing custom `isinstance(...)` dispatch in examples.
+
+```python
+from agentbyte.presets import ConsoleStreamPrinter, run_agent_stream
+
+response = await run_agent_stream(
+    agent,
+    "Summarise the last 3 contracts.",
+)
+
+printer = ConsoleStreamPrinter(max_chars=1000)
+async for item in agent.run_stream("Summarise the last 3 contracts.", verbose=True):
+    printer.print(item)
+```
+
+`run_agent_stream()` prints stream items and returns the final
+`AgentResponse`. It defaults to `verbose=True` and `stream_tokens=False`.
+
 ### Stream logging with StreamEventLogger
 
 Use `verbose=True` to emit execution events, then pass every streamed item to
@@ -141,7 +194,8 @@ async for item in agent.run_stream(
 
 `StreamEventLogger` covers execution-layer events from `run_stream()`. It
 complements `LoggingMiddleware`, which logs model and tool operations inside the
-middleware chain.
+middleware chain. Use `ConsoleStreamPrinter` for human-readable terminal output;
+use `StreamEventLogger` for structured Python logs.
 
 ### run() parameters
 
@@ -353,6 +407,12 @@ response = await coordinator.run("What is the weather in Berlin in Celsius?")
 
 `AgentAsTool` also accepts `context=` forwarding in `execute()` — pass a pre-seeded context to give the specialist prior history.
 
+`AgentAsTool.execute_stream()` invokes the delegated child agent with
+`verbose=True` and `stream_tokens=False`. This lets nested child-agent events
+flow through a parent `agent.run_stream(..., verbose=True)` call for
+`StreamEventLogger` or `ConsoleStreamPrinter`, while avoiding noisy nested token
+chunks.
+
 ### Manual construction
 
 ```python

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-ai-driven-orchestration/SKILL.md

@@ -102,6 +102,16 @@ asyncio.run(main())
 
 ## Pattern: Streaming AI-Driven Orchestration
 
+For readable terminal output:
+
+```python
+from agentbyte.presets import run_orchestrator_stream
+
+result = await run_orchestrator_stream(orchestrator, task)
+```
+
+For structured Python logs:
+
 ```python
 from agentbyte.logger import StreamEventLogger
 
@@ -113,11 +123,6 @@ async for item in orchestrator.run_stream(task, verbose=True):
     stream_logger.warning(item)
     stream_logger.error(item)
     stream_logger.exception(item)
-
-    if isinstance(item, Message):
-        print(f"[{item.source}] {item.content}")
-    elif isinstance(item, OrchestrationResponse):
-        print(f"Complete: {item.stop_message.content}")
 ```
 
 ## How AI Selection Works
@@ -273,7 +278,7 @@ termination = (
 - **Safety Fallback:** If LLM selection fails, the orchestrator falls back to round-robin selection to preserve forward progress.
 - **Usage Accounting:** Final usage includes both agent tokens AND selector tokens.
 - **Case Insensitive:** Agent name matching is case-insensitive for robustness.
-- **Event Observability:** Use `verbose=True` with `run_stream()` and pass items to `StreamEventLogger` for structured execution logs, including selector events.
+- **Event Observability:** Use `verbose=True` with `run_stream()` and pass items to `StreamEventLogger` for structured execution logs, including selector events. Use `run_orchestrator_stream()` / `ConsoleStreamPrinter` for readable terminal output.
 
 ## When to Use AI-Driven vs Round-Robin
 

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-handoff-orchestration/SKILL.md

@@ -85,10 +85,18 @@ asyncio.run(main())
 
 ## Pattern: Streaming Handoff Orchestration
 
+For readable terminal output:
+
+```python
+from agentbyte.presets import run_orchestrator_stream
+
+result = await run_orchestrator_stream(orchestrator, task)
+```
+
+For structured Python logs:
+
 ```python
 from agentbyte.logger import StreamEventLogger
-from agentbyte.messages import Message
-from agentbyte.types import OrchestrationResponse
 
 stream_logger = StreamEventLogger()
 
@@ -98,11 +106,6 @@ async for item in orchestrator.run_stream(task, verbose=True):
     stream_logger.warning(item)
     stream_logger.error(item)
     stream_logger.exception(item)
-
-    if isinstance(item, Message):
-        print(f"[{item.source}] {item.content}")
-    elif isinstance(item, OrchestrationResponse):
-        print(f"Complete: {item.stop_message.content}")
 ```
 
 ## How Handoff Routing Works

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-middleware/SKILL.md

@@ -117,13 +117,43 @@ agent = Agent(
 
 ### LoggingMiddleware
 
+`LoggingMiddleware` emits standard Python log records. It does not configure
+handlers by itself, so examples and notebooks must configure logging before the
+agent runs.
+
 ```python
+import logging
+
+from agentbyte.agents import Agent
 from agentbyte.middleware import LoggingMiddleware
 
-agent = Agent(..., middlewares=[LoggingMiddleware()])
-# Logs at INFO level under logger "agentbyte.middleware"
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+
+agent = Agent(
+    name="my-agent",
+    description="Demonstrates operation logging.",
+    instructions="Answer concisely.",
+    model_client=client,
+    middlewares=[LoggingMiddleware()],
+)
+
+result = await agent.run("hello")
 ```
 
+Logs are emitted under logger name `agentbyte.middleware`. If the application
+already configured logging, set that logger level explicitly instead of calling
+`basicConfig()` again:
+
+```python
+logging.getLogger("agentbyte.middleware").setLevel(logging.INFO)
+```
+
+Use `middlewares=[...]` and `model_client=...`; `middleware=` and `model=` are
+not Agent constructor parameters.
+
 ### GuardrailMiddleware
 
 ```python

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-plan-based-orchestration/SKILL.md

@@ -114,10 +114,18 @@ asyncio.run(main())
 
 ## Pattern: Streaming Plan-Based Orchestration
 
+For readable terminal output:
+
+```python
+from agentbyte.presets import run_orchestrator_stream
+
+result = await run_orchestrator_stream(orchestrator, task)
+```
+
+For structured Python logs:
+
 ```python
 from agentbyte.logger import StreamEventLogger
-from agentbyte.messages import Message
-from agentbyte.types import OrchestrationResponse
 
 stream_logger = StreamEventLogger()
 
@@ -127,12 +135,6 @@ async for item in orchestrator.run_stream(task, verbose=True):
     stream_logger.warning(item)
     stream_logger.error(item)
     stream_logger.exception(item)
-
-    if isinstance(item, Message):
-        print(f"[MSG][{item.source}] {item.content}")
-    elif isinstance(item, OrchestrationResponse):
-        print(f"Complete: {item.stop_message.content}")
-        print(f"Steps completed: {item.pattern_metadata.get('steps_completed')}")
 ```
 
 ## How Plan-Based Orchestration Works
@@ -284,4 +286,3 @@ This makes plan-based orchestration more expensive than simpler patterns, but mu
 3. Gather evidence -> synthesize -> present answer
 4. Multi-step analyst/reporter/editor collaboration
 5. Quality-sensitive tasks where each phase should be checked before moving on
-

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-round-robin-orchestration/SKILL.md

@@ -71,6 +71,16 @@ asyncio.run(main())
 
 ## Pattern: Streaming Round-Robin
 
+For readable terminal output:
+
+```python
+from agentbyte.presets import run_orchestrator_stream
+
+result = await run_orchestrator_stream(orchestrator, task)
+```
+
+For structured Python logs:
+
 ```python
 from agentbyte.logger import StreamEventLogger
 
@@ -82,11 +92,6 @@ async for item in orchestrator.run_stream(task, verbose=True):
     stream_logger.warning(item)
     stream_logger.error(item)
     stream_logger.exception(item)
-
-    if isinstance(item, Message):
-        print(f"[{item.source}] {item.content}")
-    elif isinstance(item, OrchestrationResponse):
-        print(f"Complete: {item.stop_message.content}")
 ```
 
 ## Available Termination Conditions
@@ -220,7 +225,7 @@ result = await orchestrator.run(task, context=ctx, cancellation_token=token)
 - **Safety Limit:** Set `max_iterations` as a failsafe even with other termination conditions.
 - **Shared Context:** By default all agents see full history as text, but `HistoryContextPolicy` can narrow the window or change the format.
 - **Model Client:** Each agent needs its own `model_client` configured.
-- **Event Observability:** Use `verbose=True` with `run_stream()` and pass items to `StreamEventLogger` for structured execution logs.
+- **Event Observability:** Use `verbose=True` with `run_stream()` and pass items to `StreamEventLogger` for structured execution logs. Use `run_orchestrator_stream()` / `ConsoleStreamPrinter` for readable terminal output.
 
 ## Common Use Cases
 

{agentbyte-0.20.4 → agentbyte-0.20.5}/.github/skills/agentbyte-workflow/SKILL.md

@@ -413,6 +413,20 @@ execution.error           # str | None — set when status == FAILED
 
 ## 9. Streaming workflow events
 
+For human-readable terminal or notebook output, use the console streaming preset:
+
+```python
+from agentbyte.presets import ConsoleStreamPrinter, run_workflow_stream
+
+execution = await run_workflow_stream(workflow, {"value": 5})
+
+printer = ConsoleStreamPrinter()
+async for event in WorkflowRunner().run_stream(workflow, {"value": 5}):
+    printer.print(event)
+```
+
+For structured Python logs, use `StreamEventLogger`:
+
 ```python
 from agentbyte.logger import StreamEventLogger
 
@@ -612,4 +626,4 @@ if not validation.is_valid:
 - `request_input()` and `request_approval()` never return; code after them runs only on resume.
 - Do not thread `AgentContext` through `WorkflowContext.state` — keep it in `AgentbyteAgentInput.agent_context`.
 - `WorkflowRunner` is not thread-safe across concurrent runs of the same workflow instance; use one runner per concurrent workflow.
-- Workflow logging is event-driven today — use `run_stream()` for observability, and pair it with `StreamEventLogger` when you want standard Python log output.
+- Workflow logging is event-driven today — use `run_stream()` for observability, pair it with `StreamEventLogger` for structured Python logs, and use `ConsoleStreamPrinter` / `run_workflow_stream()` for readable terminal output.

agentbyte-0.20.5/.github/skills/webui-smoke-test/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: webui-smoke-test
+description: Step-by-step guide for smoke testing the Agentbyte WebUI server with curl. Use this when you need to validate discovery, agent streaming, multi-turn persistence, orchestrator execution, or workflow execution. Includes curl examples, expected responses, and debugging tips.
+license: MIT
+---
+
+Use this skill when you need to **validate that the WebUI server is working correctly** across all entity types (agents, orchestrators, workflows) with real API credentials.
+
+## Prerequisites
+
+1. **Server running**: `uv run python examples/webui/presets_webui.py`
+2. **API credentials configured**: `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` exported
+3. **Tools available**: `curl`, `jq` (optional, for output formatting), `uuidgen`
+4. **Base URL**: `http://127.0.0.1:8080` (adjust host/port if needed)
+
+## Critical: Message Format
+
+**All messages sent to the API must include a `source` field.** This is required by the BaseMessage Pydantic schema.
+
+❌ **Wrong:**
+```json
+{"role": "user", "content": "What is AI?"}
+```
+
+✅ **Correct:**
+```json
+{"role": "user", "content": "What is AI?", "source": "user"}
+```
+
+## Step 1: Verify Discovery Endpoint
+
+**Purpose**: Check that all entities are registered and discoverable.
+
+```bash
+curl -s http://127.0.0.1:8080/api/entities | jq .
+```
+
+**Expected Response**:
+- JSON array of 8+ entity objects
+- Each has: `id`, `name`, `type`, `description`, `model`, `tools`
+- For presets_webui.py: `query_rewriter`, `researcher`, `writer`, `reviewer` (agents)
+- For presets_webui.py: `round_robin_team`, `ai_team`, `plan_based_team` (orchestrators)
+- For presets_webui.py: `research_writer_reviewer_workflow` (workflow)
+
+**Debug if it fails**:
+- Server not running? → `uv run python examples/webui/presets_webui.py`
+- Port in use? → Check with `lsof -i :8080` and kill if needed
+- CORS error? → Check server logs for middleware issues
+
+---
+
+## Step 2: Test Agent Streaming (Turn 1)
+
+**Purpose**: Verify single-turn agent execution with SSE streaming.
+
+```bash
+session_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+user_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+
+echo "Session: $session_id"
+echo "User: $user_id"
+
+curl -N -X POST http://127.0.0.1:8080/api/entities/query_rewriter/run/stream \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Rewrite: impacts of AI on hiring\",\"source\":\"user\"}],\"session_id\":\"$session_id\",\"user_id\":\"$user_id\",\"stream_tokens\":false}"
+```
+
+**Expected Sequence**:
+1. `data:` line with `event_type: "model_call"` → Model is being invoked
+2. `data:` line with `event_type: "model_response"` → Model returned tokens
+3. `data:` line with `role: "assistant"` → Final response message
+4. `data:` line with `event_type: "task_complete"` → Execution finished
+5. Final `data:` line with `context.messages` array → Session persisted
+
+**Expected Content**:
+- All `data:` lines are WebUIStreamEvent JSON: `{session_id, timestamp, event}`
+- `session_id` matches what you sent
+- `event` contains framework payloads (model_call, model_response, message, task_complete)
+
+**Debug if it fails**:
+- HTTP 400? → Check message format includes `source` field
+- HTTP 404? → Entity doesn't exist, verify entity_id is correct
+- HTTP 500? → Check server logs for actual error (usually API credential or validation issue)
+- No streaming output? → Try without `-N` flag, or check if server is hung
+- Timeout? → Model may be slow; wait or check OPENAI_API_KEY is valid
+
+**Save the session_id** — you'll reuse it in Step 3.
+
+---
+
+## Step 3: Verify Multi-Turn Persistence
+
+**Purpose**: Confirm agent sees prior conversation history and adapts responses.
+
+```bash
+# Use session_id and user_id from Step 2
+curl -N -X POST http://127.0.0.1:8080/api/entities/query_rewriter/run/stream \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Make it even shorter\",\"source\":\"user\"}],\"session_id\":\"$session_id\",\"user_id\":\"$user_id\",\"stream_tokens\":false}" \
+  | grep -E '"content"|"role"|"event_type"' | head -20
+```
+
+**Expected Behavior**:
+- In the `model_call` event, `input_messages` array should contain:
+  1. System message (if configured)
+  2. Turn 1 user message + response
+  3. Turn 2 user message (the "Make it shorter" request)
+- Agent's response should be **shorter than Turn 1** — proof it understood context
+- Final context should have **4+ messages** (system, turn1_user, turn1_asst, turn2_user, turn2_asst)
+
+**Debug if it fails**:
+- No prior messages in input? → Session not persisting, check SessionManager and session store
+- Agent not adapting? → Model may not have received context; check input_messages array size
+- Different response? → Normal variation; ensure it's shorter, not just different wording
+
+---
+
+## Step 4: Test Orchestrator Execution
+
+**Purpose**: Verify multi-agent orchestration with non-streaming endpoint.
+
+```bash
+session_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+user_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+
+curl -s -X POST http://127.0.0.1:8080/api/entities/round_robin_team/run \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Research AI and hiring, then write a summary\",\"source\":\"user\"}],\"session_id\":\"$session_id\",\"user_id\":\"$user_id\"}" \
+  | jq '{final_result: .final_result, messages_count: (.messages | length), stop_reason: .stop_reason}'
+```
+
+**Expected Response**:
+- `final_result` contains the orchestrator's final output (usually from the last agent)
+- `messages` array has **3+ messages**:
+  - User's initial request
+  - Researcher's contribution
+  - Writer's contribution (or other agents in round-robin order)
+- `stop_reason` shows why orchestration terminated (e.g., "Text mention found: 'TERMINATE'")
+- `stop_message` object with details
+
+**Expected Behavior**:
+- All agents in the team should have contributed to `messages`
+- Agents should have passed context between turns
+- Output should synthesize contributions (e.g., research facts → written summary)
+
+**Debug if it fails**:
+- HTTP 500? → Check if OpenAI API is working (use agent test first)
+- Only 1 message in array? → Agents aren't running; check orchestrator configuration
+- No final_result? → Orchestrator may have failed; check stop_reason and server logs
+- Timeout? → Orchestrator running multiple agents; may take 30+ seconds
+
+---
+
+## Step 5: Test Workflow Execution
+
+**Purpose**: Verify deterministic workflow DAG execution.
+
+```bash
+session_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+user_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+
+curl -s -X POST http://127.0.0.1:8080/api/entities/research_writer_reviewer_workflow/run \
+  -H "Content-Type: application/json" \
+  -d "{\"input_data\":{\"task\":\"Write a 2 sentence note about solar energy benefits.\"},\"session_id\":\"$session_id\",\"user_id\":\"$user_id\"}" \
+  | jq '{status: .status, step_count: (.step_executions | length), state_keys: (.state | keys)}'
+```
+
+**Expected Response**:
+- `status: "completed"`
+- `step_executions` is a **dict** keyed by step name with **6+ entries** (one per DAG step); `| length` in jq works on both dicts and arrays
+- `state` object has keys like `researcher_output`, `writer_draft`, `reviewer_output` (varies by workflow)
+- Each step value has a `status: "completed"` field; `duration_ms` may not be present at top level
+
+**Expected Behavior**:
+- Steps execute in DAG order (dependencies respected)
+- Each step uses output from prior steps
+- Final state includes all intermediate and final outputs
+- Workflow completes within reasonable time (30-120 seconds for research_writer_reviewer_workflow)
+
+**Debug if it fails**:
+- HTTP 500? → Check OpenAI API; workflows use multiple agent calls
+- `step_executions` empty or too few? → Workflow may have errored; check server logs
+- Status not "completed"? → Check error messages in response
+- Timeout? → Workflows run multiple sequential steps; increase curl timeout with `--max-time 120`
+
+---
+
+## Full Smoke Test Script
+
+Save this as `smoke_test.sh` for quick reuse:
+
+```bash
+#!/bin/bash
+set -e
+
+BASE_URL="${1:-http://127.0.0.1:8080}"
+echo "🔍 Testing WebUI server at $BASE_URL"
+echo ""
+
+# Step 1: Discovery
+echo "1️⃣ Testing Discovery Endpoint..."
+ENTITY_COUNT=$(curl -s "$BASE_URL/api/entities" | jq 'length')
+echo "   ✅ Found $ENTITY_COUNT entities"
+echo ""
+
+# Step 2: Agent Streaming
+echo "2️⃣ Testing Agent Streaming (Turn 1)..."
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+USER_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+echo "   Session: $SESSION_ID"
+
+STREAM_EVENTS=$(curl -s -N -X POST "$BASE_URL/api/entities/query_rewriter/run/stream" \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Rewrite: impacts of AI on hiring\",\"source\":\"user\"}],\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"stream_tokens\":false}" \
+  | grep -c "data:" || true)
+echo "   ✅ Received $STREAM_EVENTS SSE frames"
+echo ""
+
+# Step 3: Multi-turn
+echo "3️⃣ Testing Multi-Turn Persistence (Turn 2)..."
+STREAM_EVENTS_T2=$(curl -s -N -X POST "$BASE_URL/api/entities/query_rewriter/run/stream" \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Make it shorter\",\"source\":\"user\"}],\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\",\"stream_tokens\":false}" \
+  | grep -c "data:" || true)
+echo "   ✅ Received $STREAM_EVENTS_T2 SSE frames (context preserved)"
+echo ""
+
+# Step 4: Orchestrator
+echo "4️⃣ Testing Orchestrator Execution..."
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+ORCH_RESULT=$(curl -s -X POST "$BASE_URL/api/entities/round_robin_team/run" \
+  -H "Content-Type: application/json" \
+  -d "{\"messages\":[{\"role\":\"user\",\"content\":\"Write a 2 sentence note about solar energy.\",\"source\":\"user\"}],\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\"}")
+MSG_COUNT=$(echo "$ORCH_RESULT" | jq '.messages | length')
+echo "   ✅ Orchestrator produced $MSG_COUNT messages"
+echo ""
+
+# Step 5: Workflow
+echo "5️⃣ Testing Workflow Execution..."
+SESSION_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+WF_RESULT=$(curl -s -X POST "$BASE_URL/api/entities/research_writer_reviewer_workflow/run" \
+  -H "Content-Type: application/json" \
+  -d "{\"input_data\":{\"task\":\"Write 1 sentence about solar energy.\"},\"session_id\":\"$SESSION_ID\",\"user_id\":\"$USER_ID\"}")
+WF_STATUS=$(echo "$WF_RESULT" | jq -r '.status')
+STEP_COUNT=$(echo "$WF_RESULT" | jq '.step_executions | length')
+echo "   ✅ Workflow status: $WF_STATUS ($STEP_COUNT steps)"
+echo ""
+
+echo "✅ All smoke tests passed!"
+```
+
+**Run it**:
+```bash
+chmod +x smoke_test.sh
+./smoke_test.sh
+# or with custom base URL:
+./smoke_test.sh http://prod-server:8080
+```
+
+---
+
+## Common Issues & Solutions
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| HTTP 400 | Missing `source` field in message | Add `"source":"user"` to every message |
+| HTTP 404 | Entity doesn't exist | Verify entity_id in discovery response |
+| HTTP 500 | API credential invalid/expired | Check `$OPENAI_API_KEY` or Azure credentials |
+| HTTP 500 | Rate limit hit | Wait 60s and retry |
+| No output | Server not running | `uv run python examples/webui/presets_webui.py` |
+| No SSE frames | `-N` flag needed | Use `-N` flag for streaming: `curl -N ...` |
+| Timeout | Model responding slowly | Increase timeout: `--max-time 120` |
+| Session not persisting | Wrong session store | Check config; use in-memory for dev tests |
+
+---
+
+## Debugging with Verbose Output
+
+```bash
+# See full HTTP headers and response:
+curl -v -X POST http://127.0.0.1:8080/api/entities/query_rewriter/run/stream \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"test","source":"user"}],"session_id":"xyz","user_id":"abc","stream_tokens":false}' \
+  2>&1 | head -50
+
+# See just the first SSE frame:
+curl -N -X POST http://127.0.0.1:8080/api/entities/query_rewriter/run/stream \
+  -H "Content-Type: application/json" \
+  -d '...' \
+  2>/dev/null | head -1 | jq .
+
+# Parse event types from stream:
+curl -N -X POST http://127.0.0.1:8080/api/entities/query_rewriter/run/stream \
+  -H "Content-Type: application/json" \
+  -d '...' \
+  2>/dev/null | grep -oP '"event_type":\s*"\K[^"]+' | sort | uniq -c
+```
+
+---
+
+## Success Criteria
+
+✅ **Smoke tests pass if**:
+1. Discovery returns entity array
+2. Agent streaming produces 4+ SSE frames
+3. Multi-turn context includes prior messages
+4. Orchestrator produces 2+ agent messages
+5. Workflow completes all steps
+
+✅ **You can now**:
+- Deploy to dev/staging with confidence
+- Debug specific entity types using this guide
+- Add new entities and rerun smoke tests
+- Use curl patterns as frontend request templates

{agentbyte-0.20.4 → agentbyte-0.20.5}/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.20.5] - 2026-05-20
+
+### Added
+
+- Added `agentbyte.presets.streaming` with `ConsoleStreamPrinter`, `render_stream_item`, `run_agent_stream()`, `run_orchestrator_stream()`, and `run_workflow_stream()` for readable terminal/notebook stream inspection.
+- Exported the console streaming helpers from `agentbyte.presets` and the top-level `agentbyte` package.
+- Added focused tests for stream rendering, helper return values, package exports, workflow-as-agent event forwarding, and delegated agent-as-tool streaming.
+- Added `docs/study/01-agent_topics/topic_console_streaming_preset.md` and cross-referenced it from the agent and stream logger study topics.
+
+### Changed
+
+- `WorkflowAgent.run_stream(verbose=True)` now forwards underlying workflow events before yielding the final agent-style `AssistantMessage` and `AgentResponse`; `verbose=False` preserves the quiet final-output behavior.
+- `AgentAsTool.execute_stream()` now invokes delegated child agents with `verbose=True` and `stream_tokens=False`, allowing nested child-agent events to flow through parent verbose streams without nested token noise.
+- Updated repo-local `.github/skills` guidance for agents, workflows, orchestration, and middleware logging, including explicit `LoggingMiddleware` setup with Python logging configuration.
+
+---
+
 ## [0.20.4] - 2026-05-18
 
 ### Fixed

{agentbyte-0.20.4 → agentbyte-0.20.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbyte
-Version: 0.20.4
+Version: 0.20.5
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -76,7 +76,7 @@ Description-Content-Type: text/markdown
 
 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 release: **0.20.5**
 
 ## Current Capabilities
 
@@ -84,6 +84,7 @@ Current release: **0.20.4**
 - Tooling system (function tools + core tools + memory tool).
 - Middleware chain for request/response/error handling.
 - Built-in middleware: logging, security, rate limiting, approval, telemetry.
+- Console stream printing presets for readable agent, orchestrator, and workflow debugging.
 - 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.