feat: #2228 persist tool origin metadata in run items (#2654)

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.
 
@@ -489,6 +496,9 @@ class ToolApprovalItem(RunItemBase[Any]):
     tool_namespace: str | None = None
     """Optional Responses API namespace for function-tool approvals."""
 
+    tool_origin: ToolOrigin | None = None
+    """Optional metadata describing where the approved tool call came from."""
+
     tool_lookup_key: FunctionToolLookupKey | None = field(
         default=None,
         kw_only=True,

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,14 @@
     RawResponsesStreamEvent,
     RunItemStreamEvent,
 )
-from ..tool import FunctionTool, Tool, dispose_resolved_computers
+from ..tool import (
+    FunctionTool,
+    Tool,
+    ToolOrigin,
+    ToolOriginType,
+    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 +150,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,24 +1553,38 @@ 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)
                         )
                         if metadata is not None:
                             tool_description = metadata.description
                             tool_title = metadata.title
+                        tool_origin = ToolOrigin(
+                            type=ToolOriginType.MCP,
+                            mcp_server_name=output_item.server_label,
+                        )
                     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,
     )
 
 
@@ -1062,6 +1065,7 @@ async def resolve_approval_status(
     context_wrapper: RunContextWrapper[Any],
     tool_namespace: str | None = None,
     tool_lookup_key: FunctionToolLookupKey | None = None,
+    tool_origin: ToolOrigin | None = None,
     on_approval: Callable[[RunContextWrapper[Any], ToolApprovalItem], Any] | None = None,
 ) -> tuple[bool | None, ToolApprovalItem]:
     """Build approval item, run on_approval hook if needed, and return latest approval status."""
@@ -1070,6 +1074,7 @@ async def resolve_approval_status(
         raw_item=raw_item,
         tool_name=tool_name,
         tool_namespace=tool_namespace,
+        tool_origin=tool_origin,
         tool_lookup_key=tool_lookup_key,
     )
     approval_status = context_wrapper.get_approval_status(
@@ -1609,6 +1614,7 @@ async def _maybe_execute_tool_approval(
                 raw_item=raw_tool_call,
                 tool_name=func_tool.name,
                 tool_namespace=tool_namespace,
+                tool_origin=get_function_tool_origin(func_tool),
                 tool_lookup_key=tool_lookup_key,
                 _allow_bare_name_alias=should_allow_bare_name_approval_alias(
                     func_tool,
@@ -1649,6 +1655,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 +1851,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 +2068,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 +2111,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 +2138,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 +2155,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 +2169,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/tool_planning.py

@@ -22,7 +22,7 @@
     ToolCallOutputItem,
 )
 from ..run_context import RunContextWrapper
-from ..tool import FunctionTool, MCPToolApprovalRequest
+from ..tool import FunctionTool, MCPToolApprovalRequest, get_function_tool_origin
 from ..tool_guardrails import ToolInputGuardrailResult, ToolOutputGuardrailResult
 from .agent_bindings import AgentBindings
 from .run_steps import (
@@ -427,11 +427,17 @@ async def _collect_runs_by_approval(
         if approval_status is True:
             approved_runs.append(run)
         else:
+            function_tool = get_mapping_or_attr(run, "function_tool")
             pending_item = existing_pending or ToolApprovalItem(
                 agent=agent,
                 raw_item=get_mapping_or_attr(run, "tool_call"),
                 tool_name=tool_name,
                 tool_namespace=get_tool_call_namespace(get_mapping_or_attr(run, "tool_call")),
+                tool_origin=(
+                    get_function_tool_origin(function_tool)
+                    if isinstance(function_tool, FunctionTool)
+                    else None
+                ),
                 tool_lookup_key=get_function_tool_lookup_key_for_call(
                     get_mapping_or_attr(run, "tool_call")
                 ),