From 59c9174270405948a7074b7ce8bf266b8c519230 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Cufi=C3=B1o?= <dancufino@gmail.com>
Date: Wed, 15 Apr 2026 10:45:22 -0400
Subject: [PATCH] feat: add convenience properties (tool_name, call_id) to
 ToolCallItem and ToolCallOutputItem

ToolApprovalItem already exposes tool_name and call_id as properties,
but ToolCallItem and ToolCallOutputItem require users to reach into
raw_item internals. This adds the same convenience accessors to both
classes, following the existing ToolApprovalItem patterns.

Closes #2886
---
 src/agents/items.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/agents/items.py b/src/agents/items.py
index 9d6219f37d..349a21404f 100644
--- a/src/agents/items.py
+++ b/src/agents/items.py
@@ -358,6 +358,20 @@ class ToolCallItem(RunItemBase[Any]):
     title: str | None = None
     """Optional short display label if known at item creation time."""
 
+    @property
+    def tool_name(self) -> str | None:
+        """Return the tool name from the raw item, if available."""
+        if isinstance(self.raw_item, dict):
+            return self.raw_item.get("name")
+        return getattr(self.raw_item, "name", None)
+
+    @property
+    def call_id(self) -> str | None:
+        """Return the call identifier from the raw item, if available."""
+        if isinstance(self.raw_item, dict):
+            return self.raw_item.get("call_id") or self.raw_item.get("id")
+        return getattr(self.raw_item, "call_id", None) or getattr(self.raw_item, "id", None)
+
 
 ToolCallOutputTypes: TypeAlias = Union[
     FunctionCallOutput,
@@ -382,6 +396,14 @@ class ToolCallOutputItem(RunItemBase[Any]):
 
     type: Literal["tool_call_output_item"] = "tool_call_output_item"
 
+    @property
+    def call_id(self) -> str | None:
+        """Return the call identifier from the raw item, if available."""
+        if isinstance(self.raw_item, dict):
+            cid = self.raw_item.get("call_id") or self.raw_item.get("id")
+            return str(cid) if cid is not None else None
+        return getattr(self.raw_item, "call_id", None) or getattr(self.raw_item, "id", None)
+
     def to_input_item(self) -> TResponseInputItem:
         """Converts the tool output into an input item for the next model turn.