fixes

Author: jhills20

docs/handoffs.md

@@ -82,7 +82,7 @@ handoff_obj = handoff(
 
 When a handoff occurs, it's as though the new agent takes over the conversation, and gets to see the entire previous conversation history. If you want to change this, you can set an [`input_filter`][agents.handoffs.Handoff.input_filter]. An input filter is a function that receives the existing input via a [`HandoffInputData`][agents.handoffs.HandoffInputData], and must return a new `HandoffInputData`.
 
-By default the runner now collapses the prior transcript into a single assistant summary message (see [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]). The summary appears inside a `<CONVERSATION HISTORY>` block that keeps appending new turns when multiple handoffs happen during the same run. You can provide your own mapping function via [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] to replace the generated message without writing a full `input_filter`. That default only applies when neither the handoff nor the run supplies an explicit `input_filter`, so existing code that already customizes the payload (including the examples in this repository) keeps its current behavior without changes.
+By default the runner now collapses the prior transcript into a single assistant summary message (see [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]). The summary appears inside a `<CONVERSATION HISTORY>` block that keeps appending new turns when multiple handoffs happen during the same run. You can provide your own mapping function via [`RunConfig.handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper] to replace the generated message without writing a full `input_filter`. That default only applies when neither the handoff nor the run supplies an explicit `input_filter`, so existing code that already customizes the payload (including the examples in this repository) keeps its current behavior without changes. You can override the nesting behaviour for a single handoff by passing `nest_handoff_history=True` or `False` to [`handoff(...)`][agents.handoffs.handoff], which sets [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history]. If you just need to change the wrapper text for the generated summary, call [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (and optionally [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers]) before running your agents.
 
 There are some common patterns (for example removing all tool calls from the history), which are implemented for you in [`agents.extensions.handoff_filters`][]
 

docs/running_agents.md

@@ -51,14 +51,14 @@ The `run_config` parameter lets you configure some global settings for the agent
 -   [`model_settings`][agents.run.RunConfig.model_settings]: Overrides agent-specific settings. For example, you can set a global `temperature` or `top_p`.
 -   [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: A list of input or output guardrails to include on all runs.
 -   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: A global input filter to apply to all handoffs, if the handoff doesn't already have one. The input filter allows you to edit the inputs that are sent to the new agent. See the documentation in [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] for more details.
--   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: When `True` (the default) the runner collapses the prior transcript into a single assistant message before invoking the next agent. The helper places the content inside a `<CONVERSATION HISTORY>` block that keeps appending new turns as subsequent handoffs occur. Set this to `False` or provide a custom handoff filter if you prefer to pass through the raw transcript. All [`Runner` methods](agents.run.Runner) automatically create a `RunConfig` when you do not pass one, so the quickstarts and examples pick up this default automatically, and any explicit [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] callbacks continue to override it.
+-   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: When `True` (the default) the runner collapses the prior transcript into a single assistant message before invoking the next agent. The helper places the content inside a `<CONVERSATION HISTORY>` block that keeps appending new turns as subsequent handoffs occur. Set this to `False` or provide a custom handoff filter if you prefer to pass through the raw transcript. All [`Runner` methods](agents.run.Runner) automatically create a `RunConfig` when you do not pass one, so the quickstarts and examples pick up this default automatically, and any explicit [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] callbacks continue to override it. Individual handoffs can override this setting via [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history].
 -   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: Optional callable that receives the normalized transcript (history + handoff items) whenever `nest_handoff_history` is `True`. It must return the exact list of input items to forward to the next agent, allowing you to replace the built-in summary without writing a full handoff filter.
 -   [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: Allows you to disable [tracing](tracing.md) for the entire run.
 -   [`trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]: Configures whether traces will include potentially sensitive data, such as LLM and tool call inputs/outputs.
 -   [`workflow_name`][agents.run.RunConfig.workflow_name], [`trace_id`][agents.run.RunConfig.trace_id], [`group_id`][agents.run.RunConfig.group_id]: Sets the tracing workflow name, trace ID and trace group ID for the run. We recommend at least setting `workflow_name`. The group ID is an optional field that lets you link traces across multiple runs.
 -   [`trace_metadata`][agents.run.RunConfig.trace_metadata]: Metadata to include on all traces.
 
-By default, the SDK now nests prior turns inside a single assistant summary message whenever an agent hands off to another agent. This reduces repeated assistant messages and keeps the full transcript inside a single block that new agents can scan quickly. If you'd like to return to the legacy behavior, pass `RunConfig(nest_handoff_history=False)` or supply a `handoff_input_filter` (or `handoff_history_mapper`) that forwards the conversation exactly as you need.
+By default, the SDK now nests prior turns inside a single assistant summary message whenever an agent hands off to another agent. This reduces repeated assistant messages and keeps the full transcript inside a single block that new agents can scan quickly. If you'd like to return to the legacy behavior, pass `RunConfig(nest_handoff_history=False)` or supply a `handoff_input_filter` (or `handoff_history_mapper`) that forwards the conversation exactly as you need. You can also opt out (or in) for a specific handoff by setting `handoff(..., nest_handoff_history=False)` or `True`. To change the wrapper text used in the generated summary without writing a custom mapper, call [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (and [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] to restore the defaults).
 
 ## Conversations/chat threads
 
@@ -204,4 +204,4 @@ The SDK raises exceptions in certain cases. The full list is in [`agents.excepti
     -   Malformed JSON: When the model provides a malformed JSON structure for tool calls or in its direct output, especially if a specific `output_type` is defined.
     -   Unexpected tool-related failures: When the model fails to use tools in an expected manner
 -   [`UserError`][agents.exceptions.UserError]: This exception is raised when you (the person writing code using the SDK) make an error while using the SDK. This typically results from incorrect code implementation, invalid configuration, or misuse of the SDK's API.
--   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: This exception is raised when the conditions of an input guardrail or output guardrail are met, respectively. Input guardrails check incoming messages before processing, while output guardrails check the agent's final response before delivery.
+-   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: This exception is raised when the conditions of an input guardrail or output guardrail are met, respectively. Input guardrails check incoming messages before processing, while output guardrails check the agent's final response before delivery.

src/agents/__init__.py

@@ -34,7 +34,17 @@
     input_guardrail,
     output_guardrail,
 )
-from .handoffs import Handoff, HandoffInputData, HandoffInputFilter, handoff
+from .handoffs import (
+    Handoff,
+    HandoffInputData,
+    HandoffInputFilter,
+    default_handoff_history_mapper,
+    get_conversation_history_wrappers,
+    handoff,
+    nest_handoff_history,
+    reset_conversation_history_wrappers,
+    set_conversation_history_wrappers,
+)
 from .items import (
     HandoffCallItem,
     HandoffOutputItem,
@@ -191,6 +201,11 @@ def enable_verbose_stdout_logging():
     "StopAtTools",
     "ToolsToFinalOutputFunction",
     "ToolsToFinalOutputResult",
+    "default_handoff_history_mapper",
+    "get_conversation_history_wrappers",
+    "nest_handoff_history",
+    "reset_conversation_history_wrappers",
+    "set_conversation_history_wrappers",
     "Runner",
     "run_demo_loop",
     "Model",

src/agents/_run_impl.py

@@ -51,9 +51,8 @@
     ToolOutputGuardrailTripwireTriggered,
     UserError,
 )
-from .extensions.handoff_filters import nest_handoff_history
 from .guardrail import InputGuardrail, InputGuardrailResult, OutputGuardrail, OutputGuardrailResult
-from .handoffs import Handoff, HandoffInputData
+from .handoffs import Handoff, HandoffInputData, nest_handoff_history
 from .items import (
     HandoffCallItem,
     HandoffOutputItem,
@@ -999,8 +998,14 @@ async def execute_handoffs(
             input_filter = handoff.input_filter or (
                 run_config.handoff_input_filter if run_config else None
             )
+            handoff_nest_setting = handoff.nest_handoff_history
+            should_nest_history = (
+                handoff_nest_setting
+                if handoff_nest_setting is not None
+                else run_config.nest_handoff_history
+            )
             handoff_input_data: HandoffInputData | None = None
-            if input_filter or run_config.nest_handoff_history:
+            if input_filter or should_nest_history:
                 handoff_input_data = HandoffInputData(
                     input_history=tuple(original_input)
                     if isinstance(original_input, list)
@@ -1011,7 +1016,15 @@ async def execute_handoffs(
                 )
 
             if input_filter and handoff_input_data is not None:
-                logger.debug("Filtering inputs for handoff")
+                filter_name = getattr(input_filter, "__qualname__", repr(input_filter))
+                from_agent = getattr(agent, "name", agent.__class__.__name__)
+                to_agent = getattr(new_agent, "name", new_agent.__class__.__name__)
+                logger.debug(
+                    "Filtering handoff inputs with %s for %s -> %s",
+                    filter_name,
+                    from_agent,
+                    to_agent,
+                )
                 if not callable(input_filter):
                     _error_tracing.attach_error_to_span(
                         span_handoff,
@@ -1041,7 +1054,7 @@ async def execute_handoffs(
                 )
                 pre_step_items = list(filtered.pre_handoff_items)
                 new_step_items = list(filtered.new_items)
-            elif run_config.nest_handoff_history and handoff_input_data is not None:
+            elif should_nest_history and handoff_input_data is not None:
                 nested = nest_handoff_history(
                     handoff_input_data,
                     history_mapper=run_config.handoff_history_mapper,

src/agents/extensions/handoff_filters.py

@@ -1,14 +1,13 @@
 from __future__ import annotations
 
-import json
-from copy import deepcopy
-from typing import Any, cast
-
-from ..handoffs import HandoffHistoryMapper, HandoffInputData
+from ..handoffs import (
+    HandoffInputData,
+    default_handoff_history_mapper,
+    nest_handoff_history,
+)
 from ..items import (
     HandoffCallItem,
     HandoffOutputItem,
-    ItemHelpers,
     ReasoningItem,
     RunItem,
     ToolCallItem,
@@ -18,6 +17,12 @@
 
 """Contains common handoff input filters, for convenience. """
 
+__all__ = [
+    "remove_all_tools",
+    "nest_handoff_history",
+    "default_handoff_history_mapper",
+]
+
 
 def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData:
     """Filters out all tool items: file search, web search and function calls+output."""
@@ -39,181 +44,6 @@ def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData:
     )
 
 
-_CONVERSATION_HISTORY_START = "<CONVERSATION HISTORY>"
-_CONVERSATION_HISTORY_END = "</CONVERSATION HISTORY>"
-
-
-def nest_handoff_history(
-    handoff_input_data: HandoffInputData,
-    *,
-    history_mapper: HandoffHistoryMapper | None = None,
-) -> HandoffInputData:
-    """Summarizes 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)
-    pre_items_as_inputs = [
-        _run_item_to_plain_input(item) for item in handoff_input_data.pre_handoff_items
-    ]
-    new_items_as_inputs = [_run_item_to_plain_input(item) for item in handoff_input_data.new_items]
-    transcript = flattened_history + pre_items_as_inputs + new_items_as_inputs
-
-    mapper = history_mapper or default_handoff_history_mapper
-    history_items = mapper(transcript)
-    filtered_pre_items = tuple(
-        item
-        for item in handoff_input_data.pre_handoff_items
-        if _get_run_item_role(item) != "assistant"
-    )
-
-    return handoff_input_data.clone(
-        input_history=tuple(deepcopy(item) for item in history_items),
-        pre_handoff_items=filtered_pre_items,
-    )
-
-
-def default_handoff_history_mapper(
-    transcript: list[TResponseInputItem],
-) -> list[TResponseInputItem]:
-    """Returns 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)"]
-
-    content_lines = [_CONVERSATION_HISTORY_START, *summary_lines, _CONVERSATION_HISTORY_END]
-    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 != "type"}
-    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_idx = content.find(_CONVERSATION_HISTORY_START)
-    end_idx = content.find(_CONVERSATION_HISTORY_END)
-    if start_idx == -1 or end_idx == -1 or end_idx <= start_idx:
-        return None
-    start_idx += len(_CONVERSATION_HISTORY_START)
-    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 _get_run_item_role(run_item: RunItem) -> str | None:
-    role_candidate = run_item.to_input_item().get("role")
-    return role_candidate if isinstance(role_candidate, str) else None
-
-
 def _remove_tools_from_items(items: tuple[RunItem, ...]) -> tuple[RunItem, ...]:
     filtered_items = []
     for item in items: