agentbyte 0.20.3__tar.gz → 0.20.5__tar.gz

{agentbyte-0.20.3 → 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
@@ -444,7 +504,7 @@ def build_contract_agent(*, model_client) -> Agent:
         required_tools=["think"],
         max_iterations=6,
         example_tasks=[
-            "Who signed CW347209 from Novartis?",
+            "Who signed CW347209 from XYZ?",
             "List all contracts expiring in Q3 2025.",
         ],
     )
@@ -481,6 +541,7 @@ async def run_with_filters(
 ```python
 from agentbyte.agents import EmbeddingAgent
 from agentbyte.llm.openai import OpenAIEmbeddingClient
+from agentbyte.llm.types import EmbeddingResult
 from agentbyte.middleware import OTelMiddleware
 
 client = OpenAIEmbeddingClient.from_api_key(model="text-embedding-3-small")
@@ -510,6 +571,7 @@ print(f"Cost: ${result.usage.cost_estimate:.4f}, tokens: {result.usage.tokens_in
 
 ```python
 from agentbyte.agents import EmbeddingBatchProgressEvent
+from agentbyte.llm.types import EmbeddingResult
 
 async for event in agent.run_stream(texts=chunks):
     if isinstance(event, EmbeddingBatchProgressEvent):

{agentbyte-0.20.3 → 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.3 → 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.3 → 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.3 → 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.3 → 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.3 → agentbyte-0.20.5}/.github/skills/agentbyte-workflow/SKILL.md

@@ -101,6 +101,38 @@ FunctionStep(
 )
 ```
 
+Design guidance:
+
+- `input_type` and `output_type` should be concrete Pydantic model classes that represent the real data crossing the step boundary.
+- Prefer step outputs as the primary transport for business data that flows from one step to the next.
+- Use `WorkflowContext` for cross-cutting concerns such as progress, flags, lightweight shared metadata, and values that are needed outside the direct step-to-step path.
+
+Preferred pattern:
+
+```python
+from pydantic import BaseModel
+
+
+class ParsedInput(BaseModel):
+    record_id: str
+    file_name: str
+
+
+class EnrichedOutput(ParsedInput):
+    content_hash: str
+
+
+async def enrich(input_data: ParsedInput, context) -> EnrichedOutput:
+    context.set("started_enrichment", True)
+    return EnrichedOutput(
+        record_id=input_data.record_id,
+        file_name=input_data.file_name,
+        content_hash="abc123",
+    )
+```
+
+Avoid using placeholder or pass-through output types while putting the real business payload only into `WorkflowContext.state`. That pattern weakens validation, makes step contracts less clear, and pushes too much logic into string-keyed shared state.
+
 ### TransformStep
 
 Maps fields from one schema to another without custom code. Use `"static:<value>"` for literal values, or a field name string to copy from input.
@@ -341,6 +373,13 @@ async def step_b(input_data: MyOutput, context: WorkflowContext) -> MyOutput:
     return MyOutput(value=f"Got: {shared}")
 ```
 
+Use `WorkflowContext` intentionally:
+
+- Put primary business data in step outputs when that data is part of the direct step-to-step contract.
+- Put small shared values in `WorkflowContext` when they are cross-cutting, optional, or orthogonal to the main output shape.
+- For simple linear enrichment pipelines, a good default is typed outputs for the main payload plus a small amount of primitive state for bookkeeping.
+- Avoid making `WorkflowContext.state` the only source of truth for the workflow's main data flow unless the workflow genuinely needs loose coupling between many steps.
+
 `WorkflowContext` API:
 
 | Method | Purpose |
@@ -374,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
 
@@ -447,6 +500,14 @@ resumed_execution = await runner.run(
 
 The runner validates the checkpoint's structure hash against the live workflow graph on resume. If steps were added/removed, `can_resume=False` is set on the `CheckpointValidationResult`.
 
+State size guidance:
+
+- Workflow state is retained for the lifetime of the run.
+- When checkpointing is enabled, that state is serialized into checkpoints.
+- Prefer storing IDs, keys, counters, flags, and other small primitives in shared state.
+- Avoid storing large domain objects, open clients, or heavyweight in-memory payloads in `WorkflowContext.state` unless they are truly required for resume semantics.
+- If a step can reconstruct a full object from a lightweight identifier, prefer storing the identifier and reconstructing on demand.
+
 ---
 
 ## 11. Suspend / resume — human-in-the-loop
@@ -556,10 +617,13 @@ if not validation.is_valid:
 ## Guardrails
 
 - Use `chain()` for linear flows; use `add_step()` + `add_edge()` only when branching or fan-out is required.
+- Design `FunctionStep` input and output types as real Pydantic contracts for the data flowing between steps; do not use placeholder output models when the actual payload lives only in workflow state.
+- Use step outputs for primary business data flow, and reserve `WorkflowContext.state` for compact shared metadata, flags, and bookkeeping.
+- Keep workflow state small and checkpoint-friendly; prefer IDs and lightweight values over large domain objects.
 - A fan-in join step with ≥ 2 upstream `always` edges receives `{"branch_outputs": {...}, "failed_branches": [...]}` — its input model must declare these fields, not the upstream output shape.
 - Always pass a workflow factory (callable) to `SubWorkflowStep`, not a live instance — the runner calls it to get a fresh copy per execution.
 - Do not pass `initial_input` and `responses` together — they are mutually exclusive.
 - `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.