agentensemble 0.2.0__tar.gz → 0.3.0__tar.gz

{agentensemble-0.2.0 → agentensemble-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentensemble
-Version: 0.2.0
+Version: 0.3.0
 Summary: Orchestrate AI agents in perfect harmony - A comprehensive Python framework for building, testing, and orchestrating multi-agent AI systems
 Author-email: Irfan Ali <irfanali29@hotmail.com>
 Maintainer-email: Irfan Ali <irfanali29@hotmail.com>
@@ -76,25 +76,43 @@ AgentEnsemble is a modern framework for building and orchestrating AI agent syst
 ## Architecture
 
 <p align="center">
-  <img src="docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="800"/>
+  <img src="docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="900"/>
 </p>
 
-*Architecture, functionalities, and use cases — what AgentEnsemble is capable of.*
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        AgentEnsemble                             │
-├─────────────┬─────────────┬─────────────┬───────────────────────┤
-│   Agents    │ Orchestration│   Tools     │ Memory & Runner       │
-├─────────────┼─────────────┼─────────────┼───────────────────────┤
-│ ReActAgent  │ Ensemble    │ SearchTool  │ Session (InMemory,    │
-│ StateGraph  │ Supervisor  │ RAGTool     │ SQLite)               │
-│ RAGAgent    │ Swarm       │ @function_  │ Runner + RunConfig    │
-│ HybridAgent │ Pipeline    │ tool        │ TraceHooks            │
-│ RouterAgent │ Debate      │ Validation  │                       │
-│ PlannerAgent│             │             │                       │
-└─────────────┴─────────────┴─────────────┴───────────────────────┘
-```
+### Framework layers
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│                              AgentEnsemble — Layered Architecture                          │
+├─────────────────┬─────────────────────┬─────────────────────┬────────────────────────────┤
+│     AGENTS      │   ORCHESTRATION      │       TOOLS         │    MEMORY & RUNNER          │
+├─────────────────┼─────────────────────┼─────────────────────┼────────────────────────────┤
+│ ReActAgent      │ Supervisor          │ SearchTool          │ Session (InMemory, SQLite)  │
+│ StateGraphAgent │ Swarm (parallel)    │ RAGTool             │ RunConfig, RunHooks        │
+│ RAGAgent        │ Pipeline (seq)     │ @function_tool      │ TraceHooks (usage, cost)    │
+│ HybridAgent     │ Debate (consensus)  │ ValidationTool      │ interrupt_before_tools      │
+│ RouterAgent     │ Ensemble + Router   │ ToolRegistry         │ retries, session memory     │
+│ PlannerAgent    │ WorkflowGraph       │                     │                             │
+└─────────────────┴─────────────────────┴─────────────────────┴────────────────────────────┘
+         │                    │                    │                         │
+         └────────────────────┴────────────────────┴─────────────────────────┘
+                                          │
+                              ┌───────────▼───────────┐
+                              │   Use Case Spectrum   │
+                              └───────────────────────┘
+```
+
+### Use case spectrum
+
+| Layer | Use cases |
+|-------|-----------|
+| **Research & fact-checking** | ReActAgent + SearchTool; Swarm for parallel verification |
+| **Document Q&A** | RAGAgent + RAGTool; index URLs, ask questions |
+| **Multi-agent coordination** | Supervisor, Swarm, Pipeline; RouterAgent for LLM-based selection |
+| **Debate & consensus** | DebateOrchestrator; solvers propose → aggregator votes |
+| **Custom workflows** | WorkflowGraph (DAG), StateGraphAgent (nodes), PlannerAgent (decompose) |
+| **Human-in-loop** | `interrupt_before_tools` — pause before sensitive tools, resume with approval |
+| **Production pipelines** | Runner + RunConfig, retries, TraceHooks (usage/cost), Session memory |
 
 ---
 
@@ -367,7 +385,65 @@ Runner.run(agent, "What about its population?", config=config)  # Remembers cont
 
 ---
 
-### 11. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
+### 11. TraceHooks — Observability, token usage, cost estimation
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, TraceHooks, SearchTool
+
+agent = ReActAgent(name="research", tools=[SearchTool()], max_iterations=3)
+hooks = TraceHooks()
+
+config = RunConfig(trace_hooks=hooks)
+result = Runner.run(agent, "Who won the 2024 Nobel Prize in Physics?", config=config)
+
+print(result["result"][:100], "...")
+print("Usage:", result["metadata"].get("total_usage"))
+print("Cost (USD):", result["metadata"].get("cost_usd"))
+print("Events:", [e.type.value for e in hooks.events])
+```
+
+**Output:**
+
+```
+The 2024 Nobel Prize in Physics was awarded jointly to John J. Hopfield and Geoffrey E. Hinton...
+Usage: {'input_tokens': 1247, 'output_tokens': 89, 'total_tokens': 1336}
+Cost (USD): 0.00293
+Events: ['run_start', 'llm_start', 'llm_end', 'tool_start', 'tool_end', 'llm_start', 'llm_end', 'run_end']
+```
+
+---
+
+### 12. Human-in-loop — Pause before sensitive tools, resume with approval
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, function_tool
+
+@function_tool(description="Execute a payment")
+def execute_payment(amount: float, recipient: str) -> str:
+    return f"Paid ${amount} to {recipient}"
+
+agent = ReActAgent(tools=[execute_payment], max_iterations=2)
+config = RunConfig(interrupt_before_tools=["execute_payment"])
+
+result = Runner.run(agent, "Pay $50 to Alice", config=config)
+
+if result.get("__interrupted__"):
+    print("Paused for approval:", result["pending_tool"])
+    # Simulate human approval
+    result = Runner.run(agent, "...", config=config, resume=result["run_state"], resume_value="Paid $50 to Alice")
+print(result["result"])
+```
+
+**Output:**
+
+```
+Paused for approval: {'name': 'execute_payment', 'arguments': {'amount': 50.0, 'recipient': 'Alice'}}
+Paid $50 to Alice
+```
+
+---
+
+### 13. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
 
 ```python
 from agentensemble import RAGAgent, RAGTool
@@ -388,7 +464,7 @@ manageable subtasks that can be executed by specialized agents...
 
 ---
 
-### 12. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
+### 14. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
 
 ```python
 from pydantic import BaseModel, Field
@@ -469,7 +545,7 @@ pip install agentensemble[search]
 PYTHONPATH=. python examples/showcase_all.py
 ```
 
-Runs all 10 demos with real API calls.
+Runs all demos with real API calls.
 
 ---
 
@@ -507,7 +583,8 @@ Runs all 10 demos with real API calls.
 
 - **Session** — `InMemorySession`, `SQLiteSession` for multi-turn context
 - **Runner** — `Runner.run()`, `Runner.arun()` with `RunConfig`, `RunHooks`, retries
-- **TraceHooks** — Observability for runs, LLM calls, tools
+- **TraceHooks** — Observability: run/LLM/tool events, token usage, cost estimation
+- **Human-in-loop** — `interrupt_before_tools=["pay", "send_email"]` to pause for approval
 
 ---
 
@@ -542,7 +619,8 @@ agentensemble/
 | Graph workflows    | WorkflowGraph, StateGraph | Native       | No     | No      |
 | Debate pattern     | DebateOrchestrator        | Manual       | Yes    | Yes     |
 | Session memory     | InMemory, SQLite          | Checkpointer | No     | No      |
-| Observability      | TraceHooks                | LangSmith    | No     | No      |
+| Observability      | TraceHooks, usage, cost   | LangSmith    | No     | No      |
+| Human-in-loop     | interrupt_before_tools    | interrupt()  | No     | No      |
 
 ---
 
@@ -550,7 +628,8 @@ agentensemble/
 
 - **Retries**: `RunConfig(max_retries=2, retry_on=(RateLimitError, TimeoutError))`
 - **Session**: `Runner.run(agent, query, config=RunConfig(session=SQLiteSession()))`
-- **Tracing**: Attach `TraceHooks` to capture run/LLM/tool events
+- **Tracing**: `RunConfig(trace_hooks=TraceHooks())` — captures run/LLM/tool events, usage, cost
+- **Human-in-loop**: `RunConfig(interrupt_before_tools=["pay"])` — pause before sensitive tools; resume with `Runner.run(agent, ..., resume=run_state, resume_value="Approved")`
 - **Benchmarks**: `AgentComparison`, `Benchmark.research_tasks()`, `Metrics`
 
 ---

{agentensemble-0.2.0 → agentensemble-0.3.0}/README.md

@@ -23,25 +23,43 @@ AgentEnsemble is a modern framework for building and orchestrating AI agent syst
 ## Architecture
 
 <p align="center">
-  <img src="docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="800"/>
+  <img src="docs/agentensemble-architecture.png" alt="AgentEnsemble Architecture" width="900"/>
 </p>
 
-*Architecture, functionalities, and use cases — what AgentEnsemble is capable of.*
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        AgentEnsemble                             │
-├─────────────┬─────────────┬─────────────┬───────────────────────┤
-│   Agents    │ Orchestration│   Tools     │ Memory & Runner       │
-├─────────────┼─────────────┼─────────────┼───────────────────────┤
-│ ReActAgent  │ Ensemble    │ SearchTool  │ Session (InMemory,    │
-│ StateGraph  │ Supervisor  │ RAGTool     │ SQLite)               │
-│ RAGAgent    │ Swarm       │ @function_  │ Runner + RunConfig    │
-│ HybridAgent │ Pipeline    │ tool        │ TraceHooks            │
-│ RouterAgent │ Debate      │ Validation  │                       │
-│ PlannerAgent│             │             │                       │
-└─────────────┴─────────────┴─────────────┴───────────────────────┘
-```
+### Framework layers
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────────────┐
+│                              AgentEnsemble — Layered Architecture                          │
+├─────────────────┬─────────────────────┬─────────────────────┬────────────────────────────┤
+│     AGENTS      │   ORCHESTRATION      │       TOOLS         │    MEMORY & RUNNER          │
+├─────────────────┼─────────────────────┼─────────────────────┼────────────────────────────┤
+│ ReActAgent      │ Supervisor          │ SearchTool          │ Session (InMemory, SQLite)  │
+│ StateGraphAgent │ Swarm (parallel)    │ RAGTool             │ RunConfig, RunHooks        │
+│ RAGAgent        │ Pipeline (seq)     │ @function_tool      │ TraceHooks (usage, cost)    │
+│ HybridAgent     │ Debate (consensus)  │ ValidationTool      │ interrupt_before_tools      │
+│ RouterAgent     │ Ensemble + Router   │ ToolRegistry         │ retries, session memory     │
+│ PlannerAgent    │ WorkflowGraph       │                     │                             │
+└─────────────────┴─────────────────────┴─────────────────────┴────────────────────────────┘
+         │                    │                    │                         │
+         └────────────────────┴────────────────────┴─────────────────────────┘
+                                          │
+                              ┌───────────▼───────────┐
+                              │   Use Case Spectrum   │
+                              └───────────────────────┘
+```
+
+### Use case spectrum
+
+| Layer | Use cases |
+|-------|-----------|
+| **Research & fact-checking** | ReActAgent + SearchTool; Swarm for parallel verification |
+| **Document Q&A** | RAGAgent + RAGTool; index URLs, ask questions |
+| **Multi-agent coordination** | Supervisor, Swarm, Pipeline; RouterAgent for LLM-based selection |
+| **Debate & consensus** | DebateOrchestrator; solvers propose → aggregator votes |
+| **Custom workflows** | WorkflowGraph (DAG), StateGraphAgent (nodes), PlannerAgent (decompose) |
+| **Human-in-loop** | `interrupt_before_tools` — pause before sensitive tools, resume with approval |
+| **Production pipelines** | Runner + RunConfig, retries, TraceHooks (usage/cost), Session memory |
 
 ---
 
@@ -314,7 +332,65 @@ Runner.run(agent, "What about its population?", config=config)  # Remembers cont
 
 ---
 
-### 11. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
+### 11. TraceHooks — Observability, token usage, cost estimation
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, TraceHooks, SearchTool
+
+agent = ReActAgent(name="research", tools=[SearchTool()], max_iterations=3)
+hooks = TraceHooks()
+
+config = RunConfig(trace_hooks=hooks)
+result = Runner.run(agent, "Who won the 2024 Nobel Prize in Physics?", config=config)
+
+print(result["result"][:100], "...")
+print("Usage:", result["metadata"].get("total_usage"))
+print("Cost (USD):", result["metadata"].get("cost_usd"))
+print("Events:", [e.type.value for e in hooks.events])
+```
+
+**Output:**
+
+```
+The 2024 Nobel Prize in Physics was awarded jointly to John J. Hopfield and Geoffrey E. Hinton...
+Usage: {'input_tokens': 1247, 'output_tokens': 89, 'total_tokens': 1336}
+Cost (USD): 0.00293
+Events: ['run_start', 'llm_start', 'llm_end', 'tool_start', 'tool_end', 'llm_start', 'llm_end', 'run_end']
+```
+
+---
+
+### 12. Human-in-loop — Pause before sensitive tools, resume with approval
+
+```python
+from agentensemble import ReActAgent, Runner, RunConfig, function_tool
+
+@function_tool(description="Execute a payment")
+def execute_payment(amount: float, recipient: str) -> str:
+    return f"Paid ${amount} to {recipient}"
+
+agent = ReActAgent(tools=[execute_payment], max_iterations=2)
+config = RunConfig(interrupt_before_tools=["execute_payment"])
+
+result = Runner.run(agent, "Pay $50 to Alice", config=config)
+
+if result.get("__interrupted__"):
+    print("Paused for approval:", result["pending_tool"])
+    # Simulate human approval
+    result = Runner.run(agent, "...", config=config, resume=result["run_state"], resume_value="Paid $50 to Alice")
+print(result["result"])
+```
+
+**Output:**
+
+```
+Paused for approval: {'name': 'execute_payment', 'arguments': {'amount': 50.0, 'recipient': 'Alice'}}
+Paid $50 to Alice
+```
+
+---
+
+### 13. RAGAgent — Document Q&A (optional: `pip install agentensemble[rag]`)
 
 ```python
 from agentensemble import RAGAgent, RAGTool
@@ -335,7 +411,7 @@ manageable subtasks that can be executed by specialized agents...
 
 ---
 
-### 12. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
+### 14. StructuredAgent — Pydantic output (optional: `langchain>=1.1`)
 
 ```python
 from pydantic import BaseModel, Field
@@ -416,7 +492,7 @@ pip install agentensemble[search]
 PYTHONPATH=. python examples/showcase_all.py
 ```
 
-Runs all 10 demos with real API calls.
+Runs all demos with real API calls.
 
 ---
 
@@ -454,7 +530,8 @@ Runs all 10 demos with real API calls.
 
 - **Session** — `InMemorySession`, `SQLiteSession` for multi-turn context
 - **Runner** — `Runner.run()`, `Runner.arun()` with `RunConfig`, `RunHooks`, retries
-- **TraceHooks** — Observability for runs, LLM calls, tools
+- **TraceHooks** — Observability: run/LLM/tool events, token usage, cost estimation
+- **Human-in-loop** — `interrupt_before_tools=["pay", "send_email"]` to pause for approval
 
 ---
 
@@ -489,7 +566,8 @@ agentensemble/
 | Graph workflows    | WorkflowGraph, StateGraph | Native       | No     | No      |
 | Debate pattern     | DebateOrchestrator        | Manual       | Yes    | Yes     |
 | Session memory     | InMemory, SQLite          | Checkpointer | No     | No      |
-| Observability      | TraceHooks                | LangSmith    | No     | No      |
+| Observability      | TraceHooks, usage, cost   | LangSmith    | No     | No      |
+| Human-in-loop     | interrupt_before_tools    | interrupt()  | No     | No      |
 
 ---
 
@@ -497,7 +575,8 @@ agentensemble/
 
 - **Retries**: `RunConfig(max_retries=2, retry_on=(RateLimitError, TimeoutError))`
 - **Session**: `Runner.run(agent, query, config=RunConfig(session=SQLiteSession()))`
-- **Tracing**: Attach `TraceHooks` to capture run/LLM/tool events
+- **Tracing**: `RunConfig(trace_hooks=TraceHooks())` — captures run/LLM/tool events, usage, cost
+- **Human-in-loop**: `RunConfig(interrupt_before_tools=["pay"])` — pause before sensitive tools; resume with `Runner.run(agent, ..., resume=run_state, resume_value="Approved")`
 - **Benchmarks**: `AgentComparison`, `Benchmark.research_tasks()`, `Metrics`
 
 ---

{agentensemble-0.2.0 → agentensemble-0.3.0}/agentensemble/__init__.py

@@ -4,7 +4,7 @@ AgentEnsemble - Orchestrate AI agents in perfect harmony
 A comprehensive framework for building, testing, and orchestrating multi-agent AI systems.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __author__ = "Irfan Ali"
 
 # Core imports
@@ -52,7 +52,7 @@ from agentensemble.core import AgentProtocol
 from agentensemble.router import RouterAgent
 from agentensemble.planner import PlannerAgent
 from agentensemble.graph import WorkflowGraph, Node, Edge
-from agentensemble.tracing import TraceHooks, TraceEvent
+from agentensemble.tracing import TraceHooks, TraceEvent, TraceEventType, estimate_cost
 
 __all__ = [
     # Version
@@ -101,6 +101,8 @@ __all__ = [
     # Tracing
     "TraceHooks",
     "TraceEvent",
+    "TraceEventType",
+    "estimate_cost",
 ]
 
 # Add StructuredAgent if available

{agentensemble-0.2.0 → agentensemble-0.3.0}/agentensemble/agents/react_agent.py

@@ -10,12 +10,22 @@ Research basis:
 """
 
 import asyncio
+import time
 from typing import Any, AsyncIterator, Dict, List, Optional
 
 from agentensemble.agents.base import BaseAgent, AgentState
 from agentensemble.llm.interface import LLMMessage, LLMProvider, ToolCall
 from agentensemble.tools.adapters import get_tool_schemas, ainvoke_tool
 
+try:
+    from agentensemble.tracing import TraceEventType, TraceEvent, estimate_cost
+    TRACING_AVAILABLE = True
+except ImportError:
+    TRACING_AVAILABLE = False
+    TraceEventType = None
+    TraceEvent = None
+    estimate_cost = None
+
 try:
     from agentensemble.llm.mistral_provider import MistralLLMProvider
     LLM_AVAILABLE = True
@@ -213,6 +223,35 @@ class ReActAgent(BaseAgent):
             raw.append(d)
         self.session.add_messages(raw)
 
+    def _messages_to_dicts(self, msgs: List[LLMMessage]) -> List[Dict[str, Any]]:
+        """Serialize messages for run_state (human-in-loop resume)."""
+        out = []
+        for m in msgs:
+            d: Dict[str, Any] = {"role": m.role, "content": m.content if isinstance(m.content, str) else ""}
+            if m.tool_call_id:
+                d["tool_call_id"] = m.tool_call_id
+            if m.tool_calls:
+                d["tool_calls"] = [{"id": t.id, "name": t.name, "arguments": t.arguments} for t in m.tool_calls]
+            out.append(d)
+        return out
+
+    def _dicts_to_messages(self, raw: List[Dict[str, Any]]) -> List[LLMMessage]:
+        """Deserialize messages from run_state."""
+        out: List[LLMMessage] = []
+        for m in raw:
+            tc = None
+            if m.get("tool_calls"):
+                tc = [ToolCall(id=x.get("id", ""), name=x.get("name", ""), arguments=x.get("arguments", {})) for x in m["tool_calls"]]
+            out.append(
+                LLMMessage(
+                    role=m["role"],
+                    content=m.get("content", ""),
+                    tool_call_id=m.get("tool_call_id"),
+                    tool_calls=tc,
+                )
+            )
+        return out
+
     async def _run_loop(self, query: str, **kwargs: Any) -> Dict[str, Any]:
         """Async ReAct loop: Reason -> Act -> Observe until final answer."""
         if self.llm is None:
@@ -221,43 +260,99 @@ class ReActAgent(BaseAgent):
                 "or pass llm=YourLLMProvider()."
             )
 
-        state = AgentState(query=query, context=kwargs.get("context", {}))
+        run_config = kwargs.get("run_config")
+        trace_hooks = getattr(run_config, "trace_hooks", None) if run_config else None
+        interrupt_tools = getattr(run_config, "interrupt_before_tools", None) or []
+        resume_state = kwargs.get("resume")
+        resume_value = kwargs.get("resume_value")
+
+        if resume_state and resume_value is not None:
+            messages = self._dicts_to_messages(resume_state["messages"])
+            state = AgentState(**resume_state["state"])
+            pending = resume_state["pending_tc"]
+            messages.append(
+                LLMMessage(role="tool", content=str(resume_value), tool_call_id=pending.get("id", ""))
+            )
+            state = self._update_state(state, tool_calls=[{"name": pending.get("name", ""), "result": str(resume_value)}])
+        else:
+            state = AgentState(query=query, context=kwargs.get("context", {}))
+            history = self._session_to_messages()
+            messages = [
+                LLMMessage(role="system", content=""),
+                *history,
+                LLMMessage(role="user", content=query),
+            ]
+            system_prompt = self.llm.get_react_system_prompt(
+                get_tool_schemas(self.tools) if self.tools else [],
+                self.max_iterations,
+            )
+            messages[0] = LLMMessage(role="system", content=system_prompt)
+
         tool_schemas = get_tool_schemas(self.tools) if self.tools else []
         tool_map = {t.name: t for t in self.tools} if self.tools else {}
+        history_len = len(self._session_to_messages())
+        total_usage: Dict[str, int] = {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
 
-        system_prompt = self.llm.get_react_system_prompt(tool_schemas, self.max_iterations)
-        history = self._session_to_messages()
-        messages: List[LLMMessage] = [
-            LLMMessage(role="system", content=system_prompt),
-            *history,
-            LLMMessage(role="user", content=query),
-        ]
+        if trace_hooks and TRACING_AVAILABLE:
+            trace_hooks.emit(TraceEvent(type=TraceEventType.RUN_START, agent=self.name, data={"query": query[:200]}))
 
         for iteration in range(self.max_iterations):
             if not self._validate_state(state):
                 break
 
-            # After tool results, omit tools to encourage final answer
             has_tool_results = any(m.role == "tool" for m in messages)
             use_tools = tool_schemas and not has_tool_results
 
+            llm_start = time.perf_counter()
+            if trace_hooks and TRACING_AVAILABLE:
+                trace_hooks.emit(TraceEvent(type=TraceEventType.LLM_START, agent=self.name, data={}))
+
             response = await self.llm.agenerate(
                 messages,
                 tools=tool_schemas if use_tools else None,
                 tool_choice="auto" if use_tools else None,
             )
 
+            if response.usage:
+                for k in total_usage:
+                    total_usage[k] = total_usage.get(k, 0) + response.usage.get(k, 0)
+            if trace_hooks and TRACING_AVAILABLE:
+                llm_data: Dict[str, Any] = {}
+                if response.usage:
+                    llm_data["usage"] = response.usage
+                    if estimate_cost:
+                        model = getattr(self.llm, "model_name", "mistral-large-latest")
+                        llm_data["cost_usd"] = estimate_cost(response.usage, model=model)
+                trace_hooks.emit(
+                    TraceEvent(
+                        type=TraceEventType.LLM_END,
+                        agent=self.name,
+                        data=llm_data,
+                        duration_ms=(time.perf_counter() - llm_start) * 1000,
+                    )
+                )
+
             if response.tool_calls:
-                # Append assistant message with tool_calls (required for multi-turn)
                 messages.append(
-                    LLMMessage(
-                        role="assistant",
-                        content=response.content or "",
-                        tool_calls=response.tool_calls,
-                    )
+                    LLMMessage(role="assistant", content=response.content or "", tool_calls=response.tool_calls)
                 )
-                # Execute each tool and append results (preserve tool_call id for matching)
                 for tc in response.tool_calls:
+                    if interrupt_tools and tc.name in interrupt_tools:
+                        run_state = {
+                            "messages": self._messages_to_dicts(messages),
+                            "state": state.model_dump(),
+                            "pending_tc": {"id": tc.id or f"call_{tc.name}", "name": tc.name, "arguments": tc.arguments},
+                        }
+                        return {
+                            "__interrupted__": True,
+                            "run_state": run_state,
+                            "pending_tool": {"name": tc.name, "arguments": tc.arguments},
+                        }
+
+                    tool_start = time.perf_counter()
+                    if trace_hooks and TRACING_AVAILABLE:
+                        trace_hooks.emit(TraceEvent(type=TraceEventType.TOOL_START, agent=self.name, data={"tool": tc.name}))
+
                     tool = tool_map.get(tc.name)
                     if tool:
                         try:
@@ -268,33 +363,50 @@ class ReActAgent(BaseAgent):
                     else:
                         result_str = f"Tool '{tc.name}' not found"
 
-                    messages.append(
-                        LLMMessage(
-                            role="tool",
-                            content=result_str,
-                            tool_call_id=tc.id or f"call_{tc.name}",
+                    if trace_hooks and TRACING_AVAILABLE:
+                        trace_hooks.emit(
+                            TraceEvent(
+                                type=TraceEventType.TOOL_END,
+                                agent=self.name,
+                                data={"tool": tc.name, "result_preview": result_str[:100]},
+                                duration_ms=(time.perf_counter() - tool_start) * 1000,
+                            )
                         )
+
+                    messages.append(
+                        LLMMessage(role="tool", content=result_str, tool_call_id=tc.id or f"call_{tc.name}")
                     )
-                    state = self._update_state(
-                        state,
-                        tool_calls=[{"name": tc.name, "result": result_str}],
-                    )
+                    state = self._update_state(state, tool_calls=[{"name": tc.name, "result": result_str}])
             else:
-                # Final answer
                 state.result = response.content or state.result
                 break
 
-        # Persist to session (user + assistant/tool messages from this turn)
         if self.session:
-            to_save = messages[len(history) + 2:]  # Skip system, history; keep user + new
+            to_save = messages[history_len + 2:]
             if to_save:
                 self._messages_to_session(to_save)
 
+        metadata: Dict[str, Any] = {
+            "iterations": state.iteration_count,
+            "tool_calls": len(state.tool_calls),
+            "agent": self.name,
+        }
+        if total_usage.get("total_tokens"):
+            metadata["total_usage"] = total_usage
+            if estimate_cost:
+                model = getattr(self.llm, "model_name", "mistral-large-latest")
+                metadata["cost_usd"] = estimate_cost(total_usage, model=model)
+
+        if trace_hooks and TRACING_AVAILABLE:
+            trace_hooks.emit(
+                TraceEvent(
+                    type=TraceEventType.RUN_END,
+                    agent=self.name,
+                    data={"query": query[:200], "usage": total_usage, "result_preview": str(state.result or "")[:200]},
+                )
+            )
+
         return {
             "result": state.result or "No result generated",
-            "metadata": {
-                "iterations": state.iteration_count,
-                "tool_calls": len(state.tool_calls),
-                "agent": self.name,
-            },
+            "metadata": metadata,
         }