ragbits-agents 1.4.0.dev202601310254__tar.gz → 1.4.0.dev202602030301__tar.gz

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/CHANGELOG.md

@@ -6,7 +6,6 @@
 - Add Support for Thinking in agents (#837)
 - Add parallel tool calling support to agents for concurrent tool execution (#836)
 - TodoOrchestrator & Todo list for agent (#823)
-- Support wrapping downstream agents as tools (#818)
 - Add syntax sugar allowing easier Agents definition (#820)
 - Add post-processors (#821)
 - Support streaming from downstream agents (#812)
@@ -17,9 +16,9 @@
 - Add supervisor post-processor (#830)
 - Add support for todo lists generated by agents with examples (#827)
 - Add long-term semantic memory tools for agents (#839)
-- Add control over what output from the tool is passed to the LLM (#920)
 - Add support for confirmation requests in agents (#853) (#914)
 - Add hooks system (pre- and post-tool) for lifecycle event interception (#914)
+- Add ToolReturn allowing the control which part of the tool output we pass to LLM (#920)
 
 ## 1.3.0 (2025-09-11)
 

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragbits-agents
-Version: 1.4.0.dev202601310254
+Version: 1.4.0.dev202602030301
 Summary: Building blocks for rapid development of GenAI applications
 Project-URL: Homepage, https://github.com/deepsense-ai/ragbits
 Project-URL: Bug Reports, https://github.com/deepsense-ai/ragbits/issues
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: ragbits-core==1.4.0.dev202601310254
+Requires-Dist: ragbits-core==1.4.0.dev202602030301
 Provides-Extra: a2a
 Requires-Dist: a2a-sdk<1.0.0,>=0.2.9; extra == 'a2a'
 Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == 'a2a'

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragbits-agents"
-version = "1.4.0.dev202601310254"
+version = "1.4.0.dev202602030301"
 description = "Building blocks for rapid development of GenAI applications"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,7 +31,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dependencies = ["ragbits-core==1.4.0.dev202601310254"]
+dependencies = ["ragbits-core==1.4.0.dev202602030301"]
 
 [project.optional-dependencies]
 a2a = [

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/src/ragbits/agents/_main.py

@@ -1036,12 +1036,11 @@ class Agent(
                 }
 
         # Execute POST_TOOL hooks with chaining
-        post_tool_result = await self.hook_manager.execute_post_tool(
+        post_tool_output = await self.hook_manager.execute_post_tool(
             tool_call=tool_call,
-            output=tool_output,
+            tool_return=tool_return,
             error=tool_error,
         )
-        tool_output = post_tool_result.output
 
         # Raise error after hooks have been executed
         if tool_error:
@@ -1051,8 +1050,8 @@ class Agent(
             id=tool_call.id,
             name=tool_call.name,
             arguments=tool_call.arguments,
-            result=tool_return.value,
-            metadata=tool_return.metadata,
+            result=post_tool_output.tool_return.value if post_tool_output.tool_return else None,
+            metadata=post_tool_output.tool_return.metadata if post_tool_output.tool_return else None,
         )
 
     @requires_dependencies(["a2a.types"], "a2a")

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/src/ragbits/agents/hooks/manager.py

@@ -8,11 +8,12 @@ organization, and execution of hooks during lifecycle events.
 import hashlib
 import json
 from collections import defaultdict
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from ragbits.agents.confirmation import ConfirmationRequest
 from ragbits.agents.hooks.base import Hook
 from ragbits.agents.hooks.types import EventType, PostToolInput, PostToolOutput, PreToolInput, PreToolOutput
+from ragbits.agents.tool import ToolReturn
 from ragbits.core.llms.base import ToolCall
 
 if TYPE_CHECKING:
@@ -156,7 +157,7 @@ class HookManager:
     async def execute_post_tool(
         self,
         tool_call: ToolCall,
-        output: Any,  # noqa: ANN401
+        tool_return: ToolReturn | None,
         error: Exception | None,
     ) -> PostToolOutput:
         """
@@ -166,7 +167,7 @@ class HookManager:
 
         Args:
             tool_call: The tool call that was executed
-            output: The tool output
+            tool_return: Object representing the output of the tool (with value passed to the LLM and metadata)
             error: Any error that occurred
 
         Returns:
@@ -175,20 +176,20 @@ class HookManager:
         hooks = self.get_hooks(EventType.POST_TOOL, tool_call.name)
 
         # Start with original output
-        current_output = output
+        current_output = tool_return
 
         for hook in hooks:
             # Create input with current state (chained from previous hook)
             hook_input = PostToolInput(
                 tool_call=tool_call,
-                output=current_output,
+                tool_return=current_output,
                 error=error,
             )
 
             result: PostToolOutput = await hook.execute(hook_input)
 
             # Chain output for next hook
-            current_output = result.output
+            current_output = result.tool_return
 
         # Return final chained result
-        return PostToolOutput(output=current_output)
+        return PostToolOutput(tool_return=current_output)

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/src/ragbits/agents/hooks/types.py

@@ -12,6 +12,7 @@ from typing import Any, Literal, TypeAlias
 from pydantic import BaseModel, Field, model_validator
 
 from ragbits.agents.confirmation import ConfirmationRequest
+from ragbits.agents.tool import ToolReturn
 from ragbits.core.llms.base import ToolCall
 
 
@@ -73,13 +74,13 @@ class PostToolInput(HookEventIO):
     Attributes:
         event_type: Always EventType.POST_TOOL (unchangeable)
         tool_call: The original tool call
-        output: The result returned by the tool (None if error occurred)
+        tool_return: The result returned by the tool (None if error occurred)
         error: Any error that occurred during execution (None if successful)
     """
 
     event_type: Literal[EventType.POST_TOOL] = Field(default=EventType.POST_TOOL, frozen=True)
     tool_call: ToolCall
-    output: Any = None
+    tool_return: ToolReturn | None = None
     error: Exception | None = None
 
 
@@ -120,20 +121,20 @@ class PostToolOutput(HookEventIO):
 
     Attributes:
         event_type: Always EventType.POST_TOOL (unchangeable)
-        output: Tool output to use (original or modified) - always present
+        tool_return: Tool output to use (original or modified) - None if the tool execution failed
 
     Example:
         ```python
         # Pass through unchanged
-        return PostToolOutput(output=input.output)
+        return PostToolOutput(tool_return=input.tool_return)
 
         # Modify output
-        return PostToolOutput(output={"filtered": data})
+        return PostToolOutput(tool_return=ToolReturn(value={"filtered": data}))
         ```
     """
 
     event_type: Literal[EventType.POST_TOOL] = Field(default=EventType.POST_TOOL, frozen=True)  # type: ignore[assignment]
-    output: Any
+    tool_return: ToolReturn | None
 
 
 # Type aliases for hook callbacks

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/tests/unit/conftest.py

@@ -10,6 +10,7 @@ from ragbits.agents.hooks.types import (
     PreToolInput,
     PreToolOutput,
 )
+from ragbits.agents.tool import ToolReturn
 
 # Reusable hook callbacks as fixtures
 
@@ -62,9 +63,10 @@ def append_output():
 
     def factory(text: str, prepend: bool = False) -> PostToolHookCallback:
         async def hook(input_data: PostToolInput) -> PostToolOutput:
+            tool_return_value = input_data.tool_return.value if input_data.tool_return is not None else None
             if prepend:
-                return PostToolOutput(output=f"{text}{input_data.output}")
-            return PostToolOutput(output=f"{input_data.output}{text}")
+                return PostToolOutput(tool_return=ToolReturn(f"{text}{tool_return_value}"))
+            return PostToolOutput(tool_return=ToolReturn(f"{tool_return_value}{text}"))
 
         return hook
 

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/tests/unit/hooks/test_manager.py

@@ -18,6 +18,7 @@ from ragbits.agents.hooks.types import (
     PreToolInput,
     PreToolOutput,
 )
+from ragbits.agents.tool import ToolReturn
 from ragbits.core.llms.base import ToolCall
 
 
@@ -154,9 +155,10 @@ class TestPostToolExecution:
                 Hook(event_type=EventType.POST_TOOL, callback=append_output(" + h2"), priority=2),
             ]
         )
-        result = await manager.execute_post_tool(tool_call, output="Original", error=None)
+        result = await manager.execute_post_tool(tool_call, tool_return=ToolReturn(value="Original"), error=None)
 
-        assert result.output == "Original + h1 + h2"
+        assert result.tool_return is not None
+        assert result.tool_return.value == "Original + h1 + h2"
 
 
 class TestConfirmationIdGeneration:

{ragbits_agents-1.4.0.dev202601310254 → ragbits_agents-1.4.0.dev202602030301}/tests/unit/hooks/test_types.py

@@ -13,6 +13,7 @@ from ragbits.agents.hooks.types import (
     PreToolInput,
     PreToolOutput,
 )
+from ragbits.agents.tool import ToolReturn
 from ragbits.core.llms.base import ToolCall
 
 
@@ -71,18 +72,25 @@ class TestPreToolOutput:
 
 class TestPostToolInput:
     def test_creation_with_output_and_error(self, tool_call: ToolCall):
-        input_data = PostToolInput(tool_call=tool_call, output="result")
+        input_data = PostToolInput(tool_call=tool_call, tool_return=ToolReturn(value="result"))
         assert input_data.event_type == EventType.POST_TOOL
-        assert input_data.output == "result"
+        assert input_data.tool_return is not None
+        assert input_data.tool_return.value == "result"
         assert input_data.error is None
 
         error = ValueError("failed")
-        input_with_error = PostToolInput(tool_call=tool_call, output=None, error=error)
+        input_with_error = PostToolInput(tool_call=tool_call, tool_return=None, error=error)
         assert input_with_error.error == error
 
 
 class TestPostToolOutput:
     def test_creation_with_various_outputs(self):
-        assert PostToolOutput(output="string").output == "string"
-        assert PostToolOutput(output={"key": "value"}).output == {"key": "value"}
-        assert PostToolOutput(output=None).output is None
+        string_output = PostToolOutput(tool_return=ToolReturn("string"))
+        assert string_output.tool_return is not None
+        assert string_output.tool_return.value == "string"
+
+        dict_output = PostToolOutput(tool_return=ToolReturn({"key": "value"}))
+        assert dict_output.tool_return is not None
+        assert dict_output.tool_return.value == {"key": "value"}
+
+        assert PostToolOutput(tool_return=None).tool_return is None