feat(items): add tool call convenience accessors

Author: MukundaKatta

src/agents/items.py

@@ -362,6 +362,28 @@ class ToolCallItem(RunItemBase[Any]):
     tool_origin: ToolOrigin | None = None
     """Optional metadata describing the source of a function-tool-backed item."""
 
+    @property
+    def tool_name(self) -> str | None:
+        """Return the tool name from the raw item when available."""
+        if isinstance(self.raw_item, dict):
+            candidate = self.raw_item.get("name") or self.raw_item.get("tool_name")
+        else:
+            candidate = getattr(self.raw_item, "name", None) or getattr(
+                self.raw_item, "tool_name", None
+            )
+        return str(candidate) if candidate is not None else None
+
+    @property
+    def call_id(self) -> str | None:
+        """Return the call identifier from the raw item when available."""
+        if isinstance(self.raw_item, dict):
+            candidate = self.raw_item.get("call_id") or self.raw_item.get("id")
+        else:
+            candidate = getattr(self.raw_item, "call_id", None) or getattr(
+                self.raw_item, "id", None
+            )
+        return str(candidate) if candidate is not None else None
+
 
 ToolCallOutputTypes: TypeAlias = (
     FunctionCallOutput
@@ -389,6 +411,17 @@ class ToolCallOutputItem(RunItemBase[Any]):
     tool_origin: ToolOrigin | None = None
     """Optional metadata describing the source of a function-tool-backed item."""
 
+    @property
+    def call_id(self) -> str | None:
+        """Return the call identifier from the raw item when available."""
+        if isinstance(self.raw_item, dict):
+            candidate = self.raw_item.get("call_id") or self.raw_item.get("id")
+        else:
+            candidate = getattr(self.raw_item, "call_id", None) or getattr(
+                self.raw_item, "id", None
+            )
+        return str(candidate) if candidate is not None else None
+
     def to_input_item(self) -> TResponseInputItem:
         """Converts the tool output into an input item for the next model turn.
 

tests/test_run_internal_items.py

@@ -15,6 +15,7 @@
 from agents.items import (
     ReasoningItem,
     ToolCallItem,
+    ToolCallOutputItem,
     ToolSearchCallItem,
     ToolSearchOutputItem,
     TResponseInputItem,
@@ -489,6 +490,52 @@ def test_run_item_to_input_item_omits_tool_call_metadata() -> None:
     assert "title" not in result_dict
 
 
+def test_tool_call_item_exposes_convenience_properties_for_typed_raw_items() -> None:
+    agent = Agent(name="A")
+    item = ToolCallItem(
+        agent=agent,
+        raw_item=ResponseFunctionToolCall(
+            id="fc_123",
+            call_id="call_123",
+            name="lookup_account",
+            arguments="{}",
+            type="function_call",
+            status="completed",
+        ),
+    )
+
+    assert item.tool_name == "lookup_account"
+    assert item.call_id == "call_123"
+
+
+def test_tool_call_item_exposes_convenience_properties_for_dict_raw_items() -> None:
+    agent = Agent(name="A")
+    item = ToolCallItem(
+        agent=agent,
+        raw_item={
+            "id": "fc_456",
+            "call_id": "call_456",
+            "name": "lookup_account",
+            "arguments": "{}",
+            "type": "function_call",
+        },
+    )
+
+    assert item.tool_name == "lookup_account"
+    assert item.call_id == "call_456"
+
+
+def test_tool_call_output_item_exposes_call_id_for_dict_raw_items() -> None:
+    agent = Agent(name="A")
+    item = ToolCallOutputItem(
+        agent=agent,
+        raw_item={"type": "function_call_output", "call_id": "call_456", "output": "ok"},
+        output="ok",
+    )
+
+    assert item.call_id == "call_456"
+
+
 def test_normalize_input_items_for_api_strips_internal_tool_call_metadata() -> None:
     item = cast(
         TResponseInputItem,