feat: add convenience properties (tool_name, call_id, arguments) to ToolCallItem and ToolCallOutputItem

ToolApprovalItem already exposes tool_name, call_id, and arguments 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

Author: DanielCufino

src/agents/items.py

@@ -358,6 +358,37 @@ 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)
+
+    @property
+    def arguments(self) -> str | None:
+        """Return the tool call arguments as a JSON string, if available."""
+        candidate: Any | None = None
+        if isinstance(self.raw_item, dict):
+            candidate = self.raw_item.get("arguments")
+        elif hasattr(self.raw_item, "arguments"):
+            candidate = self.raw_item.arguments
+        if candidate is None:
+            return None
+        if isinstance(candidate, str):
+            return candidate
+        try:
+            return json.dumps(candidate)
+        except (TypeError, ValueError):
+            return str(candidate)
+
 
 ToolCallOutputTypes: TypeAlias = Union[
     FunctionCallOutput,
@@ -382,6 +413,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.
 

tests/test_tool_call_item_properties.py

@@ -0,0 +1,63 @@
+"""Tests for convenience properties on ToolCallItem and ToolCallOutputItem."""
+
+from __future__ import annotations
+
+from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
+
+from agents import Agent
+from agents.items import ToolCallItem, ToolCallOutputItem
+
+
+def test_tool_call_item_properties_from_function_call() -> None:
+    raw = ResponseFunctionToolCall(
+        id="fc_1",
+        arguments='{"x": 1}',
+        call_id="call_1",
+        name="my_tool",
+        type="function_call",
+    )
+    item = ToolCallItem(agent=Agent(name="test"), raw_item=raw)
+
+    assert item.tool_name == "my_tool"
+    assert item.call_id == "call_1"
+    assert item.arguments == '{"x": 1}'
+
+
+def test_tool_call_item_properties_from_dict() -> None:
+    item = ToolCallItem(
+        agent=Agent(name="test"),
+        raw_item={"name": "search", "call_id": "c1", "arguments": '{"q": "hi"}'},
+    )
+    assert item.tool_name == "search"
+    assert item.call_id == "c1"
+    assert item.arguments == '{"q": "hi"}'
+
+
+def test_tool_call_item_call_id_falls_back_to_id() -> None:
+    item = ToolCallItem(agent=Agent(name="test"), raw_item={"id": "fallback"})
+    assert item.call_id == "fallback"
+
+
+def test_tool_call_item_returns_none_for_empty_raw_item() -> None:
+    item = ToolCallItem(agent=Agent(name="test"), raw_item={})
+    assert item.tool_name is None
+    assert item.call_id is None
+    assert item.arguments is None
+
+
+def test_tool_call_output_item_call_id_from_dict() -> None:
+    item = ToolCallOutputItem(
+        agent=Agent(name="test"),
+        raw_item={"type": "function_call_output", "call_id": "call_xyz", "output": "ok"},
+        output="ok",
+    )
+    assert item.call_id == "call_xyz"
+
+
+def test_tool_call_output_item_call_id_returns_none_when_missing() -> None:
+    item = ToolCallOutputItem(
+        agent=Agent(name="test"),
+        raw_item={"type": "function_call_output", "output": "ok"},
+        output="ok",
+    )
+    assert item.call_id is None