agentbyte 0.40.0__tar.gz → 0.42.0__tar.gz

{agentbyte-0.40.0 → agentbyte-0.42.0}/.gitignore

@@ -71,3 +71,6 @@ data/flatfiles/*
 *.sqlite-wal
 *.sqlite-shm
 *.writer.lock
+
+# marimo local session cache
+__marimo__/

{agentbyte-0.40.0 → agentbyte-0.42.0}/CHANGELOG.md

@@ -6,6 +6,73 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-04
+
+### Changed (breaking)
+
+- Orchestrators share the agent run contract (spec 0066 Part B). `BaseOrchestrator.run` and
+  `run_stream` take the agent parameter order `(task=None, context=None, cancellation_token=None,
+  ...)` and return the same `AgentResponse` as agents. Team-only detail is on the new optional
+  `AgentResponse.orchestration` (`OrchestrationDetail`). `OrchestrationResponse` is removed.
+  Migration:
+
+  | Before | After |
+  |---|---|
+  | `isinstance(x, OrchestrationResponse)` | `isinstance(x, AgentResponse) and x.orchestration is not None` |
+  | `result.final_result` | `result.final_content` (or `result.orchestration.final_result`) |
+  | `result.final_structured_result` | `result.structured_output` |
+  | `result.stop_message` / `pattern_metadata` / `usage_breakdown` | `result.orchestration.<same>` |
+  | `result.messages` | unchanged (`context.messages`) |
+  | `run(task, token, context)` positional | `run(task, context, token)` |
+
+- A team response sets `source` (orchestrator name), `finish_reason` (mapped from the stop source:
+  `stop`, `max_iterations`, `max_iterations_finalized`, `approval_needed`, `error`, `cancelled`),
+  `error` (exception, synthesis failure, fallback), and `context` (the caller's context, updated in
+  place on every terminal path). `final_message` is the selected answer, not necessarily the last
+  message.
+- Cancelling a team now returns a response with `finish_reason="cancelled"`, as for agents, instead
+  of re-raising `CancelledError` after the final item.
+- `task=None` runs a team on the trailing user message(s) already in `context`.
+
+### Added
+
+- Orchestrator member event streaming (spec 0066 Part A): with `verbose=True`, member tool, model and
+  approval events are forwarded with `source` attribution; orchestration events gain `event_type`,
+  `turn_kind`, and per-turn `usage`; `run_stream` accepts `stream_tokens`.
+- Reserved final synthesis and full-run usage breakdown for orchestrators (spec 0065), and the
+  built-in `DescriptionTunable`.
+
+### Fixed
+
+- `PlanBasedOrchestrator` planned the oldest message of a multi-turn session instead of the current
+  task.
+- With `AGENTBYTE_ENABLE_OTEL` on, a failing orchestration was re-run untraced, duplicating turns
+  and cost.
+
+## [0.41.0] - 2026-10-04
+
+### Fixed
+
+- Tool-call-pair-safe recent history window (spec 0064). `BaseOrchestrator._select_history_messages`
+  implemented `AgentHistoryPolicy(window="recent")` as a blind `shared_messages[-message_limit:]`
+  slice, which could cut between a tool-calling `AssistantMessage` and its `ToolMessage` reply once
+  enough turns accumulated (a multi-step plan, or a step-retry loop), handing the next agent a
+  transcript that opens on an orphaned tool result and gets rejected by the provider. The `"recent"`
+  branch now reuses `agentbyte.compaction.grouping.group_messages` (spec 0049) to keep each tool
+  exchange whole, growing the window left by the few messages needed rather than splitting it.
+  `message_limit` is therefore a floor, not an exact count, only when a tool exchange would
+  otherwise be split; histories with no tool calls are unaffected. Lives in `BaseOrchestrator`, so
+  every pattern (`PlanBasedOrchestrator`, `AIOrchestrator`, `RoundRobinOrchestrator`,
+  `HandoffOrchestrator`) is covered by the one change.
+
+### Added
+
+- New optim usecase notebook `notebooks/usecases/optim/02-optim-it-helpdesk-triage.ipynb`: a
+  `PlanBasedOrchestrator` supervisor over three structured-output specialists (`hardware`,
+  `software`, `access-control`, each with a `lookup_asset` tool) plus a `synthesizer`, optimized
+  with `ReflectiveOptimizer` against a routing-correctness judge. Introduces a `DescriptionTunable`
+  (the planner routes off each member's `description`, which the built-in tunables did not expose).
+
 ## [0.40.0] - 2026-10-02
 
 ### Added

{agentbyte-0.40.0 → agentbyte-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.40.0
+Version: 0.42.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -77,7 +77,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.40.0**
+Current release: **0.42.0**
 
 ## Building an Agent
 

{agentbyte-0.40.0 → agentbyte-0.42.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.40.0**
+Current release: **0.42.0**
 
 ## Building an Agent
 

{agentbyte-0.40.0 → agentbyte-0.42.0}/pyproject.toml

@@ -98,6 +98,7 @@ test = [
 dev = [
     "fastexcel>=0.19.0",
     "ipykernel>=7.1.0",
+    "marimo>=0.25.1",
     "nbclient>=0.10.4",
     "nbformat>=5.10.4",
     "polars>=1.40.0",

agentbyte-0.42.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.42.0"
+VERSION = __version__

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/agents/types.py

@@ -9,7 +9,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from agentbyte.context import AgentContext, ToolApprovalRequest
 from agentbyte.messages import AssistantMessage, Message, Usage
-from agentbyte.types import ToolResult
+from agentbyte.types import OrchestrationDetail, ToolResult
 
 
 class BaseEvent(BaseModel):
@@ -193,12 +193,17 @@ class AgentErrorDetail(BaseModel):
 
 
 class AgentResponse(BaseModel):
-    """Final response payload for a completed agent run."""
+    """Final response payload for a completed agent or orchestrator (team) run.
+
+    Agents and orchestrators return this same type, so a consumer handles both
+    with one code path. ``orchestration`` carries team-only detail and is
+    ``None`` for a single agent.
+    """
 
     model_config = ConfigDict(frozen=False)
 
     context: AgentContext = Field(..., description="Final execution context")
-    source: str = Field(..., description="Agent name")
+    source: str = Field(..., description="Agent or orchestrator name")
     finish_reason: str = Field(
         ...,
         description="Why the agent stopped: stop, approval_needed, max_iterations, max_iterations_finalized, tool_executed, error, cancelled",
@@ -212,6 +217,10 @@ class AgentResponse(BaseModel):
         default_factory=datetime.now,
         description="When the response was created",
     )
+    orchestration: Optional[OrchestrationDetail] = Field(
+        default=None,
+        description="Team-only detail; set when an orchestrator produced this response",
+    )
 
     @property
     def messages(self) -> List[Message]:
@@ -220,8 +229,13 @@ class AgentResponse(BaseModel):
 
     @property
     def needs_approval(self) -> bool:
-        """Check if response is waiting for approvals."""
-        return self.context.waiting_for_approval
+        """Check if response is waiting for approvals.
+
+        A team stops with ``finish_reason="approval_needed"`` when a member waits on
+        tool approval; the member's pending tools are in
+        ``orchestration.stop_message.metadata``.
+        """
+        return self.context.waiting_for_approval or self.finish_reason == "approval_needed"
 
     @property
     def approval_requests(self) -> List[ToolApprovalRequest]:
@@ -234,20 +248,34 @@ class AgentResponse(BaseModel):
 
         When the run failed, the error text is not in ``context.messages`` (it is
         deliberately kept out of the replayed history), so it is surfaced from
-        ``error`` here for display and logging.
+        ``error`` here for display and logging. For a team it is the answer chosen
+        by the orchestrator (``orchestration.final_result``).
         """
         if self.error is not None:
             return f"Error: {self.error.message}"
+        if self.orchestration is not None:
+            return self.orchestration.final_result
         if not self.context.messages:
             return ""
         return self.context.messages[-1].content
 
     @property
     def final_message(self) -> AssistantMessage | None:
-        """Final assistant message if the run ended with one."""
-        if not self.context.messages:
+        """Final assistant message if the run ended with one.
+
+        For a team this is the message the orchestrator selected as the answer
+        (e.g. the synthesizer's), which is not necessarily the last message.
+        """
+        messages = self.context.messages
+        if self.orchestration is not None:
+            index = self.orchestration.final_message_index
+            if index is None or not 0 <= index < len(messages):
+                return None
+            message = messages[index]
+        elif not messages:
             return None
-        message = self.context.messages[-1]
+        else:
+            message = messages[-1]
         if isinstance(message, AssistantMessage):
             return message
         return None

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/eval/targets/orchestrator.py

@@ -47,19 +47,25 @@ class OrchestratorEvalTarget(BaseEvalTarget):
                             task.input, cancellation_token=cancellation_token
                         )
                         messages, usage = list(response.messages), response.usage
-                        status = normalize_status(response.stop_message.source)
+                        status = normalize_status(response.finish_reason)
+                        detail = response.orchestration
                         if status == "failed":
-                            error = response.stop_message.content
-                        metadata.update(
-                            pattern=response.pattern_metadata.get(
-                                "pattern", type(orchestrator).__name__
-                            ),
-                            iterations=response.pattern_metadata.get(
-                                "iterations_completed", 0
-                            ),
-                            stop_reason=response.stop_message.content,
-                            stop_source=response.stop_message.source,
-                        )
+                            error = (
+                                detail.stop_message.content
+                                if detail is not None
+                                else response.final_content
+                            )
+                        if detail is not None:
+                            metadata.update(
+                                pattern=detail.pattern_metadata.get(
+                                    "pattern", detail.pattern
+                                ),
+                                iterations=detail.pattern_metadata.get(
+                                    "iterations_completed", 0
+                                ),
+                                stop_reason=detail.stop_message.content,
+                                stop_source=detail.stop_message.source,
+                            )
                         if not collector.trace.spans:
                             collector.incomplete(
                                 "Custom orchestrator exposes response evidence only"

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/execution_trace/collector.py

@@ -41,6 +41,8 @@ def normalize_status(reason: str) -> ExecutionStatus:
         "MaxIterations": "incomplete",
         "Error": "failed",
         "Exception": "failed",
+        "SynthesisFailed": "failed",
+        "ApprovalRequired": "suspended",
     }
     return statuses.get(reason, "completed")
 
@@ -105,16 +107,12 @@ class TraceCollector:
             if span.kind == "agent":
                 span.usage = span.usage + self.trace.aggregate_usage(span.id)
             span.error = item.error.message if item.error is not None else None
+            orchestration = getattr(item, "orchestration", None)
+            if orchestration is not None:
+                span.metadata["stop_reason"] = snapshot(orchestration.stop_message)
             if self.capture_payloads:
                 span.output = item.final_content
             return
-        if hasattr(item, "stop_message"):
-            span.status = normalize_status(item.stop_message.source)
-            span.metadata["stop_reason"] = snapshot(item.stop_message)
-            span.usage = item.usage
-            if self.capture_payloads:
-                span.output = item.final_result
-            return
         if hasattr(item, "event_type") or isinstance(item, OrchestrationEvent):
             if self.capture_payloads and span.kind != "workflow_agent":
                 self.trace.events.append(
@@ -243,6 +241,10 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
             if workflow is not None:
                 name = workflow.id
             span = collector.start(kind, name)
+            turn_kind = bound.arguments.get("turn_kind")
+            if turn_kind:
+                # Orchestration turn role, e.g. "worker" or "synthesis" (spec 0065)
+                span.metadata["turn_kind"] = turn_kind
             started = time.perf_counter()
             if collector.capture_payloads:
                 span.input = snapshot(
@@ -261,7 +263,13 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                     pt = _parent.set(span.id)
                     try:
                         item = await anext(stream)
-                        collector.observe(span, item)
+                        is_forwarded_member_event = (
+                            kind == "orchestrator"
+                            and hasattr(item, "event_type")
+                            and getattr(item, "source", "orchestrator") != "orchestrator"
+                        )
+                        if not is_forwarded_member_event:
+                            collector.observe(span, item)
                         if kind == "invocation" and hasattr(item, "finish_reason"):
                             if any(
                                 s.parent_id == span.id for s in collector.trace.spans
@@ -349,12 +357,25 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
 
 @trace_stream("invocation")
 async def capture_agent_stream(
-    agent: Any, task: Any, *, cancellation_token=None, verbose: bool = False
+    agent: Any,
+    task: Any,
+    *,
+    cancellation_token=None,
+    verbose: bool = False,
+    turn_kind: str | None = None,
+    stream_tokens: bool = False,
 ) -> AsyncIterator[Any]:
-    """Capture custom and native agents uniformly inside orchestration streams."""
-    stream = agent.run_stream(
-        task, cancellation_token=cancellation_token, verbose=verbose
-    )
+    """Capture custom and native agents uniformly inside orchestration streams.
+
+    ``turn_kind`` is recorded on the span only; it is not passed to the agent.
+    """
+    stream_kwargs: dict[str, Any] = {
+        "cancellation_token": cancellation_token,
+        "verbose": verbose,
+    }
+    if stream_tokens:
+        stream_kwargs["stream_tokens"] = True
+    stream = agent.run_stream(task, **stream_kwargs)
     try:
         async for item in stream:
             yield item

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/optim/__init__.py

@@ -27,6 +27,7 @@ from .reflective import EditOut, ReflectionOut, ReflectiveOptimizer
 from .spec import (
     CatalogEntry,
     Component,
+    DescriptionTunable,
     Edit,
     InstructionTunable,
     MemberOptimizationSpec,
@@ -59,6 +60,7 @@ __all__ = [
     "Edit",
     "Tunable",
     "InstructionTunable",
+    "DescriptionTunable",
     "SkillTunable",
     "SkillDescriptionTunable",
     "SkillTriggersTunable",

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/optim/spec.py

@@ -114,6 +114,36 @@ class InstructionTunable(Tunable):
         return config.model_copy(update={"instructions": rewrites[-1].value})
 
 
+class DescriptionTunable(Tunable):
+    """Rewrite the agent's description. Free-form, single component.
+
+    Plan-based and AI-driven orchestrators route on member descriptions, not
+    instructions, so this is the component a routing judge can observe. Opt-in:
+    not part of the default ``OptimizationSpec`` tunables.
+    """
+
+    kind = "description"
+    ops = frozenset({Operation.REWRITE})
+    mode = ProposalMode.GENERATIVE
+
+    def read(self, config: AgentConfig) -> list[Component]:
+        return [
+            Component(
+                name="description",
+                kind=self.kind,
+                value=config.description,
+                ops=self.ops,
+                mode=self.mode,
+            )
+        ]
+
+    def apply(self, config: AgentConfig, edits: list[Edit]) -> AgentConfig:
+        rewrites = [e for e in edits if e.op is Operation.REWRITE and e.value]
+        if not rewrites:
+            return config
+        return config.model_copy(update={"description": rewrites[-1].value})
+
+
 class SkillTunable(Tunable):
     """Add / rewrite / remove named skills. Free-form (generative).
 
@@ -379,6 +409,7 @@ __all__ = [
     "Edit",
     "Tunable",
     "InstructionTunable",
+    "DescriptionTunable",
     "SkillTunable",
     "SkillDescriptionTunable",
     "SkillTriggersTunable",

{agentbyte-0.40.0 → agentbyte-0.42.0}/src/agentbyte/orchestration/ai.py

@@ -120,9 +120,9 @@ class AIOrchestrator(BaseOrchestrator):
             return self._last_selection_reason
         return super()._get_selection_reason(selected_agent)
 
-    def _get_additional_usage_stats(self) -> list[Usage]:
+    def _get_orchestrator_usage_stats(self) -> list[tuple[str, Usage]]:
         """Include selector LLM calls in orchestration usage aggregation."""
-        return list(self._selector_usage_stats)
+        return [("selector", usage) for usage in self._selector_usage_stats]
 
     def _reset_for_run(self) -> None:
         """Reset AI-driven runtime state for new run."""
@@ -151,7 +151,7 @@ class AIOrchestrator(BaseOrchestrator):
 
     def _build_selection_prompt(self) -> str:
         """Build LLM prompt for choosing the next best agent."""
-        agent_names = ", ".join(agent.name for agent in self.agents)
+        agent_names = ", ".join(agent.name for agent in self._worker_agents)
         capabilities = self.get_agent_capabilities_summary()
         conversation_context = self._format_conversation_for_selection()
 
@@ -228,13 +228,14 @@ class AIOrchestrator(BaseOrchestrator):
         return json.dumps(payload, indent=2)
 
     def _find_agent_by_name(self, agent_name: str) -> Optional[BaseAgent]:
-        """Resolve agent by exact name first, then case-insensitive match."""
-        for agent in self.agents:
+        """Resolve a worker agent by exact name first, then case-insensitive match."""
+        workers = self._worker_agents
+        for agent in workers:
             if agent.name == agent_name:
                 return agent
 
         target = agent_name.casefold()
-        for agent in self.agents:
+        for agent in workers:
             if agent.name.casefold() == target:
                 return agent
 
@@ -242,8 +243,9 @@ class AIOrchestrator(BaseOrchestrator):
 
     def _select_next_by_fallback(self, reason: str) -> BaseAgent:
         """Round-robin fallback selection used when AI selection fails."""
-        agent = self.agents[self._fallback_agent_index]
-        self._fallback_agent_index = (self._fallback_agent_index + 1) % len(self.agents)
+        workers = self._worker_agents
+        agent = workers[self._fallback_agent_index]
+        self._fallback_agent_index = (self._fallback_agent_index + 1) % len(workers)
         self._last_selection_reason = (
             f"{reason}. Fallback round-robin selected '{agent.name}'"
         )