agentbyte 0.26.4__tar.gz → 0.27.0__tar.gz

{agentbyte-0.26.4 → agentbyte-0.27.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.27.0] - 2026-09-12
+
+### Added
+
+- Agents now support `finalize_on_exhaustion` (default `True`): when the iteration budget is about to be exhausted, the last iteration is reserved for a tool-free finalization turn so the agent always returns a complete, well-formed answer instead of nothing. This turn disables tools and injects a finalization instruction; the run reports `finish_reason="max_iterations_finalized"`. Set `finalize_on_exhaustion=False` to keep the previous behavior of stopping with `finish_reason="max_iterations"`.
+- New `DuplicateToolResultMiddleware` (exported from `agentbyte.middleware`) collapses byte-identical large tool results in the model-call payload: it keeps the most recent full copy and replaces earlier duplicates in place with a short placeholder, preserving `tool_call_id` pairing. Duplicates are matched on a full-content hash, and only the outgoing payload is modified — persisted session history keeps every full copy. This caps the token cost of a skill or resource that is loaded on several turns; place it before `ContextCompactionMiddleware`. Configurable via `min_dedupe_chars` (default `2000`).
+- `RetryPolicy` gained `retryable_error_substrings` (default empty): an otherwise-terminal error (for example Azure's non-deterministic `invalid_prompt` 400) is retried with the standard back-off when `str(error)` contains a configured marker (case-insensitive). The field is plain JSON data, so it round-trips through component serialization. Streaming keeps its no-retry-after-first-chunk guard, and `AuthenticationError` remains terminal regardless of markers.
+
+### Changed
+
+- The default skills advertisement template now instructs the model to reuse skill content already present earlier in the conversation instead of calling `load_skill` again, reducing avoidable reloads in multi-turn sessions. Callers passing a custom `instruction_template` are unaffected.
+
 ## [0.26.4] - 2026-09-10
 
 ### Fixed

{agentbyte-0.26.4 → agentbyte-0.27.0}/PKG-INFO

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

{agentbyte-0.26.4 → agentbyte-0.27.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.26.4**
+Current release: **0.27.0**
 
 ## Building an Agent
 

agentbyte-0.27.0/src/agentbyte/__about__.py

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

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/agents/agent.py

@@ -16,6 +16,7 @@ from agentbyte.llm.types import ChatCompletionChunk
 from agentbyte.messages import (
     AssistantMessage,
     Message,
+    SystemMessage,
     ToolCallRequest,
     ToolMessage,
     Usage,
@@ -42,6 +43,14 @@ from .types import (
 )
 
 
+_FINALIZE_INSTRUCTION = (
+    "You have reached the maximum number of tool-using iterations. No further "
+    "tool calls are available. Produce your final answer now using only the "
+    "information already gathered. If the analysis is incomplete, state clearly "
+    "what is missing, but still return a complete, well-formed response."
+)
+
+
 class Agent(BaseAgent):
     """Standard single-agent execution loop with tools and cancellation."""
 
@@ -462,6 +471,20 @@ class Agent(BaseAgent):
                     memory_operations += 1
                 tools = self._get_tools_for_llm(extra_tools=provider_tools) if (self.tools or provider_tools) else None
 
+                # Reserve the final iteration for a tool-free answer so an exhausted
+                # budget yields a complete response instead of nothing.
+                is_final_iteration = (
+                    self.finalize_on_exhaustion
+                    and self.max_iterations > 1
+                    and iteration == self.max_iterations - 1
+                    and bool(tools)
+                )
+                if is_final_iteration:
+                    tools = None
+                    llm_messages.append(
+                        SystemMessage(content=_FINALIZE_INSTRUCTION, source=self.name)
+                    )
+
                 if verbose:
                     yield ModelCallEvent(
                         source=self.name,
@@ -518,7 +541,7 @@ class Agent(BaseAgent):
 
                     working_context.add_message(assistant_message)
                     yield assistant_message
-                    finish_reason = "stop"
+                    finish_reason = "max_iterations_finalized" if is_final_iteration else "stop"
                     break
 
                 async def _execute_model_call(payload: dict[str, object]):
@@ -621,6 +644,8 @@ class Agent(BaseAgent):
 
                 if not assistant_message.tool_calls:
                     finish_reason = completion_result.finish_reason or "stop"
+                    if is_final_iteration:
+                        finish_reason = "max_iterations_finalized"
                     break
 
                 approval_pause = False

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/agents/base.py

@@ -53,6 +53,7 @@ class BaseAgent(ABC):
         memory: Optional[BaseMemory] = None,
         middlewares: Optional[List[BaseMiddleware]] = None,
         max_iterations: int = 10,
+        finalize_on_exhaustion: bool = True,
         output_format: Optional[Type[BaseModel]] = None,
         summarize_tool_result: bool = True,
         required_tools: Optional[List[str]] = None,
@@ -68,6 +69,7 @@ class BaseAgent(ABC):
         self.memory = memory
         self.middleware_chain = MiddlewareChain(middlewares)
         self.max_iterations = max_iterations
+        self.finalize_on_exhaustion = finalize_on_exhaustion
         self.output_format = output_format
         self.summarize_tool_result = summarize_tool_result
         self.required_tools = required_tools or []
@@ -217,6 +219,7 @@ class BaseAgent(ABC):
             "tools_count": len(self.tools),
             "middlewares_count": len(self.middleware_chain.middlewares),
             "max_iterations": self.max_iterations,
+            "finalize_on_exhaustion": self.finalize_on_exhaustion,
         }
 
     def as_tool(

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/agents/types.py

@@ -183,7 +183,7 @@ class AgentResponse(BaseModel):
     source: str = Field(..., description="Agent name")
     finish_reason: str = Field(
         ...,
-        description="Why the agent stopped: stop, approval_needed, max_iterations, error, cancelled",
+        description="Why the agent stopped: stop, approval_needed, max_iterations, max_iterations_finalized, tool_executed, error, cancelled",
     )
     usage: Usage = Field(default_factory=Usage, description="Aggregated usage")
     timestamp: datetime = Field(

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/context_providers/skills.py

@@ -29,9 +29,10 @@ Each skill provides specialized instructions, reference documents, and assets fo
 </available_skills>
 
 When a task aligns with a skill's domain, follow these steps in exact order:
-- Use `load_skill` to retrieve the skill's instructions.
+- If the skill's content is already present earlier in this conversation, reuse it and do NOT call `load_skill` again for it.
+- Otherwise, use `load_skill` to retrieve the skill's instructions.
 - Follow the provided guidance.
-{resource_instructions}{runner_instructions}Only load what is needed, when it is needed."""
+{resource_instructions}{runner_instructions}Only load what is needed, when it is needed, and do not reload content already shown above."""
 
 _RESOURCE_INSTRUCTIONS = (
     "- Use `read_skill_resource` to read any referenced resources, "

agentbyte-0.27.0/src/agentbyte/llm/retry_policy.py

@@ -0,0 +1,200 @@
+"""Shared retry policy and mixin for LLM clients."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any, Callable, List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+
+class RetryPolicy(BaseModel):
+    """Retry configuration for LLM clients."""
+
+    max_retries: int = 3
+    initial_retry_delay: float = 1.0
+    max_retry_delay: float = 60.0
+    retryable_error_substrings: List[str] = Field(default_factory=list)
+    """Opt otherwise-terminal errors into the retry path by marker.
+
+    An error that would normally be non-transient (for example a provider's
+    ``BadRequestError`` mapped to :class:`InvalidRequestError`) is retried with
+    the standard back-off when ``str(error)`` contains any of these substrings
+    (case-insensitive). Empty by default, so existing behaviour is unchanged.
+    Use a specific marker such as an error code (``"invalid_prompt"``), not a
+    generic word, or unrelated failures will only be slowed before they surface.
+    """
+
+    @field_validator("max_retries")
+    @classmethod
+    def _non_negative_retries(cls, v: int) -> int:
+        if v < 0:
+            raise ValueError("max_retries must be >= 0")
+        return v
+
+    @field_validator("initial_retry_delay", "max_retry_delay")
+    @classmethod
+    def _no_negative_delays(cls, v: float) -> float:
+        if v < 0:
+            raise ValueError("delay must be non-negative")
+        return v
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.max_retry_delay < self.initial_retry_delay:
+            raise ValueError(
+                "max_retry_delay must be >= initial_retry_delay"
+            )
+
+
+class RetryMixin:
+    """Mixin providing unified retry logic for all LLM clients.
+
+    Clients must set ``self.retry_policy`` (a :class:`RetryPolicy` instance)
+    before calling these methods.
+    """
+
+    retry_policy: RetryPolicy
+
+    def _error_opted_into_retry(self, error: Exception) -> bool:
+        """Return True if the caller marked this error's text as retryable.
+
+        Matches ``str(error)`` case-insensitively against
+        ``retry_policy.retryable_error_substrings``. This only ever widens what is
+        retried; it never suppresses an error.
+        """
+        markers = getattr(self.retry_policy, "retryable_error_substrings", None) or []
+        if not markers:
+            return False
+        text = str(error).lower()
+        return any(marker.lower() in text for marker in markers)
+
+    async def _retry_with_backoff(
+        self,
+        func: Callable[..., Any],
+        *args: Any,
+        _retry_history: Optional[List] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute *func* with exponential back-off on transient errors."""
+        from .base import AuthenticationError, InvalidRequestError, RateLimitError
+        from .types import ModelClientError
+        from ._retry_observability import build_retry_record
+
+        last_exception: Optional[Exception] = None
+        current_delay = self.retry_policy.initial_retry_delay
+
+        for attempt in range(self.retry_policy.max_retries + 1):
+            try:
+                return await func(*args, **kwargs)
+            except AuthenticationError as e:
+                # Authentication never becomes valid on retry; opt-in cannot
+                # widen this.
+                logger.error(f"Non-transient error in {func.__name__}: {e}")
+                raise
+            except InvalidRequestError as e:
+                # Terminal by classification. Retry only when the caller opted
+                # this error's text into the retry path.
+                last_exception = e
+                if not self._error_opted_into_retry(e):
+                    logger.error(f"Non-transient error in {func.__name__}: {e}")
+                    raise
+            except (RateLimitError, ModelClientError) as e:
+                last_exception = e
+            except Exception as e:
+                # Raw provider errors reach the retry loop before adapter
+                # conversion. Terminal unless the caller opted the text in.
+                last_exception = e
+                if not self._error_opted_into_retry(e):
+                    logger.error(f"Unexpected error in {func.__name__}: {e}")
+                    raise
+
+            # Reached only for a retryable error.
+            if attempt >= self.retry_policy.max_retries:
+                logger.warning(
+                    f"Max retries ({self.retry_policy.max_retries}) reached for {func.__name__}"
+                )
+                raise last_exception
+            if _retry_history is not None:
+                _retry_history.append(
+                    build_retry_record(
+                        attempt + 1, current_delay, type(last_exception), "retrying"
+                    )
+                )
+            logger.debug(
+                f"Transient error in {func.__name__} "
+                f"(attempt {attempt + 1}/{self.retry_policy.max_retries + 1}): "
+                f"{last_exception}. Retrying in {current_delay:.1f}s"
+            )
+            await asyncio.sleep(current_delay)
+            current_delay = min(current_delay * 2, self.retry_policy.max_retry_delay)
+
+        raise last_exception if last_exception is not None else ModelClientError("Retry logic error")
+
+    async def _retry_stream_with_backoff(
+        self,
+        func: Callable[..., AsyncGenerator[Any, None]],
+        *args: Any,
+        **kwargs: Any,
+    ) -> AsyncGenerator[Any, None]:
+        """Execute a streaming *func* with exponential back-off on transient errors."""
+        from .base import AuthenticationError, InvalidRequestError, RateLimitError
+        from .types import ModelClientError
+
+        current_delay = self.retry_policy.initial_retry_delay
+
+        for attempt in range(self.retry_policy.max_retries + 1):
+            saw_chunk = False
+            try:
+                async for chunk in func(*args, **kwargs):
+                    saw_chunk = True
+                    yield chunk
+                return
+            except AuthenticationError:
+                raise
+            except InvalidRequestError as e:
+                # Terminal unless opted in, and never retried once a chunk has
+                # already reached the caller (the response is half-said).
+                if (
+                    saw_chunk
+                    or attempt >= self.retry_policy.max_retries
+                    or not self._error_opted_into_retry(e)
+                ):
+                    raise
+                logger.debug(
+                    f"Retryable stream error in {func.__name__} "
+                    f"(attempt {attempt + 1}/{self.retry_policy.max_retries + 1}): {e}. "
+                    f"Retrying in {current_delay:.1f}s"
+                )
+                await asyncio.sleep(current_delay)
+                current_delay = min(current_delay * 2, self.retry_policy.max_retry_delay)
+            except (RateLimitError, ModelClientError) as e:
+                if saw_chunk or attempt >= self.retry_policy.max_retries:
+                    raise
+                logger.debug(
+                    f"Transient stream error in {func.__name__} "
+                    f"(attempt {attempt + 1}/{self.retry_policy.max_retries + 1}): {e}. "
+                    f"Retrying in {current_delay:.1f}s"
+                )
+                await asyncio.sleep(current_delay)
+                current_delay = min(current_delay * 2, self.retry_policy.max_retry_delay)
+            except Exception as e:
+                if (
+                    saw_chunk
+                    or attempt >= self.retry_policy.max_retries
+                    or not self._error_opted_into_retry(e)
+                ):
+                    raise
+                logger.debug(
+                    f"Retryable stream error in {func.__name__} "
+                    f"(attempt {attempt + 1}/{self.retry_policy.max_retries + 1}): {e}. "
+                    f"Retrying in {current_delay:.1f}s"
+                )
+                await asyncio.sleep(current_delay)
+                current_delay = min(current_delay * 2, self.retry_policy.max_retry_delay)
+
+
+__all__ = ["RetryPolicy", "RetryMixin"]

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/middleware/__init__.py

@@ -6,6 +6,7 @@ from .base import (
     ApprovalMiddleware,
     BaseMiddleware,
     ContextCompactionMiddleware,
+    DuplicateToolResultMiddleware,
     GuardrailMiddleware,
     LoggingMiddleware,
     MetricsMiddleware,
@@ -40,6 +41,7 @@ __all__ = [
     "MiddlewareChain",
     "ApprovalMiddleware",
     "ContextCompactionMiddleware",
+    "DuplicateToolResultMiddleware",
     "LoggingMiddleware",
     "PIIRedactionMiddleware",
     "GuardrailMiddleware",

{agentbyte-0.26.4 → agentbyte-0.27.0}/src/agentbyte/middleware/base.py

@@ -1,12 +1,14 @@
 """Middleware infrastructure for cross-cutting agent concerns."""
 
 import asyncio
+import copy
 import inspect
 import json
 import logging
 import re
 import time
 from abc import ABC, abstractmethod
+from hashlib import sha256
 from collections import deque
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from enum import Enum
@@ -1052,6 +1054,113 @@ class ContextCompactionMiddleware(BaseMiddleware):
         return None
 
 
+class DuplicateToolResultMiddleware(BaseMiddleware):
+    """Collapse repeated identical tool results in the model-call payload.
+
+    A tool result stays in the conversation for the life of a session and is
+    re-transmitted on every later model call. When the same large document is
+    returned by a tool more than once (for example a skill or resource loaded on
+    several turns), the payload carries multiple byte-identical copies, each
+    billed and sent again.
+
+    This middleware keeps exactly one full copy of each duplicated large tool
+    result -- the most recent -- and replaces the earlier copies in place with a
+    short placeholder. Keeping the last occurrence leaves the surviving full copy
+    in the recency tail that ``ContextCompactionMiddleware`` preserves, so
+    collapsing never leaves a reference to content that later compaction removes.
+
+    Only the outgoing payload (``context.data["messages"]``) is modified; the
+    persisted ``AgentContext.messages`` are untouched, so session history keeps
+    every full copy. Recommended placement: before ``ContextCompactionMiddleware``
+    so compaction operates on the already-deduplicated list.
+    """
+
+    _PLACEHOLDER = (
+        "[Duplicate tool result omitted - identical content appears later in "
+        "this conversation and is still valid. Reuse it; do not request it again.]"
+    )
+
+    def __init__(self, min_dedupe_chars: int = 2000):
+        if min_dedupe_chars <= 0:
+            raise ValueError("min_dedupe_chars must be greater than zero")
+        self.min_dedupe_chars = min_dedupe_chars
+
+    def _is_dedupe_candidate(self, message: Any) -> bool:
+        """A successful tool result whose body is large enough to be worth it."""
+        if getattr(message, "role", None) != "tool":
+            return False
+        if getattr(message, "success", None) is not True:
+            return False
+        content = getattr(message, "content", None)
+        return isinstance(content, str) and len(content) >= self.min_dedupe_chars
+
+    def _collapse(self, message: Any) -> Any:
+        """Return a copy of *message* with its body replaced by the placeholder.
+
+        Never mutates *message* in place: the same object is referenced by the
+        persisted context, and the placeholder must only affect the outgoing
+        payload.
+        """
+        model_copy = getattr(message, "model_copy", None)
+        if callable(model_copy):
+            return model_copy(update={"content": self._PLACEHOLDER})
+        clone = copy.copy(message)
+        clone.content = self._PLACEHOLDER
+        return clone
+
+    async def process_request(self, context: MiddlewareContext) -> MiddlewareContext:
+        if context.operation != OperationType.MODEL_CALL:
+            return context
+
+        payload = context.data
+        if not isinstance(payload, dict):
+            return context
+
+        messages = payload.get("messages", [])
+        if not isinstance(messages, list) or len(messages) <= 1:
+            return context
+
+        # Group candidate indices by an exact hash of the full body. A prefix or
+        # fingerprint is never used, so two different bodies cannot collide.
+        groups: Dict[str, List[int]] = {}
+        for idx, message in enumerate(messages):
+            if not self._is_dedupe_candidate(message):
+                continue
+            key = sha256(message.content.encode("utf-8")).hexdigest()
+            groups.setdefault(key, []).append(idx)
+
+        # Keep the last occurrence in each duplicate group; collapse the rest.
+        collapse: set[int] = set()
+        duplicate_groups = 0
+        for indices in groups.values():
+            if len(indices) > 1:
+                duplicate_groups += 1
+                collapse.update(indices[:-1])
+
+        if not collapse:
+            return context
+
+        new_messages = [
+            self._collapse(message) if idx in collapse else message
+            for idx, message in enumerate(messages)
+        ]
+        context.data = {**payload, "messages": new_messages}
+        context.metadata["duplicate_tool_results_pruned"] = True
+        context.metadata["duplicate_groups"] = duplicate_groups
+        context.metadata["messages_collapsed"] = len(collapse)
+        return context
+
+    async def process_response(self, context: MiddlewareContext, result: Any) -> Any:
+        return result
+
+    async def process_error(
+        self,
+        context: MiddlewareContext,
+        error: Exception,
+    ) -> Optional[Any]:
+        return None
+
+
 class ApprovalMiddleware(BaseMiddleware):
     """Middleware that emits approval events for configured tool names."""
 

{agentbyte-0.26.4 → agentbyte-0.27.0}/tests/agents/test_agent_basic.py

@@ -36,6 +36,7 @@ class FakeModelClient(BaseChatCompletionClient):
         output_format: Optional[type] = None,
         **kwargs: Any,
     ) -> ChatCompletionResult:
+        self.last_tools = tools
         response = self._responses[self._index]
         self._index += 1
         return response
@@ -361,3 +362,71 @@ async def test_agent_run_with_streaming_tool_path() -> None:
     tool_messages = [message for message in response.messages if message.role == "tool"]
     assert len(tool_messages) == 1
     assert tool_messages[0].content == "5"
+
+
+def _tool_call_result(call_id: str) -> ChatCompletionResult:
+    return ChatCompletionResult(
+        message=AssistantMessage(
+            content="calling tool",
+            source="fake",
+            tool_calls=[
+                {
+                    "tool_name": "add",
+                    "parameters": {"a": 1, "b": 2},
+                    "call_id": call_id,
+                }
+            ],
+        ),
+        usage=Usage(tokens_input=5, tokens_output=2),
+        model="fake",
+    )
+
+
+@pytest.mark.asyncio
+async def test_agent_finalizes_on_exhaustion() -> None:
+    responses = [
+        _tool_call_result("call-1"),
+        _tool_call_result("call-2"),
+        ChatCompletionResult(
+            message=AssistantMessage(content="final answer", source="fake"),
+            usage=Usage(tokens_input=4, tokens_output=2),
+            model="fake",
+        ),
+    ]
+    client = FakeModelClient(responses)
+    agent = Agent(
+        name="assistant",
+        description="desc",
+        instructions="help",
+        model_client=client,
+        tools=[add],
+        max_iterations=3,
+        finalize_on_exhaustion=True,
+    )
+
+    response = await agent.run(UserMessage(content="calculate", source="user"))
+
+    assert response.finish_reason == "max_iterations_finalized"
+    assert response.messages[-1].content == "final answer"
+    # Last model call must have been made with tools disabled.
+    assert client.last_tools is None
+
+
+@pytest.mark.asyncio
+async def test_agent_max_iterations_without_finalize() -> None:
+    responses = [_tool_call_result("call-1"), _tool_call_result("call-2")]
+    client = FakeModelClient(responses)
+    agent = Agent(
+        name="assistant",
+        description="desc",
+        instructions="help",
+        model_client=client,
+        tools=[add],
+        max_iterations=2,
+        finalize_on_exhaustion=False,
+    )
+
+    response = await agent.run(UserMessage(content="calculate", source="user"))
+
+    assert response.finish_reason == "max_iterations"
+

{agentbyte-0.26.4 → agentbyte-0.27.0}/tests/llm/test_retry_policy_api.py

@@ -88,6 +88,7 @@ def test_component_dump_includes_nested_retry_policy(client_cls, model) -> None:
         "max_retries": 4,
         "initial_retry_delay": 0.5,
         "max_retry_delay": 8.0,
+        "retryable_error_substrings": [],
     }
     assert "max_retries" not in dumped.config
     assert "initial_retry_delay" not in dumped.config