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

{ragbits_agents-1.4.0.dev202601300258 → 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,7 +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 support for confirmation requests in agents (#853)
+- 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.dev202601300258 → ragbits_agents-1.4.0.dev202602030301}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragbits-agents
-Version: 1.4.0.dev202601300258
+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.dev202601300258
+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.dev202601300258 → ragbits_agents-1.4.0.dev202602030301}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragbits-agents"
-version = "1.4.0.dev202601300258"
+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.dev202601300258"]
+dependencies = ["ragbits-core==1.4.0.dev202602030301"]
 
 [project.optional-dependencies]
 a2a = [

{ragbits_agents-1.4.0.dev202601300258 → ragbits_agents-1.4.0.dev202602030301}/src/ragbits/agents/__init__.py

@@ -9,8 +9,12 @@ from ragbits.agents._main import (
     ToolCall,
     ToolCallResult,
 )
+from ragbits.agents.hooks import (
+    EventType,
+    Hook,
+    HookManager,
+)
 from ragbits.agents.post_processors.base import PostProcessor, StreamingPostProcessor
-from ragbits.agents.tool import requires_confirmation
 from ragbits.agents.tools import LongTermMemory, MemoryEntry, create_memory_tools
 from ragbits.agents.types import QuestionAnswerAgent, QuestionAnswerPromptInput, QuestionAnswerPromptOutput
 
@@ -22,6 +26,9 @@ __all__ = [
     "AgentResultStreaming",
     "AgentRunContext",
     "DownstreamAgentResult",
+    "EventType",
+    "Hook",
+    "HookManager",
     "LongTermMemory",
     "MemoryEntry",
     "PostProcessor",
@@ -32,5 +39,4 @@ __all__ = [
     "ToolCall",
     "ToolCallResult",
     "create_memory_tools",
-    "requires_confirmation",
 ]

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

@@ -1,6 +1,4 @@
 import asyncio
-import hashlib
-import json
 import types
 import uuid
 from collections.abc import AsyncGenerator, AsyncIterator, Callable
@@ -32,6 +30,10 @@ from ragbits.agents.exceptions import (
     AgentToolNotAvailableError,
     AgentToolNotSupportedError,
 )
+from ragbits.agents.hooks import (
+    Hook,
+    HookManager,
+)
 from ragbits.agents.mcp.server import MCPServer, MCPServerStdio, MCPServerStreamableHttp
 from ragbits.agents.mcp.utils import get_tools
 from ragbits.agents.post_processors.base import (
@@ -40,7 +42,7 @@ from ragbits.agents.post_processors.base import (
     StreamingPostProcessor,
     stream_with_post_processing,
 )
-from ragbits.agents.tool import Tool, ToolCallResult, ToolChoice
+from ragbits.agents.tool import Tool, ToolCallResult, ToolChoice, ToolReturn
 from ragbits.core.audit.traces import trace
 from ragbits.core.llms.base import (
     LLM,
@@ -65,10 +67,6 @@ with suppress(ImportError):
 
     from ragbits.core.llms import LiteLLM
 
-# Confirmation ID length: 16 hex chars provides sufficient uniqueness
-# while being compact for display and storage
-CONFIRMATION_ID_LENGTH = 16
-
 _Input = TypeVar("_Input", bound=BaseModel)
 _Output = TypeVar("_Output")
 
@@ -212,9 +210,10 @@ class AgentRunContext(BaseModel, Generic[DepsT]):
     """Whether to stream events from downstream agents when tools execute other agents."""
     downstream_agents: dict[str, "Agent"] = Field(default_factory=dict)
     """Registry of all agents that participated in this run"""
-    confirmed_tools: list[dict[str, Any]] | None = Field(
-        default=None,
-        description="List of confirmed/declined tools from the frontend",
+    tool_confirmations: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="List of confirmed/declined tool executions. Each entry has 'confirmation_id' and 'confirmed' "
+        "(bool)",
     )
 
     def register_agent(self, agent: "Agent") -> None:
@@ -375,6 +374,7 @@ class Agent(
         keep_history: bool = False,
         tools: list[Callable] | None = None,
         mcp_servers: list[MCPServer] | None = None,
+        hooks: list[Hook] | None = None,
         default_options: AgentOptions[LLMClientOptionsT] | None = None,
     ) -> None:
         """
@@ -394,6 +394,7 @@ class Agent(
             keep_history: Whether to keep the history of the agent.
             tools: The tools available to the agent.
             mcp_servers: The MCP servers available to the agent.
+            hooks: List of tool hooks to register for tool lifecycle events.
             default_options: The default options for the agent run.
         """
         super().__init__(default_options)
@@ -416,6 +417,7 @@ class Agent(
         self.mcp_servers = mcp_servers or []
         self.history = history or []
         self.keep_history = keep_history
+        self.hook_manager = HookManager(hooks)
 
         if getattr(self, "system_prompt", None) and not getattr(self, "input_type", None):
             raise ValueError(
@@ -536,7 +538,9 @@ class Agent(
                 ):
                     if isinstance(result, ToolCallResult):
                         tool_calls.append(result)
-                        prompt_with_history = prompt_with_history.add_tool_use_message(**result.__dict__)
+                        prompt_with_history = prompt_with_history.add_tool_use_message(
+                            id=result.id, name=result.name, arguments=result.arguments, result=result.result
+                        )
 
                 turn_count += 1
             else:
@@ -762,7 +766,9 @@ class Agent(
                         elif isinstance(result, ToolCallResult):
                             # Add ALL tool results to history (including pending confirmations)
                             # This allows the agent to see them in the next turn
-                            prompt_with_history = prompt_with_history.add_tool_use_message(**result.__dict__)
+                            prompt_with_history = prompt_with_history.add_tool_use_message(
+                                id=result.id, name=result.name, arguments=result.arguments, result=result.result
+                            )
                             returned_tool_call = True
 
                     # If we have pending confirmations, prepare for text-only summary generation
@@ -958,54 +964,37 @@ class Agent(
 
         tool = tools_mapping[tool_call.name]
 
-        # Check if tool requires confirmation
-        if tool.requires_confirmation:
-            # Check if this tool has been confirmed in the context
-            confirmed_tools = context.confirmed_tools or []
-
-            # Generate a stable confirmation ID based on tool name and arguments
-            confirmation_id = hashlib.sha256(
-                f"{tool_call.name}:{json.dumps(tool_call.arguments, sort_keys=True)}".encode()
-            ).hexdigest()[:CONFIRMATION_ID_LENGTH]
+        # Execute PRE_TOOL hooks with chaining
+        pre_tool_result = await self.hook_manager.execute_pre_tool(
+            tool_call=tool_call,
+            context=context,
+        )
 
-            # Check if this specific tool call has been confirmed or declined
-            is_confirmed = any(
-                ct.get("confirmation_id") == confirmation_id and ct.get("confirmed") for ct in confirmed_tools
+        # Check decision
+        if pre_tool_result.decision == "deny":
+            yield ToolCallResult(
+                id=tool_call.id,
+                name=tool_call.name,
+                arguments=tool_call.arguments,
+                result=pre_tool_result.reason or "Tool execution denied",
             )
-            is_declined = any(
-                ct.get("confirmation_id") == confirmation_id and not ct.get("confirmed", True) for ct in confirmed_tools
+            return
+        # Handle "ask" decision from hooks
+        elif pre_tool_result.decision == "ask" and pre_tool_result.confirmation_request is not None:
+            yield pre_tool_result.confirmation_request
+
+            yield ToolCallResult(
+                id=tool_call.id,
+                name=tool_call.name,
+                arguments=tool_call.arguments,
+                result=pre_tool_result.reason or "Hook requires user confirmation",
             )
+            return
 
-            if is_declined:
-                # Tool was explicitly declined - skip execution entirely
-                yield ToolCallResult(
-                    id=tool_call.id,
-                    name=tool_call.name,
-                    arguments=tool_call.arguments,
-                    result="❌ Action declined by user",
-                )
-                return
-
-            if not is_confirmed:
-                # Tool not confirmed yet - create and yield confirmation request
-                request = ConfirmationRequest(
-                    confirmation_id=confirmation_id,
-                    tool_name=tool_call.name,
-                    tool_description=tool.description or "",
-                    arguments=tool_call.arguments,
-                )
-
-                # Yield confirmation request (will be streamed to frontend)
-                yield request
+        # Always update arguments (chained from hooks)
+        tool_call.arguments = pre_tool_result.arguments
 
-                # Yield a pending result and exit without executing
-                yield ToolCallResult(
-                    id=tool_call.id,
-                    name=tool_call.name,
-                    arguments=tool_call.arguments,
-                    result="⏳ Awaiting user confirmation",
-                )
-                return
+        tool_error: Exception | None = None
 
         with trace(agent_id=self.id, tool_name=tool_call.name, tool_arguments=tool_call.arguments) as outputs:
             try:
@@ -1019,35 +1008,50 @@ class Agent(
                     else asyncio.to_thread(tool.on_tool_call, **call_args)
                 )
 
-                if isinstance(tool_output, AgentResultStreaming):
+                if isinstance(tool_output, ToolReturn):
+                    tool_return = tool_output
+                elif isinstance(tool_output, AgentResultStreaming):
                     async for downstream_item in tool_output:
                         if context.stream_downstream_events:
                             yield DownstreamAgentResult(agent_id=tool.id, item=downstream_item)
-
-                    tool_output = {
-                        "content": tool_output.content,
+                    metadata = {
                         "metadata": tool_output.metadata,
                         "tool_calls": tool_output.tool_calls,
                         "usage": tool_output.usage,
                     }
+                    tool_return = ToolReturn(value=tool_output.content, metadata=metadata)
+                else:
+                    tool_return = ToolReturn(value=tool_output, metadata=None)
 
                 outputs.result = {
-                    "tool_output": tool_output,
+                    "tool_output": tool_return.value,
                     "tool_call_id": tool_call.id,
                 }
 
             except Exception as e:
+                tool_error = e
                 outputs.result = {
                     "error": str(e),
                     "tool_call_id": tool_call.id,
                 }
-                raise AgentToolExecutionError(tool_call.name, e) from e
+
+        # Execute POST_TOOL hooks with chaining
+        post_tool_output = await self.hook_manager.execute_post_tool(
+            tool_call=tool_call,
+            tool_return=tool_return,
+            error=tool_error,
+        )
+
+        # Raise error after hooks have been executed
+        if tool_error:
+            raise AgentToolExecutionError(tool_call.name, tool_error) from tool_error
 
         yield ToolCallResult(
             id=tool_call.id,
             name=tool_call.name,
             arguments=tool_call.arguments,
-            result=tool_output,
+            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.dev202602030301/src/ragbits/agents/hooks/__init__.py

@@ -0,0 +1,77 @@
+"""
+Hooks system for lifecycle events.
+
+This module provides a comprehensive hook system that allows users to register
+custom logic at various points in the execution lifecycle.
+
+Available event types:
+- PRE_TOOL: Before a tool is invoked
+- POST_TOOL: After a tool completes
+
+Example usage:
+
+    from ragbits.agents.hooks import (
+        EventType,
+        Hook,
+        PreToolInput,
+        PreToolOutput,
+    )
+
+    # Create a pre-tool hook callback
+    async def validate_input(input_data: PreToolInput) -> PreToolOutput:
+        if input_data.tool_call.name == "dangerous_tool":
+            return PreToolOutput(
+                arguments=input_data.tool_call.arguments,
+                decision="deny",
+                reason="This tool is not allowed"
+            )
+        return PreToolOutput(arguments=input_data.tool_call.arguments, decision="pass")
+
+    # Create hook instance with proper type annotation
+    hook: Hook[PreToolInput, PreToolOutput] = Hook(
+        event_type=EventType.PRE_TOOL,
+        callback=validate_input,
+        tool_names=["dangerous_tool"],
+        priority=10
+    )
+
+    # Register hooks with agent
+    agent = Agent(
+        ...,
+        hooks=[hook]
+    )
+"""
+
+from ragbits.agents.hooks.base import Hook, HookInputT, HookOutputT
+from ragbits.agents.hooks.confirmation import create_confirmation_hook
+from ragbits.agents.hooks.manager import HookManager
+from ragbits.agents.hooks.types import (
+    EventType,
+    PostToolHookCallback,
+    PostToolInput,
+    PostToolOutput,
+    PreToolHookCallback,
+    PreToolInput,
+    PreToolOutput,
+)
+
+__all__ = [
+    # Event types
+    "EventType",
+    # Core classes
+    "Hook",
+    # Type variables
+    "HookInputT",
+    "HookManager",
+    "HookOutputT",
+    "PostToolHookCallback",
+    # Input/output types
+    "PostToolInput",
+    "PostToolOutput",
+    # Callback type aliases
+    "PreToolHookCallback",
+    "PreToolInput",
+    "PreToolOutput",
+    # Hook factories
+    "create_confirmation_hook",
+]

ragbits_agents-1.4.0.dev202602030301/src/ragbits/agents/hooks/base.py

@@ -0,0 +1,94 @@
+"""
+Base classes for the hooks system.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Generic, TypeVar
+
+from ragbits.agents.hooks.types import EventType, HookEventIO
+
+HookInputT = TypeVar("HookInputT", bound=HookEventIO)
+HookOutputT = TypeVar("HookOutputT", bound=HookEventIO)
+
+
+class Hook(Generic[HookInputT, HookOutputT]):
+    """
+    A hook that intercepts execution at various lifecycle points.
+
+    Hooks allow you to:
+    - Validate inputs before execution (pre hooks)
+    - Control access (pre hooks)
+    - Modify inputs (pre hooks)
+    - Deny execution (pre hooks)
+    - Modify outputs (post hooks)
+    - Handle errors (post hooks)
+
+    Attributes:
+        event_type: The type of event (e.g., PRE_TOOL, POST_TOOL)
+        callback: The async function to call when the event is triggered
+        tool_names: List of tool names this hook applies to. If None, applies to all tools.
+        priority: Execution priority (lower numbers execute first, default: 100)
+
+    Example:
+        ```python
+        from ragbits.agents.hooks import Hook, EventType, PreToolInput, PreToolOutput
+
+
+        async def validate_input(input_data: PreToolInput) -> PreToolOutput:
+            if input_data.tool_call.name == "dangerous_tool":
+                return PreToolOutput(arguments=input_data.tool_call.arguments, decision="deny", reason="Not allowed")
+            return PreToolOutput(arguments=input_data.tool_call.arguments, decision="pass")
+
+
+        hook: Hook[PreToolInput, PreToolOutput] = Hook(
+            event_type=EventType.PRE_TOOL, callback=validate_input, tool_names=["dangerous_tool"], priority=10
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        event_type: EventType,
+        callback: Callable[[HookInputT], Awaitable[HookOutputT]],
+        tool_names: list[str] | None = None,
+        priority: int = 100,
+    ) -> None:
+        """
+        Initialize a hook.
+
+        Args:
+            event_type: The type of event (e.g., PRE_TOOL, POST_TOOL)
+            callback: The async function to call when the event is triggered
+            tool_names: List of tool names this hook applies to. If None, applies to all tools.
+            priority: Execution priority (lower numbers execute first, default: 100)
+        """
+        self.event_type = event_type
+        self.callback = callback
+        self.tool_names = tool_names
+        self.priority = priority
+
+    def matches_tool(self, tool_name: str) -> bool:
+        """
+        Check if this hook applies to the given tool name.
+
+        Args:
+            tool_name: The name of the tool to check
+
+        Returns:
+            True if this hook should be executed for the given tool
+        """
+        if self.tool_names is None:
+            return True
+        return tool_name in self.tool_names
+
+    async def execute(self, hook_input: HookInputT) -> HookOutputT:
+        """
+        Execute the hook callback with the given input.
+
+        Args:
+            hook_input: The input to pass to the callback
+
+        Returns:
+            The output from the callback
+        """
+        return await self.callback(hook_input)

ragbits_agents-1.4.0.dev202602030301/src/ragbits/agents/hooks/confirmation.py

@@ -0,0 +1,51 @@
+"""
+Helper functions for creating common hooks.
+
+This module provides factory functions for creating commonly used hooks.
+"""
+
+from ragbits.agents.hooks.base import Hook
+from ragbits.agents.hooks.types import EventType, PreToolInput, PreToolOutput
+
+
+def create_confirmation_hook(
+    tool_names: list[str] | None = None, priority: int = 1
+) -> Hook[PreToolInput, PreToolOutput]:
+    """
+    Create a hook that requires user confirmation before tool execution.
+
+    The hook returns "ask" decision, which causes the agent to yield a ConfirmationRequest
+    and wait for user approval/decline.
+
+    Args:
+        tool_names: List of tool names to require confirmation for. If None, applies to all tools.
+        priority: Hook priority (default: 1, runs first)
+
+    Returns:
+        Hook configured to require confirmation
+
+    Example:
+        ```python
+        from ragbits.agents import Agent
+        from ragbits.agents.hooks.confirmation import create_confirmation_hook
+
+        agent = Agent(
+            tools=[delete_file, send_email], hooks=[create_confirmation_hook(tool_names=["delete_file", "send_email"])]
+        )
+        ```
+    """
+
+    async def confirm_hook(input_data: PreToolInput) -> PreToolOutput:
+        """Hook that always returns 'ask' to require confirmation."""
+        return PreToolOutput(
+            arguments=input_data.tool_call.arguments,
+            decision="ask",
+            reason=f"Tool '{input_data.tool_call.name}' requires user confirmation",
+        )
+
+    return Hook(
+        event_type=EventType.PRE_TOOL,
+        callback=confirm_hook,
+        tool_names=tool_names,
+        priority=priority,
+    )