feat: #2228 persist tool origin metadata in run items

Co-authored-by: Hassan Abu Alhaj <136383052+habema@users.noreply.github.com>

Author: seratch

src/agents/__init__.py

@@ -160,6 +160,8 @@
     ShellToolLocalSkill,
     ShellToolSkillReference,
     Tool,
+    ToolOrigin,
+    ToolOriginType,
     ToolOutputFileContent,
     ToolOutputFileContentDict,
     ToolOutputImage,
@@ -393,6 +395,8 @@ def enable_verbose_stdout_logging():
     "MCPApprovalResponseItem",
     "ToolCallItem",
     "ToolCallOutputItem",
+    "ToolOrigin",
+    "ToolOriginType",
     "ReasoningItem",
     "ItemHelpers",
     "RunHooks",

src/agents/agent.py

@@ -46,6 +46,8 @@
     FunctionToolResult,
     Tool,
     ToolErrorFunction,
+    ToolOrigin,
+    ToolOriginType,
     _build_handled_function_tool_error_handler,
     _build_wrapped_function_tool,
     _log_function_tool_invocation,
@@ -886,6 +888,11 @@ async def dispatch_stream_events() -> None:
             strict_json_schema=True,
             is_enabled=is_enabled,
             needs_approval=needs_approval,
+            tool_origin=ToolOrigin(
+                type=ToolOriginType.AGENT_AS_TOOL,
+                agent_name=self.name,
+                agent_tool_name=tool_name_resolved,
+            ),
         )
         run_agent_tool._is_agent_tool = True
         run_agent_tool._agent_instance = self

src/agents/items.py

@@ -54,6 +54,7 @@
 from .exceptions import AgentsException, ModelBehaviorError
 from .logger import logger
 from .tool import (
+    ToolOrigin,
     ToolOutputFileContent,
     ToolOutputImage,
     ToolOutputText,
@@ -358,6 +359,9 @@ class ToolCallItem(RunItemBase[Any]):
     title: str | None = None
     """Optional short display label if known at item creation time."""
 
+    tool_origin: ToolOrigin | None = None
+    """Optional metadata describing the source of a function-tool-backed item."""
+
 
 ToolCallOutputTypes: TypeAlias = (
     FunctionCallOutput
@@ -382,6 +386,9 @@ class ToolCallOutputItem(RunItemBase[Any]):
 
     type: Literal["tool_call_output_item"] = "tool_call_output_item"
 
+    tool_origin: ToolOrigin | None = None
+    """Optional metadata describing the source of a function-tool-backed item."""
+
     def to_input_item(self) -> TResponseInputItem:
         """Converts the tool output into an input item for the next model turn.
 

src/agents/mcp/util.py

@@ -27,6 +27,8 @@
     FunctionTool,
     Tool,
     ToolErrorFunction,
+    ToolOrigin,
+    ToolOriginType,
     ToolOutputImageDict,
     ToolOutputTextDict,
     _build_handled_function_tool_error_handler,
@@ -314,6 +316,10 @@ def to_function_tool(
             strict_json_schema=is_strict,
             needs_approval=needs_approval,
             mcp_title=resolve_mcp_tool_title(tool),
+            tool_origin=ToolOrigin(
+                type=ToolOriginType.MCP,
+                mcp_server_name=server.name,
+            ),
         )
         return function_tool
 

src/agents/run_internal/approvals.py

@@ -13,6 +13,7 @@
 
 from ..agent import Agent
 from ..items import ItemHelpers, RunItem, ToolApprovalItem, ToolCallOutputItem, TResponseInputItem
+from ..tool import ToolOrigin
 from .items import ReasoningItemIdPolicy, run_item_to_input_item
 
 # --------------------------
@@ -28,6 +29,7 @@ def append_approval_error_output(
     tool_name: str,
     call_id: str | None,
     message: str,
+    tool_origin: ToolOrigin | None = None,
 ) -> None:
     """Emit a synthetic tool output so users see why an approval failed."""
     error_tool_call = _build_function_tool_call_for_approval_error(tool_call, tool_name, call_id)
@@ -36,6 +38,7 @@ def append_approval_error_output(
             output=message,
             raw_item=ItemHelpers.tool_call_output_item(error_tool_call, message),
             agent=agent,
+            tool_origin=tool_origin,
         )
     )
 

src/agents/run_internal/items.py

@@ -308,6 +308,7 @@ def function_rejection_item(
     *,
     rejection_message: str = REJECTION_MESSAGE,
     scope_id: str | None = None,
+    tool_origin: Any = None,
 ) -> ToolCallOutputItem:
     """Build a ToolCallOutputItem representing a rejected function tool call."""
     if isinstance(tool_call, ResponseFunctionToolCall):
@@ -316,6 +317,7 @@ def function_rejection_item(
         output=rejection_message,
         raw_item=ItemHelpers.tool_call_output_item(tool_call, rejection_message),
         agent=agent,
+        tool_origin=tool_origin,
     )
 
 

src/agents/run_internal/run_loop.py

@@ -11,7 +11,12 @@
 from collections.abc import Awaitable, Callable, Mapping
 from typing import Any, TypeVar, cast
 
-from openai.types.responses import Response, ResponseCompletedEvent, ResponseOutputItemDoneEvent
+from openai.types.responses import (
+    Response,
+    ResponseCompletedEvent,
+    ResponseFunctionToolCall,
+    ResponseOutputItemDoneEvent,
+)
 from openai.types.responses.response_output_item import McpCall, McpListTools
 from openai.types.responses.response_prompt_param import ResponsePromptParam
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
@@ -64,7 +69,7 @@
     RawResponsesStreamEvent,
     RunItemStreamEvent,
 )
-from ..tool import FunctionTool, Tool, dispose_resolved_computers
+from ..tool import FunctionTool, Tool, dispose_resolved_computers, get_function_tool_origin
 from ..tracing import Span, SpanError, agent_span, get_current_trace, task_span, turn_span
 from ..tracing.model_tracing import get_model_tracing_impl
 from ..tracing.span_data import AgentSpanData, TaskSpanData
@@ -138,6 +143,7 @@
 from .streaming import stream_step_items_to_queue, stream_step_result_to_queue
 from .tool_actions import ApplyPatchAction, ComputerAction, LocalShellAction, ShellAction
 from .tool_execution import (
+    build_litellm_json_tool_call,
     coerce_shell_call,
     execute_apply_patch_calls,
     execute_computer_actions,
@@ -1540,8 +1546,16 @@ async def rewind_model_request() -> None:
                     matched_tool = (
                         tool_map.get(tool_lookup_key) if tool_lookup_key is not None else None
                     )
+                    if (
+                        matched_tool is None
+                        and output_schema is not None
+                        and isinstance(output_item, ResponseFunctionToolCall)
+                        and output_item.name == "json_tool_call"
+                    ):
+                        matched_tool = build_litellm_json_tool_call(output_item)
                     tool_description: str | None = None
                     tool_title: str | None = None
+                    tool_origin = None
                     if isinstance(output_item, McpCall):
                         metadata = hosted_mcp_tool_metadata.get(
                             (output_item.server_label, output_item.name)
@@ -1552,12 +1566,14 @@ async def rewind_model_request() -> None:
                     elif matched_tool is not None:
                         tool_description = getattr(matched_tool, "description", None)
                         tool_title = getattr(matched_tool, "_mcp_title", None)
+                        tool_origin = get_function_tool_origin(matched_tool)
 
                     tool_item = ToolCallItem(
                         raw_item=cast(ToolCallItemTypes, output_item),
                         agent=public_agent,
                         description=tool_description,
                         title=tool_title,
+                        tool_origin=tool_origin,
                     )
                     streamed_result._event_queue.put_nowait(
                         RunItemStreamEvent(item=tool_item, name="tool_called")

src/agents/run_internal/tool_execution.py

@@ -71,6 +71,8 @@
     ShellCallOutcome,
     ShellCommandOutput,
     Tool,
+    ToolOrigin,
+    get_function_tool_origin,
     invoke_function_tool,
     maybe_invoke_function_tool_failure_error_function,
     resolve_computer,
@@ -1050,6 +1052,7 @@ async def on_invoke_tool(_ctx: ToolContext[Any], value: Any) -> Any:
         on_invoke_tool=on_invoke_tool,
         strict_json_schema=True,
         is_enabled=True,
+        _emit_tool_origin=False,
     )
 
 
@@ -1649,6 +1652,7 @@ async def _maybe_execute_tool_approval(
                 tool_call,
                 rejection_message=rejection_message,
                 scope_id=self.tool_state_scope_id,
+                tool_origin=get_function_tool_origin(func_tool),
             ),
         )
 
@@ -1844,6 +1848,7 @@ def _build_function_tool_results(self) -> list[FunctionToolResult]:
                     output=result,
                     raw_item=ItemHelpers.tool_call_output_item(tool_run.tool_call, result),
                     agent=self.public_agent,
+                    tool_origin=get_function_tool_origin(tool_run.function_tool),
                 )
             else:
                 # Skip tool output until nested interruptions are resolved.
@@ -2060,14 +2065,22 @@ async def execute_approved_tools(
             if isinstance(tool_name, str) and tool_name:
                 tool_map[tool_name] = tool
 
-    def _append_error(message: str, *, tool_call: Any, tool_name: str, call_id: str) -> None:
+    def _append_error(
+        message: str,
+        *,
+        tool_call: Any,
+        tool_name: str,
+        call_id: str,
+        tool_origin: ToolOrigin | None = None,
+    ) -> None:
         append_approval_error_output(
             message=message,
             tool_call=tool_call,
             tool_name=tool_name,
             call_id=call_id,
             generated_items=generated_items,
             agent=agent,
+            tool_origin=tool_origin,
         )
 
     async def _resolve_tool_run(
@@ -2095,14 +2108,25 @@ async def _resolve_tool_run(
 
         call_id = extract_tool_call_id(tool_call)
         if not call_id:
+            resolved_tool = tool_map.get(approval_key) if approval_key is not None else None
+            if resolved_tool is None and tool_namespace is None:
+                resolved_tool = tool_map.get(tool_name)
             _append_error(
                 message="Tool approval item missing call ID.",
                 tool_call=tool_call,
                 tool_name=tool_name,
                 call_id="unknown",
+                tool_origin=(
+                    get_function_tool_origin(resolved_tool)
+                    if isinstance(resolved_tool, FunctionTool)
+                    else None
+                ),
             )
             return None
 
+        resolved_tool = tool_map.get(approval_key) if approval_key is not None else None
+        if resolved_tool is None and tool_namespace is None:
+            resolved_tool = tool_map.get(tool_name)
         approval_status = context_wrapper.get_approval_status(
             tool_name,
             call_id,
@@ -2111,9 +2135,6 @@ async def _resolve_tool_run(
             tool_lookup_key=tool_lookup_key,
         )
         if approval_status is False:
-            resolved_tool = tool_map.get(approval_key) if approval_key is not None else None
-            if resolved_tool is None and tool_namespace is None:
-                resolved_tool = tool_map.get(tool_name)
             message = REJECTION_MESSAGE
             if isinstance(resolved_tool, FunctionTool):
                 message = await resolve_approval_rejection_message(
@@ -2131,6 +2152,11 @@ async def _resolve_tool_run(
                 tool_call=tool_call,
                 tool_name=tool_name,
                 call_id=call_id,
+                tool_origin=(
+                    get_function_tool_origin(resolved_tool)
+                    if isinstance(resolved_tool, FunctionTool)
+                    else None
+                ),
             )
             return None
 
@@ -2140,12 +2166,15 @@ async def _resolve_tool_run(
                 tool_call=tool_call,
                 tool_name=tool_name,
                 call_id=call_id,
+                tool_origin=(
+                    get_function_tool_origin(resolved_tool)
+                    if isinstance(resolved_tool, FunctionTool)
+                    else None
+                ),
             )
             return None
 
-        tool = tool_map.get(approval_key) if approval_key is not None else None
-        if tool is None and tool_namespace is None:
-            tool = tool_map.get(tool_name)
+        tool = resolved_tool
         if tool is None:
             _append_error(
                 message=f"Tool '{display_tool_name}' not found.",

src/agents/run_internal/turn_resolution.py

@@ -80,6 +80,7 @@
     LocalShellTool,
     ShellTool,
     Tool,
+    get_function_tool_origin,
 )
 from ..tool_guardrails import ToolInputGuardrailResult, ToolOutputGuardrailResult
 from ..tracing import SpanError, handoff_span
@@ -777,6 +778,7 @@ async def _record_function_rejection(
                 tool_call,
                 rejection_message=rejection_message,
                 scope_id=tool_state_scope_id,
+                tool_origin=get_function_tool_origin(function_tool),
             )
         )
         if isinstance(call_id, str):
@@ -1791,11 +1793,19 @@ def _dump_output_item(raw_item: Any) -> dict[str, Any]:
             func_tool = function_map.get(lookup_key) if lookup_key is not None else None
             if func_tool is None:
                 if output_schema is not None and output.name == "json_tool_call":
-                    items.append(ToolCallItem(raw_item=output, agent=agent))
+                    synthetic_tool = build_litellm_json_tool_call(output)
+                    items.append(
+                        ToolCallItem(
+                            raw_item=output,
+                            agent=agent,
+                            description=synthetic_tool.description,
+                            tool_origin=get_function_tool_origin(synthetic_tool),
+                        )
+                    )
                     functions.append(
                         ToolRunFunction(
                             tool_call=output,
-                            function_tool=build_litellm_json_tool_call(output),
+                            function_tool=synthetic_tool,
                         )
                     )
                     continue
@@ -1816,6 +1826,7 @@ def _dump_output_item(raw_item: Any) -> dict[str, Any]:
                     agent=agent,
                     description=func_tool.description,
                     title=func_tool._mcp_title,
+                    tool_origin=get_function_tool_origin(func_tool),
                 )
             )
             functions.append(