add capability and example

Author: evalstate

examples/tool-use-agent-hooks/agent.py

@@ -0,0 +1,56 @@
+import asyncio
+
+from fast_agent import FastAgent
+from fast_agent.agents.agent_types import AgentConfig
+from fast_agent.agents.tool_agent import ToolAgent
+from fast_agent.agents.tool_runner import ToolRunnerHooks
+from fast_agent.context import Context
+from fast_agent.interfaces import ToolRunnerHookCapable
+from fast_agent.types import PromptMessageExtended
+
+
+def get_video_call_transcript(video_id: str) -> str:
+    return "Assistant: Hi, how can I assist you today?\n\nCustomer: Hi, I wanted to ask you about last invoice I received..."
+
+
+class HookedToolAgent(ToolAgent, ToolRunnerHookCapable):
+    def __init__(
+        self,
+        config: AgentConfig,
+        context: Context | None = None,
+    ):
+        tools = [get_video_call_transcript]
+        super().__init__(config, tools, context)
+        self._hooks = ToolRunnerHooks(
+            before_llm_call=self._add_style_hint,
+            after_tool_call=self._log_tool_result,
+        )
+
+    @property
+    def tool_runner_hooks(self) -> ToolRunnerHooks | None:
+        return self._hooks
+
+    async def _add_style_hint(self, runner, messages: list[PromptMessageExtended]) -> None:
+        if runner.iteration == 0:
+            runner.append_messages("Keep the answer to one short sentence.")
+
+    async def _log_tool_result(self, runner, message: PromptMessageExtended) -> None:
+        if message.tool_results:
+            tool_names = ", ".join(message.tool_results.keys())
+            print(f"[hook] tool results received: {tool_names}")
+
+
+fast = FastAgent("Example Tool Use Application (Hooks)")
+
+
+@fast.custom(HookedToolAgent)
+async def main() -> None:
+    async with fast.run() as agent:
+        await agent.default.generate(
+            "What is the topic of the video call no.1234?",
+        )
+        await agent.interactive()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/tool-use-agent-hooks/fastagent.config.yaml

@@ -0,0 +1,6 @@
+default_model: haiku
+
+logger:
+  type: file
+  level: error
+  truncate_tools: true

src/fast_agent/agents/llm_agent.py

@@ -280,7 +280,13 @@ async def generate_impl(
         Messages are already normalized to List[PromptMessageExtended].
         """
         if "user" == messages[-1].role:
-            self.show_user_message(message=messages[-1])
+            trailing_users: list[PromptMessageExtended] = []
+            for message in reversed(messages):
+                if message.role != "user":
+                    break
+                trailing_users.append(message)
+            for message in reversed(trailing_users):
+                self.show_user_message(message=message)
 
         # TODO - manage error catch, recovery, pause
         summary_text: Text | None = None
@@ -341,7 +347,13 @@ async def structured_impl(
         request_params: RequestParams | None = None,
     ) -> Tuple[ModelT | None, PromptMessageExtended]:
         if "user" == messages[-1].role:
-            self.show_user_message(message=messages[-1])
+            trailing_users: list[PromptMessageExtended] = []
+            for message in reversed(messages):
+                if message.role != "user":
+                    break
+                trailing_users.append(message)
+            for message in reversed(trailing_users):
+                self.show_user_message(message=message)
 
         (result, message), summary = await self._structured_with_summary(
             messages, model, request_params

src/fast_agent/agents/tool_agent.py

@@ -14,6 +14,7 @@
 )
 from fast_agent.context import Context
 from fast_agent.core.logging.logger import get_logger
+from fast_agent.interfaces import ToolRunnerHookCapable
 from fast_agent.mcp.helpers.content_helpers import text_content
 from fast_agent.tools.elicitation import get_elicitation_fastmcp_tool
 from fast_agent.types import PromptMessageExtended, RequestParams, ToolTimingInfo
@@ -57,7 +58,6 @@ def __init__(
                     logger.warning(f"Failed to initialize human-input tool: {e}")
 
         for tool in working_tools:
-            (tool)
             if isinstance(tool, FastMCPTool):
                 fast_tool = tool
             elif callable(tool):
@@ -99,6 +99,8 @@ async def generate_impl(
         return await runner.until_done()
 
     def _tool_runner_hooks(self) -> ToolRunnerHooks | None:
+        if isinstance(self, ToolRunnerHookCapable):
+            return self.tool_runner_hooks
         return None
 
     async def _tool_runner_llm_step(

src/fast_agent/agents/workflow/agents_as_tools_agent.py

@@ -639,7 +639,6 @@ async def _run_child_tools(
 
         call_descriptors: list[dict[str, Any]] = []
         descriptor_by_id: dict[str, dict[str, Any]] = {}
-        tasks: list[asyncio.Task[CallToolResult]] = []
         id_list: list[str] = []
 
         for correlation_id, tool_request in (request.tool_calls or {}).items():

src/fast_agent/interfaces.py

@@ -33,6 +33,7 @@
     from fast_agent.acp.acp_aware_mixin import ACPCommand, ACPModeInfo
     from fast_agent.acp.acp_context import ACPContext
     from fast_agent.agents.agent_types import AgentConfig, AgentType
+    from fast_agent.agents.tool_runner import ToolRunnerHooks
     from fast_agent.context import Context
     from fast_agent.llm.model_info import ModelInfo
 
@@ -41,6 +42,7 @@
     "StreamingAgentProtocol",
     "LlmAgentProtocol",
     "AgentProtocol",
+    "ToolRunnerHookCapable",
     "ACPAwareProtocol",
     "LLMFactoryProtocol",
     "ModelFactoryFunctionProtocol",
@@ -265,6 +267,14 @@ def initialized(self) -> bool: ...
     def set_instruction(self, instruction: str) -> None: ...
 
 
+@runtime_checkable
+class ToolRunnerHookCapable(Protocol):
+    """Optional capability for agents to expose ToolRunner hooks."""
+
+    @property
+    def tool_runner_hooks(self) -> "ToolRunnerHooks | None": ...
+
+
 @runtime_checkable
 class StreamingAgentProtocol(AgentProtocol, Protocol):
     """Optional extension for agents that expose LLM streaming callbacks."""

src/fast_agent/utils/async_utils.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Iterable
-from typing import TypeVar
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Iterable
 
 T = TypeVar("T")