agentbyte 0.42.4__tar.gz → 0.43.0__tar.gz

{agentbyte-0.42.4 → agentbyte-0.43.0}/CHANGELOG.md

@@ -6,6 +6,27 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [0.43.0] - 2026-10-05
+
+### Added
+
+- Agents: `stop_at_tools=[...]` ends the run with `finish_reason="tool_executed"`, without a
+  final model call, once a call to a named tool succeeds. Multi-step tool discovery and retries
+  after a failed call still run; a failed stop tool does not stop the run; the budget-exhaustion
+  finalization still applies. Names are validated against the agent's tools at construction.
+  Meant for team specialists whose raw tool results a synthesizer turns into the answer.
+- Orchestration: `AgentHistoryPolicy(window="run")` sends this run's messages in full and
+  condenses earlier session turns to each user message plus the answer that closed it (no prior
+  tool calls, tool results, or worker notes). Use it as `FinalResultPolicy.synthesis_history` so a
+  synthesizer's input stays bounded across follow-up turns without losing their context.
+- Orchestration: workers that end with `max_iterations` / `max_iterations_finalized` are reported to
+  the synthesizer as a separate completion fact (partial findings), next to error turns.
+
+### Fixed
+
+- Design guide: `summarize_tool_result` was documented as a summarization knob; it actually ends
+  the run after the first tool batch. The agent topic now describes it and `stop_at_tools`.
+
 ## [0.42.4] - 2026-10-05
 
 ### Fixed

{agentbyte-0.42.4 → agentbyte-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.42.4
+Version: 0.43.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.42.4**
+Current release: **0.43.0**
 
 ## Building an Agent
 

{agentbyte-0.42.4 → agentbyte-0.43.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.42.4**
+Current release: **0.43.0**
 
 ## Building an Agent
 

agentbyte-0.43.0/src/agentbyte/__about__.py

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

{agentbyte-0.42.4 → agentbyte-0.43.0}/src/agentbyte/agents/agent.py

@@ -372,6 +372,14 @@ class Agent(BaseAgent):
             and working_context.get_approval_response(tool_call.call_id) is None
         )
 
+    def _is_stop_tool_success(self, item: object) -> bool:
+        """Whether *item* is a successful result of a ``stop_at_tools`` tool."""
+        return (
+            isinstance(item, ToolMessage)
+            and item.success
+            and item.tool_name in self.stop_at_tools
+        )
+
     async def _resolve_tool_batch(
         self,
         working_context: AgentContext,
@@ -560,6 +568,7 @@ class Agent(BaseAgent):
                 # not-yet-run siblings, in order) before asking the model again.
                 if self._unresolved_tail_calls(working_context):
                     outcome: dict[str, int | bool] = {"executed": 0, "paused": False}
+                    stop_tool_succeeded = False
                     async for item in self._resolve_tool_batch(
                         working_context,
                         cancellation_token,
@@ -567,11 +576,15 @@ class Agent(BaseAgent):
                         provider_tools,
                         outcome,
                     ):
+                        stop_tool_succeeded |= self._is_stop_tool_success(item)
                         yield item
                     tool_calls += int(outcome["executed"])
                     if outcome["paused"]:
                         finish_reason = "approval_needed"
                         break
+                    if stop_tool_succeeded:
+                        finish_reason = "tool_executed"
+                        break
 
                 llm_messages = await self._prepare_llm_messages([], working_context, extra_instructions=extra_instructions)
                 if self.memory is not None:
@@ -773,6 +786,7 @@ class Agent(BaseAgent):
                     break
 
                 outcome = {"executed": 0, "paused": False}
+                stop_tool_succeeded = False
                 async for item in self._resolve_tool_batch(
                     working_context,
                     cancellation_token,
@@ -780,13 +794,14 @@ class Agent(BaseAgent):
                     provider_tools,
                     outcome,
                 ):
+                    stop_tool_succeeded |= self._is_stop_tool_success(item)
                     yield item
                 tool_calls += int(outcome["executed"])
                 if outcome["paused"]:
                     finish_reason = "approval_needed"
                     break
 
-                if not self.summarize_tool_result:
+                if stop_tool_succeeded or not self.summarize_tool_result:
                     finish_reason = "tool_executed"
                     break
 

{agentbyte-0.42.4 → agentbyte-0.43.0}/src/agentbyte/agents/base.py

@@ -59,6 +59,7 @@ class BaseAgent(ABC):
         required_tools: Optional[List[str]] = None,
         example_tasks: Optional[List[str]] = None,
         context_providers: Optional[List[ContextProvider]] = None,
+        stop_at_tools: Optional[List[str]] = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the agent.
@@ -69,6 +70,15 @@ class BaseAgent(ABC):
         ``max_iterations >= 2``: with ``max_iterations=1`` the only turn keeps
         its tools, so a run that calls a tool ends with
         ``finish_reason="max_iterations"`` and no final answer.
+
+        ``summarize_tool_result=False`` ends the run right after the first tool
+        batch executes, with no further model call
+        (``finish_reason="tool_executed"``). ``stop_at_tools`` is the selective
+        form: the agent keeps its tool loop (multi-step discovery, retries after a
+        failed call) and ends the same way once a call to one of the named tools
+        succeeds. The names must be the agent's own tools. Use either when another
+        component, such as an orchestrator's synthesizer, writes the answer from
+        the raw tool results.
         """
         self.name = name
         self.description = description
@@ -84,6 +94,7 @@ class BaseAgent(ABC):
         self.required_tools = required_tools or []
         self.example_tasks = example_tasks or []
         self.context_providers: List[ContextProvider] = list(context_providers) if context_providers else []
+        self.stop_at_tools: List[str] = list(stop_at_tools) if stop_at_tools else []
         self.extra_config = kwargs
 
         self._validate_configuration()
@@ -100,6 +111,13 @@ class BaseAgent(ABC):
             raise AgentConfigurationError("Model client is required")
         if self.max_iterations <= 0:
             raise AgentConfigurationError("max_iterations must be > 0")
+        tool_names = {tool.name for tool in self.tools}
+        unknown = [name for name in self.stop_at_tools if name not in tool_names]
+        if unknown:
+            raise AgentConfigurationError(
+                f"stop_at_tools names unknown tools {unknown}; "
+                f"available: {sorted(tool_names)}"
+            )
 
     def _process_tools(self, tools: List[Union[BaseTool, Callable]]) -> List[BaseTool]:
         """Normalize mixed tool list into BaseTool instances."""

{agentbyte-0.42.4 → agentbyte-0.43.0}/src/agentbyte/orchestration/base.py

@@ -51,6 +51,8 @@ _SYNTHESIS_INSTRUCTION = (
 )
 _SYNTHESIS_SELECTION_REASON = "Synthesis"
 _SYNTHESIS_FAILED_FINISH_REASONS = frozenset({"error", "approval_needed", "cancelled"})
+# A worker that hit its iteration budget returned at most a partial result.
+_EXHAUSTED_FINISH_REASONS = frozenset({"max_iterations", "max_iterations_finalized"})
 
 # Stop source -> agent finish_reason (spec 0066); every other source, termination
 # conditions included, maps to "stop".
@@ -128,6 +130,7 @@ class BaseOrchestrator(ABC):
 
         # Runtime state
         self.shared_messages: List[Message] = []
+        self._run_start_index = 0
         self.iteration_count = 0
         self.start_time: Optional[float] = None
         self._last_termination_check_count = 0
@@ -154,6 +157,7 @@ class BaseOrchestrator(ABC):
         self._turn_usage: list[tuple[str, Usage]] = []
         self._run_task_messages: list[Message] = []
         self._worker_error_agents: list[str] = []
+        self._worker_exhausted_agents: list[str] = []
         self._synthesis_usage: Usage | None = None
         self._synthesis_message: Message | None = None
         self._synthesis_meta: dict[str, Any] | None = None
@@ -307,6 +311,10 @@ class BaseOrchestrator(ABC):
         # Seed shared_messages from prior session history when context is provided
         if context is not None and context.messages:
             self.shared_messages.extend(list(context.messages))
+        # Where this run's messages begin; earlier ones are prior session turns.
+        self._run_start_index = len(self.shared_messages) - (
+            len(initial_messages) if task_in_context else 0
+        )
 
         # Initialize stop_message
         stop_message: Optional[StopMessage] = None
@@ -419,6 +427,8 @@ class BaseOrchestrator(ABC):
                 if self._synthesizer is not None:
                     if result.finish_reason == "error":
                         self._worker_error_agents.append(next_agent.name)
+                    elif result.finish_reason in _EXHAUSTED_FINISH_REASONS:
+                        self._worker_exhausted_agents.append(next_agent.name)
                     approval_stop = self._get_approval_stop_message(next_agent, result)
                     if approval_stop is not None:
                         # Synthesis cannot resolve a pending approval; stop here.
@@ -888,6 +898,12 @@ class BaseOrchestrator(ABC):
                 "- Worker turns that ended in an error: "
                 + ", ".join(dict.fromkeys(self._worker_error_agents))
             )
+        if self._worker_exhausted_agents:
+            facts.append(
+                "- Worker turns that ran out of iterations before completing (treat their "
+                "findings as partial): "
+                + ", ".join(dict.fromkeys(self._worker_exhausted_agents))
+            )
         facts.extend(f"- {fact}" for fact in self._get_synthesis_facts())
         return (
             f"Original request:\n{request}\n\n"
@@ -1057,7 +1073,9 @@ class BaseOrchestrator(ABC):
         self._last_context_was_text = False
         self._turn_usage = []
         self._run_task_messages = []
+        self._run_start_index = 0
         self._worker_error_agents = []
+        self._worker_exhausted_agents = []
         self._synthesis_usage = None
         self._synthesis_message = None
         self._synthesis_meta = None
@@ -1260,8 +1278,40 @@ class BaseOrchestrator(ABC):
         """Return the relevant shared-message slice for a history policy."""
         if policy.window == "recent" and policy.message_limit is not None:
             return self._select_recent_messages(policy.message_limit)
+        if policy.window == "run":
+            prior = self.shared_messages[: self._run_start_index]
+            return [
+                *self._condense_prior_turns(prior),
+                *self.shared_messages[self._run_start_index :],
+            ]
         return list(self.shared_messages)
 
+    @staticmethod
+    def _condense_prior_turns(messages: list[Message]) -> list[Message]:
+        """Each earlier turn as its user message(s) plus the answer that closed it.
+
+        The closing answer is the turn's last assistant message with content and
+        no tool calls (for a team with a synthesizer, the synthesized answer).
+        Tool calls, tool results, and intermediate replies are dropped.
+        """
+        condensed: list[Message] = []
+        answer: Message | None = None
+        for message in messages:
+            if isinstance(message, UserMessage):
+                if answer is not None:
+                    condensed.append(answer)
+                    answer = None
+                condensed.append(message)
+            elif (
+                isinstance(message, AssistantMessage)
+                and message.content
+                and not message.tool_calls
+            ):
+                answer = message
+        if answer is not None:
+            condensed.append(answer)
+        return condensed
+
     def _select_recent_messages(self, message_limit: int) -> list[Message]:
         """Last `message_limit` messages, never splitting a tool-call exchange.
 

{agentbyte-0.42.4 → agentbyte-0.43.0}/src/agentbyte/orchestration/policies.py

@@ -12,7 +12,11 @@ class AgentHistoryPolicy(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    window: Literal["full", "recent"]
+    window: Literal["full", "recent", "run"]
+    """``full``: the whole shared conversation. ``recent``: the last
+    ``message_limit`` messages. ``run``: this run's messages in full, with earlier
+    turns of the session condensed to each user message and the answer that
+    closed its turn (no tool calls, tool results, or intermediate replies)."""
     message_limit: int | None = None
     format: Literal["messages", "text", "markdown", "json"]
     include_turn_prompt: bool = True

{agentbyte-0.42.4 → agentbyte-0.43.0}/src/agentbyte/workflow/agent.py

@@ -79,6 +79,7 @@ class WorkflowAgent(BaseAgent):
         self.max_iterations = 1
         self.output_format = None
         self.summarize_tool_result = False
+        self.stop_at_tools = []
         self.required_tools = []
         self.example_tasks = list(workflow.config.metadata.get("example_tasks", []))
         self.extra_config = {}

agentbyte-0.43.0/tests/agents/test_agent_stop_at_tools.py

@@ -0,0 +1,170 @@
+"""``stop_at_tools``: end the run, without a final model call, once a named tool succeeds."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import pytest
+
+from agentbyte.agents import Agent
+from agentbyte.agents.base import AgentConfigurationError
+from agentbyte.llm.base import BaseChatCompletionClient, BaseChatCompletionClientConfig
+from agentbyte.llm.types import ChatCompletionChunk, ChatCompletionResult
+from agentbyte.messages import AssistantMessage, ToolMessage, Usage, UserMessage
+
+
+class _Config(BaseChatCompletionClientConfig):
+    pass
+
+
+class FakeModelClient(BaseChatCompletionClient):
+    """Returns scripted completions in order."""
+
+    def __init__(self, responses: list[ChatCompletionResult]) -> None:
+        super().__init__(model="fake", client=object())
+        self._responses = list(responses)
+
+    async def create(self, messages, tools=None, output_format=None, **kwargs: Any) -> ChatCompletionResult:
+        return self._responses.pop(0)
+
+    async def create_stream(self, *args: Any, **kwargs: Any) -> AsyncGenerator[ChatCompletionChunk, None]:
+        yield ChatCompletionChunk(content="", model="fake", is_complete=True)
+
+    def _to_config(self) -> BaseChatCompletionClientConfig:
+        return _Config(model=self.model, config=self.config)
+
+    @classmethod
+    def _from_config(cls, config: BaseChatCompletionClientConfig) -> FakeModelClient:
+        return cls([])
+
+
+def discover_schema() -> str:
+    """Return the table schema."""
+    return "orders(id, amount)"
+
+
+def run_query(sql: str) -> str:
+    """Run a read-only SQL query."""
+    if sql == "bad":
+        raise ValueError("unknown column")
+    return "rows: 3"
+
+
+def _calls(*calls: tuple[str, dict]) -> ChatCompletionResult:
+    return ChatCompletionResult(
+        message=AssistantMessage(
+            content="",
+            source="fake",
+            tool_calls=[
+                {"tool_name": name, "parameters": params, "call_id": f"c-{name}-{i}"}
+                for i, (name, params) in enumerate(calls)
+            ],
+        ),
+        usage=Usage(tokens_input=1, tokens_output=1),
+        model="fake",
+    )
+
+
+def _answer(text: str) -> ChatCompletionResult:
+    return ChatCompletionResult(
+        message=AssistantMessage(content=text, source="fake"),
+        usage=Usage(tokens_input=1, tokens_output=1),
+        model="fake",
+    )
+
+
+def _agent(client: FakeModelClient, **kwargs) -> Agent:
+    return Agent(
+        name="analyst",
+        description="desc",
+        instructions="help",
+        model_client=client,
+        tools=[discover_schema, run_query],
+        **kwargs,
+    )
+
+
+@pytest.mark.asyncio
+async def test_stops_after_multi_step_discovery_without_final_answer() -> None:
+    client = FakeModelClient(
+        [_calls(("discover_schema", {})), _calls(("run_query", {"sql": "ok"}))]
+    )
+    agent = _agent(client, stop_at_tools=["run_query"])
+
+    response = await agent.run(UserMessage(content="how many orders?", source="user"))
+
+    assert response.finish_reason == "tool_executed"
+    assert response.usage.llm_calls == 2
+    assert response.usage.tool_calls == 2
+    last = response.messages[-1]
+    assert isinstance(last, ToolMessage)
+    assert (last.tool_name, last.success, last.content) == ("run_query", True, "rows: 3")
+
+
+@pytest.mark.asyncio
+async def test_failed_stop_tool_does_not_stop_so_the_agent_can_retry() -> None:
+    client = FakeModelClient(
+        [_calls(("run_query", {"sql": "bad"})), _calls(("run_query", {"sql": "ok"}))]
+    )
+    agent = _agent(client, stop_at_tools=["run_query"])
+
+    response = await agent.run(UserMessage(content="how many orders?", source="user"))
+
+    assert response.finish_reason == "tool_executed"
+    results = [m for m in response.messages if isinstance(m, ToolMessage)]
+    assert [m.success for m in results] == [False, True]
+    assert response.usage.llm_calls == 2
+
+
+@pytest.mark.asyncio
+async def test_stop_tool_in_a_parallel_batch_runs_the_whole_batch() -> None:
+    client = FakeModelClient(
+        [_calls(("run_query", {"sql": "ok"}), ("discover_schema", {}))]
+    )
+    agent = _agent(client, stop_at_tools=["run_query"])
+
+    response = await agent.run(UserMessage(content="q", source="user"))
+
+    assert response.finish_reason == "tool_executed"
+    assert [m.tool_name for m in response.messages if isinstance(m, ToolMessage)] == [
+        "run_query",
+        "discover_schema",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_without_a_stop_tool_call_the_agent_answers_normally() -> None:
+    client = FakeModelClient([_calls(("discover_schema", {})), _answer("no query needed")])
+    agent = _agent(client, stop_at_tools=["run_query"])
+
+    response = await agent.run(UserMessage(content="what tables exist?", source="user"))
+
+    assert response.finish_reason == "stop"
+    assert response.final_content == "no query needed"
+
+
+@pytest.mark.asyncio
+async def test_stop_tool_never_succeeding_finalizes_on_exhaustion() -> None:
+    client = FakeModelClient(
+        [
+            _calls(("run_query", {"sql": "bad"})),
+            _calls(("run_query", {"sql": "bad"})),
+            _answer("The query failed: unknown column."),
+        ]
+    )
+    agent = _agent(client, stop_at_tools=["run_query"], max_iterations=3)
+
+    response = await agent.run(UserMessage(content="q", source="user"))
+
+    assert response.finish_reason == "max_iterations_finalized"
+    assert response.final_content == "The query failed: unknown column."
+
+
+def test_unknown_stop_tool_is_rejected() -> None:
+    with pytest.raises(AgentConfigurationError, match="run_qeury"):
+        _agent(FakeModelClient([]), stop_at_tools=["run_qeury"])
+
+
+def test_stop_at_tools_defaults_to_empty() -> None:
+    assert _agent(FakeModelClient([])).stop_at_tools == []

{agentbyte-0.42.4 → agentbyte-0.43.0}/tests/orchestration/test_orchestrator_synthesis.py

@@ -15,7 +15,13 @@ from agentbyte.context import AgentContext
 from agentbyte.execution_trace.collector import TraceCollector
 from agentbyte.llm.base import BaseChatCompletionClient, BaseChatCompletionClientConfig
 from agentbyte.llm.types import ChatCompletionChunk, ChatCompletionResult
-from agentbyte.messages import AssistantMessage, Message, ToolCallRequest, UserMessage
+from agentbyte.messages import (
+    AssistantMessage,
+    Message,
+    ToolCallRequest,
+    ToolMessage,
+    UserMessage,
+)
 from agentbyte.orchestration import (
     AgentHistoryPolicy,
     AIOrchestrator,
@@ -504,6 +510,89 @@ class TestSynthesisContext:
         assert "Failed step 1 (hardware): do hardware" in facts
         assert response.final_content == "final"
 
+    @pytest.mark.parametrize("finish_reason", ["max_iterations", "max_iterations_finalized"])
+    async def test_exhausted_worker_is_reported_as_partial(self, finish_reason: str) -> None:
+        hardware = ScriptAgent("hardware", "gave up: query kept failing", finish_reason=finish_reason)
+        synthesizer = ScriptAgent("synthesizer", "final")
+        orchestrator = RoundRobinOrchestrator(
+            [hardware, synthesizer], _never(), max_iterations=1, final_result_policy=_policy()
+        )
+
+        await orchestrator.run("task")
+
+        facts = _text(synthesizer.received_tasks[0])
+        assert "ran out of iterations before completing" in facts
+        assert "(treat their findings as partial): hardware" in facts
+        assert "ended in an error" not in facts
+
+
+def _prior_turn() -> list[Message]:
+    """One completed team turn: question, tool exchange, worker note, answer."""
+    return [
+        UserMessage(content="old question", source="user"),
+        AssistantMessage(
+            content="",
+            source="hardware",
+            tool_calls=[ToolCallRequest(tool_name="scan", parameters={}, call_id="old-1")],
+        ),
+        ToolMessage(
+            content="OLD TOOL PAYLOAD",
+            tool_call_id="old-1",
+            tool_name="scan",
+            success=True,
+            source="system",
+        ),
+        AssistantMessage(content="old intermediate note", source="hardware"),
+        AssistantMessage(content="old answer", source="synthesizer"),
+    ]
+
+
+@pytest.mark.asyncio
+class TestRunHistoryWindow:
+    async def _synthesis_input(self, window: str, *, task_in_context: bool = False) -> str:
+        hardware = ScriptAgent("hardware", "current finding")
+        synthesizer = ScriptAgent("synthesizer", "final")
+        orchestrator = RoundRobinOrchestrator(
+            [hardware, synthesizer],
+            _never(),
+            max_iterations=1,
+            final_result_policy=_policy(
+                synthesis_history=AgentHistoryPolicy(window=window, format="text")
+            ),
+        )
+        context = AgentContext(messages=_prior_turn())
+        if task_in_context:
+            context.messages.append(UserMessage(content="new question", source="user"))
+            await orchestrator.run(context=context)
+        else:
+            await orchestrator.run("new question", context=context)
+        return _text(synthesizer.received_tasks[0])
+
+    @pytest.mark.parametrize("task_in_context", [False, True])
+    async def test_run_window_keeps_this_run_and_condenses_prior_turns(
+        self, task_in_context: bool
+    ) -> None:
+        seen = await self._synthesis_input("run", task_in_context=task_in_context)
+
+        assert "old question" in seen
+        assert "old answer" in seen
+        assert "new question" in seen
+        assert "current finding" in seen
+        assert "OLD TOOL PAYLOAD" not in seen
+        assert "old intermediate note" not in seen
+        assert seen.index("old answer") < seen.index("current finding")
+
+    async def test_full_window_still_sends_prior_tool_results(self) -> None:
+        seen = await self._synthesis_input("full")
+
+        assert "OLD TOOL PAYLOAD" in seen
+        assert "old intermediate note" in seen
+
+    async def test_run_window_needs_no_message_limit(self) -> None:
+        policy = AgentHistoryPolicy(window="run", message_limit=3, format="text")
+
+        assert policy.message_limit is None
+
 
 @pytest.mark.asyncio
 class TestTerminalOutcomes:

agentbyte-0.42.4/src/agentbyte/__about__.py

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