openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/handoffs/history.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, cast
+
+from ..items import (
+    ItemHelpers,
+    RunItem,
+    TResponseInputItem,
+)
+
+if TYPE_CHECKING:
+    from . import HandoffHistoryMapper, HandoffInputData
+
+__all__ = [
+    "default_handoff_history_mapper",
+    "get_conversation_history_wrappers",
+    "nest_handoff_history",
+    "reset_conversation_history_wrappers",
+    "set_conversation_history_wrappers",
+]
+
+_DEFAULT_CONVERSATION_HISTORY_START = "<CONVERSATION HISTORY>"
+_DEFAULT_CONVERSATION_HISTORY_END = "</CONVERSATION HISTORY>"
+_conversation_history_start = _DEFAULT_CONVERSATION_HISTORY_START
+_conversation_history_end = _DEFAULT_CONVERSATION_HISTORY_END
+
+# Item types that are summarized in the conversation history.
+# They should not be forwarded verbatim to the next agent to avoid duplication.
+_SUMMARY_ONLY_INPUT_TYPES = {
+    "function_call",
+    "function_call_output",
+}
+
+
+def set_conversation_history_wrappers(
+    *,
+    start: str | None = None,
+    end: str | None = None,
+) -> None:
+    """Override the markers that wrap the generated conversation summary.
+
+    Pass ``None`` to leave either side unchanged.
+    """
+
+    global _conversation_history_start, _conversation_history_end
+    if start is not None:
+        _conversation_history_start = start
+    if end is not None:
+        _conversation_history_end = end
+
+
+def reset_conversation_history_wrappers() -> None:
+    """Restore the default ``<CONVERSATION HISTORY>`` markers."""
+
+    global _conversation_history_start, _conversation_history_end
+    _conversation_history_start = _DEFAULT_CONVERSATION_HISTORY_START
+    _conversation_history_end = _DEFAULT_CONVERSATION_HISTORY_END
+
+
+def get_conversation_history_wrappers() -> tuple[str, str]:
+    """Return the current start/end markers used for the nested conversation summary."""
+
+    return (_conversation_history_start, _conversation_history_end)
+
+
+def nest_handoff_history(
+    handoff_input_data: HandoffInputData,
+    *,
+    history_mapper: HandoffHistoryMapper | None = None,
+) -> HandoffInputData:
+    """Summarize the previous transcript for the next agent."""
+
+    normalized_history = _normalize_input_history(handoff_input_data.input_history)
+    flattened_history = _flatten_nested_history_messages(normalized_history)
+
+    # Convert items to plain inputs for the transcript summary.
+    pre_items_as_inputs: list[TResponseInputItem] = []
+    filtered_pre_items: list[RunItem] = []
+    for run_item in handoff_input_data.pre_handoff_items:
+        plain_input = _run_item_to_plain_input(run_item)
+        pre_items_as_inputs.append(plain_input)
+        if _should_forward_pre_item(plain_input):
+            filtered_pre_items.append(run_item)
+
+    new_items_as_inputs: list[TResponseInputItem] = []
+    filtered_input_items: list[RunItem] = []
+    for run_item in handoff_input_data.new_items:
+        plain_input = _run_item_to_plain_input(run_item)
+        new_items_as_inputs.append(plain_input)
+        if _should_forward_new_item(plain_input):
+            filtered_input_items.append(run_item)
+
+    transcript = flattened_history + pre_items_as_inputs + new_items_as_inputs
+
+    mapper = history_mapper or default_handoff_history_mapper
+    history_items = mapper(transcript)
+
+    return handoff_input_data.clone(
+        input_history=tuple(deepcopy(item) for item in history_items),
+        pre_handoff_items=tuple(filtered_pre_items),
+        # new_items stays unchanged for session history.
+        input_items=tuple(filtered_input_items),
+    )
+
+
+def default_handoff_history_mapper(
+    transcript: list[TResponseInputItem],
+) -> list[TResponseInputItem]:
+    """Return a single assistant message summarizing the transcript."""
+
+    summary_message = _build_summary_message(transcript)
+    return [summary_message]
+
+
+def _normalize_input_history(
+    input_history: str | tuple[TResponseInputItem, ...],
+) -> list[TResponseInputItem]:
+    if isinstance(input_history, str):
+        return ItemHelpers.input_to_new_input_list(input_history)
+    return [deepcopy(item) for item in input_history]
+
+
+def _run_item_to_plain_input(run_item: RunItem) -> TResponseInputItem:
+    return deepcopy(run_item.to_input_item())
+
+
+def _build_summary_message(transcript: list[TResponseInputItem]) -> TResponseInputItem:
+    transcript_copy = [deepcopy(item) for item in transcript]
+    if transcript_copy:
+        summary_lines = [
+            f"{idx + 1}. {_format_transcript_item(item)}"
+            for idx, item in enumerate(transcript_copy)
+        ]
+    else:
+        summary_lines = ["(no previous turns recorded)"]
+
+    start_marker, end_marker = get_conversation_history_wrappers()
+    content_lines = [
+        "For context, here is the conversation so far between the user and the previous agent:",
+        start_marker,
+        *summary_lines,
+        end_marker,
+    ]
+    content = "\n".join(content_lines)
+    assistant_message: dict[str, Any] = {
+        "role": "assistant",
+        "content": content,
+    }
+    return cast(TResponseInputItem, assistant_message)
+
+
+def _format_transcript_item(item: TResponseInputItem) -> str:
+    role = item.get("role")
+    if isinstance(role, str):
+        prefix = role
+        name = item.get("name")
+        if isinstance(name, str) and name:
+            prefix = f"{prefix} ({name})"
+        content_str = _stringify_content(item.get("content"))
+        return f"{prefix}: {content_str}" if content_str else prefix
+
+    item_type = item.get("type", "item")
+    rest = {k: v for k, v in item.items() if k not in ("type", "provider_data")}
+    try:
+        serialized = json.dumps(rest, ensure_ascii=False, default=str)
+    except TypeError:
+        serialized = str(rest)
+    return f"{item_type}: {serialized}" if serialized else str(item_type)
+
+
+def _stringify_content(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    try:
+        return json.dumps(content, ensure_ascii=False, default=str)
+    except TypeError:
+        return str(content)
+
+
+def _flatten_nested_history_messages(
+    items: list[TResponseInputItem],
+) -> list[TResponseInputItem]:
+    flattened: list[TResponseInputItem] = []
+    for item in items:
+        nested_transcript = _extract_nested_history_transcript(item)
+        if nested_transcript is not None:
+            flattened.extend(nested_transcript)
+            continue
+        flattened.append(deepcopy(item))
+    return flattened
+
+
+def _extract_nested_history_transcript(
+    item: TResponseInputItem,
+) -> list[TResponseInputItem] | None:
+    content = item.get("content")
+    if not isinstance(content, str):
+        return None
+    start_marker, end_marker = get_conversation_history_wrappers()
+    start_idx = content.find(start_marker)
+    end_idx = content.find(end_marker)
+    if start_idx == -1 or end_idx == -1 or end_idx <= start_idx:
+        return None
+    start_idx += len(start_marker)
+    body = content[start_idx:end_idx]
+    lines = [line.strip() for line in body.splitlines() if line.strip()]
+    parsed: list[TResponseInputItem] = []
+    for line in lines:
+        parsed_item = _parse_summary_line(line)
+        if parsed_item is not None:
+            parsed.append(parsed_item)
+    return parsed
+
+
+def _parse_summary_line(line: str) -> TResponseInputItem | None:
+    stripped = line.strip()
+    if not stripped:
+        return None
+    dot_index = stripped.find(".")
+    if dot_index != -1 and stripped[:dot_index].isdigit():
+        stripped = stripped[dot_index + 1 :].lstrip()
+    role_part, sep, remainder = stripped.partition(":")
+    if not sep:
+        return None
+    role_text = role_part.strip()
+    if not role_text:
+        return None
+    role, name = _split_role_and_name(role_text)
+    reconstructed: dict[str, Any] = {"role": role}
+    if name:
+        reconstructed["name"] = name
+    content = remainder.strip()
+    if content:
+        reconstructed["content"] = content
+    return cast(TResponseInputItem, reconstructed)
+
+
+def _split_role_and_name(role_text: str) -> tuple[str, str | None]:
+    if role_text.endswith(")") and "(" in role_text:
+        open_idx = role_text.rfind("(")
+        possible_name = role_text[open_idx + 1 : -1].strip()
+        role_candidate = role_text[:open_idx].strip()
+        if possible_name:
+            return (role_candidate or "developer", possible_name)
+    return (role_text or "developer", None)
+
+
+def _should_forward_pre_item(input_item: TResponseInputItem) -> bool:
+    """Return False when the previous transcript item is represented in the summary."""
+    role_candidate = input_item.get("role")
+    if isinstance(role_candidate, str) and role_candidate == "assistant":
+        return False
+    type_candidate = input_item.get("type")
+    return not (isinstance(type_candidate, str) and type_candidate in _SUMMARY_ONLY_INPUT_TYPES)
+
+
+def _should_forward_new_item(input_item: TResponseInputItem) -> bool:
+    """Return False for tool or side-effect items that the summary already covers."""
+    # Items with a role should always be forwarded.
+    role_candidate = input_item.get("role")
+    if isinstance(role_candidate, str) and role_candidate:
+        return True
+    type_candidate = input_item.get("type")
+    return not (isinstance(type_candidate, str) and type_candidate in _SUMMARY_ONLY_INPUT_TYPES)

agents/items.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import abc
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union
+import weakref
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union, cast
 
 import pydantic
 from openai.types.responses import (
@@ -21,6 +22,12 @@ from openai.types.responses import (
 from openai.types.responses.response_code_interpreter_tool_call import (
     ResponseCodeInterpreterToolCall,
 )
+from openai.types.responses.response_function_call_output_item_list_param import (
+    ResponseFunctionCallOutputItemListParam,
+    ResponseFunctionCallOutputItemParam,
+)
+from openai.types.responses.response_input_file_content_param import ResponseInputFileContentParam
+from openai.types.responses.response_input_image_content_param import ResponseInputImageContentParam
 from openai.types.responses.response_input_item_param import (
     ComputerCallOutput,
     FunctionCallOutput,
@@ -36,9 +43,17 @@ from openai.types.responses.response_output_item import (
 )
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 from pydantic import BaseModel
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, assert_never
 
 from .exceptions import AgentsException, ModelBehaviorError
+from .logger import logger
+from .tool import (
+    ToolOutputFileContent,
+    ToolOutputImage,
+    ToolOutputText,
+    ValidToolOutputPydanticModels,
+    ValidToolOutputPydanticModelsTypeAdapter,
+)
 from .usage import Usage
 
 if TYPE_CHECKING:
@@ -58,6 +73,9 @@ TResponseStreamEvent = ResponseStreamEvent
 
 T = TypeVar("T", bound=Union[TResponseOutputItem, TResponseInputItem])
 
+# Distinguish a missing dict entry from an explicit None value.
+_MISSING_ATTR_SENTINEL = object()
+
 
 @dataclass
 class RunItemBase(Generic[T], abc.ABC):
@@ -70,6 +88,49 @@ class RunItemBase(Generic[T], abc.ABC):
     (i.e. `openai.types.responses.ResponseInputItemParam`).
     """
 
+    _agent_ref: weakref.ReferenceType[Agent[Any]] | None = field(
+        init=False,
+        repr=False,
+        default=None,
+    )
+
+    def __post_init__(self) -> None:
+        # Store a weak reference so we can release the strong reference later if desired.
+        self._agent_ref = weakref.ref(self.agent)
+
+    def __getattribute__(self, name: str) -> Any:
+        if name == "agent":
+            return self._get_agent_via_weakref("agent", "_agent_ref")
+        return super().__getattribute__(name)
+
+    def release_agent(self) -> None:
+        """Release the strong reference to the agent while keeping a weak reference."""
+        if "agent" not in self.__dict__:
+            return
+        agent = self.__dict__["agent"]
+        if agent is None:
+            return
+        self._agent_ref = weakref.ref(agent) if agent is not None else None
+        # Set to None instead of deleting so dataclass repr/asdict keep working.
+        self.__dict__["agent"] = None
+
+    def _get_agent_via_weakref(self, attr_name: str, ref_name: str) -> Any:
+        # Preserve the dataclass field so repr/asdict still read it, but lazily resolve the weakref
+        # when the stored value is None (meaning release_agent already dropped the strong ref).
+        # If the attribute was never overridden we fall back to the default descriptor chain.
+        data = object.__getattribute__(self, "__dict__")
+        value = data.get(attr_name, _MISSING_ATTR_SENTINEL)
+        if value is _MISSING_ATTR_SENTINEL:
+            return object.__getattribute__(self, attr_name)
+        if value is not None:
+            return value
+        ref = object.__getattribute__(self, ref_name)
+        if ref is not None:
+            agent = ref()
+            if agent is not None:
+                return agent
+        return None
+
     def to_input_item(self) -> TResponseInputItem:
         """Converts this item into an input item suitable for passing to the model."""
         if isinstance(self.raw_item, dict):
@@ -117,6 +178,48 @@ class HandoffOutputItem(RunItemBase[TResponseInputItem]):
 
     type: Literal["handoff_output_item"] = "handoff_output_item"
 
+    _source_agent_ref: weakref.ReferenceType[Agent[Any]] | None = field(
+        init=False,
+        repr=False,
+        default=None,
+    )
+    _target_agent_ref: weakref.ReferenceType[Agent[Any]] | None = field(
+        init=False,
+        repr=False,
+        default=None,
+    )
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        # Maintain weak references so downstream code can release the strong references when safe.
+        self._source_agent_ref = weakref.ref(self.source_agent)
+        self._target_agent_ref = weakref.ref(self.target_agent)
+
+    def __getattribute__(self, name: str) -> Any:
+        if name == "source_agent":
+            # Provide lazy weakref access like the base `agent` field so HandoffOutputItem
+            # callers keep seeing the original agent until GC occurs.
+            return self._get_agent_via_weakref("source_agent", "_source_agent_ref")
+        if name == "target_agent":
+            # Same as above but for the target of the handoff.
+            return self._get_agent_via_weakref("target_agent", "_target_agent_ref")
+        return super().__getattribute__(name)
+
+    def release_agent(self) -> None:
+        super().release_agent()
+        if "source_agent" in self.__dict__:
+            source_agent = self.__dict__["source_agent"]
+            if source_agent is not None:
+                self._source_agent_ref = weakref.ref(source_agent)
+            # Preserve dataclass fields for repr/asdict while dropping strong refs.
+            self.__dict__["source_agent"] = None
+        if "target_agent" in self.__dict__:
+            target_agent = self.__dict__["target_agent"]
+            if target_agent is not None:
+                self._target_agent_ref = weakref.ref(target_agent)
+            # Preserve dataclass fields for repr/asdict while dropping strong refs.
+            self.__dict__["target_agent"] = None
+
 
 ToolCallItemTypes: TypeAlias = Union[
     ResponseFunctionToolCall,
@@ -127,12 +230,13 @@ ToolCallItemTypes: TypeAlias = Union[
     ResponseCodeInterpreterToolCall,
     ImageGenerationCall,
     LocalShellCall,
+    dict[str, Any],
 ]
 """A type that represents a tool call item."""
 
 
 @dataclass
-class ToolCallItem(RunItemBase[ToolCallItemTypes]):
+class ToolCallItem(RunItemBase[Any]):
     """Represents a tool call e.g. a function call or computer action call."""
 
     raw_item: ToolCallItemTypes
@@ -141,13 +245,19 @@ class ToolCallItem(RunItemBase[ToolCallItemTypes]):
     type: Literal["tool_call_item"] = "tool_call_item"
 
 
+ToolCallOutputTypes: TypeAlias = Union[
+    FunctionCallOutput,
+    ComputerCallOutput,
+    LocalShellCallOutput,
+    dict[str, Any],
+]
+
+
 @dataclass
-class ToolCallOutputItem(
-    RunItemBase[Union[FunctionCallOutput, ComputerCallOutput, LocalShellCallOutput]]
-):
+class ToolCallOutputItem(RunItemBase[Any]):
     """Represents the output of a tool call."""
 
-    raw_item: FunctionCallOutput | ComputerCallOutput | LocalShellCallOutput
+    raw_item: ToolCallOutputTypes
     """The raw item from the model."""
 
     output: Any
@@ -157,6 +267,25 @@ class ToolCallOutputItem(
 
     type: Literal["tool_call_output_item"] = "tool_call_output_item"
 
+    def to_input_item(self) -> TResponseInputItem:
+        """Converts the tool output into an input item for the next model turn.
+
+        Hosted tool outputs (e.g. shell/apply_patch) carry a `status` field for the SDK's
+        book-keeping, but the Responses API does not yet accept that parameter. Strip it from the
+        payload we send back to the model while keeping the original raw item intact.
+        """
+
+        if isinstance(self.raw_item, dict):
+            payload = dict(self.raw_item)
+            payload_type = payload.get("type")
+            if payload_type == "shell_call_output":
+                payload.pop("status", None)
+                payload.pop("shell_output", None)
+                payload.pop("provider_data", None)
+            return cast(TResponseInputItem, payload)
+
+        return super().to_input_item()
+
 
 @dataclass
 class ReasoningItem(RunItemBase[ResponseReasoningItem]):
@@ -198,6 +327,17 @@ class MCPApprovalResponseItem(RunItemBase[McpApprovalResponse]):
     type: Literal["mcp_approval_response_item"] = "mcp_approval_response_item"
 
 
+@dataclass
+class CompactionItem(RunItemBase[TResponseInputItem]):
+    """Represents a compaction item from responses.compact."""
+
+    type: Literal["compaction_item"] = "compaction_item"
+
+    def to_input_item(self) -> TResponseInputItem:
+        """Converts this item into an input item suitable for passing to the model."""
+        return self.raw_item
+
+
 RunItem: TypeAlias = Union[
     MessageOutputItem,
     HandoffCallItem,
@@ -208,6 +348,7 @@ RunItem: TypeAlias = Union[
     MCPListToolsItem,
     MCPApprovalRequestItem,
     MCPApprovalResponseItem,
+    CompactionItem,
 ]
 """An item generated by an agent."""
 
@@ -298,11 +439,96 @@ class ItemHelpers:
 
     @classmethod
     def tool_call_output_item(
-        cls, tool_call: ResponseFunctionToolCall, output: str
+        cls, tool_call: ResponseFunctionToolCall, output: Any
     ) -> FunctionCallOutput:
-        """Creates a tool call output item from a tool call and its output."""
+        """Creates a tool call output item from a tool call and its output.
+
+        Accepts either plain values (stringified) or structured outputs using
+        input_text/input_image/input_file shapes. Structured outputs may be
+        provided as Pydantic models or dicts, or an iterable of such items.
+        """
+
+        converted_output = cls._convert_tool_output(output)
+
         return {
             "call_id": tool_call.call_id,
-            "output": output,
+            "output": converted_output,
             "type": "function_call_output",
         }
+
+    @classmethod
+    def _convert_tool_output(cls, output: Any) -> str | ResponseFunctionCallOutputItemListParam:
+        """Converts a tool return value into an output acceptable by the Responses API."""
+
+        # If the output is either a single or list of the known structured output types, convert to
+        # ResponseFunctionCallOutputItemListParam. Else, just stringify.
+        if isinstance(output, (list, tuple)):
+            maybe_converted_output_list = [
+                cls._maybe_get_output_as_structured_function_output(item) for item in output
+            ]
+            if all(maybe_converted_output_list):
+                return [
+                    cls._convert_single_tool_output_pydantic_model(item)
+                    for item in maybe_converted_output_list
+                    if item is not None
+                ]
+            else:
+                return str(output)
+        else:
+            maybe_converted_output = cls._maybe_get_output_as_structured_function_output(output)
+            if maybe_converted_output:
+                return [cls._convert_single_tool_output_pydantic_model(maybe_converted_output)]
+            else:
+                return str(output)
+
+    @classmethod
+    def _maybe_get_output_as_structured_function_output(
+        cls, output: Any
+    ) -> ValidToolOutputPydanticModels | None:
+        if isinstance(output, (ToolOutputText, ToolOutputImage, ToolOutputFileContent)):
+            return output
+        elif isinstance(output, dict):
+            # Require explicit 'type' field in dict to be considered a structured output
+            if "type" not in output:
+                return None
+            try:
+                return ValidToolOutputPydanticModelsTypeAdapter.validate_python(output)
+            except pydantic.ValidationError:
+                logger.debug("dict was not a valid tool output pydantic model")
+                return None
+
+        return None
+
+    @classmethod
+    def _convert_single_tool_output_pydantic_model(
+        cls, output: ValidToolOutputPydanticModels
+    ) -> ResponseFunctionCallOutputItemParam:
+        if isinstance(output, ToolOutputText):
+            return {"type": "input_text", "text": output.text}
+        elif isinstance(output, ToolOutputImage):
+            # Forward all provided optional fields so the Responses API receives
+            # the correct identifiers and settings for the image resource.
+            result: ResponseInputImageContentParam = {"type": "input_image"}
+            if output.image_url is not None:
+                result["image_url"] = output.image_url
+            if output.file_id is not None:
+                result["file_id"] = output.file_id
+            if output.detail is not None:
+                result["detail"] = output.detail
+            return result
+        elif isinstance(output, ToolOutputFileContent):
+            # Forward all provided optional fields so the Responses API receives
+            # the correct identifiers and metadata for the file resource.
+            result_file: ResponseInputFileContentParam = {"type": "input_file"}
+            if output.file_data is not None:
+                result_file["file_data"] = output.file_data
+            if output.file_url is not None:
+                result_file["file_url"] = output.file_url
+            if output.file_id is not None:
+                result_file["file_id"] = output.file_id
+            if output.filename is not None:
+                result_file["filename"] = output.filename
+            return result_file
+        else:
+            assert_never(output)
+            raise ValueError(f"Unexpected tool output type: {output}")