Document nested handoff history defaults

Author: jhills20

docs/handoffs.md

@@ -82,6 +82,8 @@ 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 wraps the prior transcript inside a developer-role summary message (see [`RunConfig.nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]). 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.
+
 There are some common patterns (for example removing all tool calls from the history), which are implemented for you in [`agents.extensions.handoff_filters`][]
 
 ```python
@@ -98,6 +100,35 @@ handoff_obj = handoff(
 
 1. This will automatically remove all tools from the history when `FAQ agent` is called.
 
+### Inspecting handoff payloads
+
+When you are debugging a workflow it is often useful to print the exact transcript that will be sent to the next agent. You can do this by inserting a lightweight filter that logs the `HandoffInputData` and then returns either the unmodified payload or the output from [`nest_handoff_history`](agents.extensions.handoff_filters.nest_handoff_history).
+
+```python
+import json
+
+from agents import Agent, HandoffInputData, handoff
+from agents.extensions.handoff_filters import nest_handoff_history
+
+
+def log_handoff_payload(data: HandoffInputData) -> HandoffInputData:
+    nested = nest_handoff_history(data)
+    history_items = nested.input_history if isinstance(nested.input_history, tuple) else ()
+    for idx, item in enumerate(history_items, start=1):
+        print(f"Turn {idx}: {json.dumps(item, indent=2, ensure_ascii=False)}")
+    return nested
+
+
+math_agent = Agent(name="Math agent")
+
+router = Agent(
+    name="Router",
+    handoffs=[handoff(math_agent, input_filter=log_handoff_payload)],
+)
+```
+
+The new [examples/handoffs/log_handoff_history.py](https://github.com/openai/openai-agents-python/tree/main/examples/handoffs/log_handoff_history.py) script contains a complete runnable sample that prints the nested transcript every time a handoff occurs.
+
 ## Recommended prompts
 
 To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix in [`agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX`][], or you can call [`agents.extensions.handoff_prompt.prompt_with_handoff_instructions`][] to automatically add recommended data to your prompts.

docs/running_agents.md

@@ -51,7 +51,7 @@ 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 wraps the prior transcript in a developer-role summary message and keeps the latest user turn separate before invoking the next agent. Set this to `False` or provide a custom handoff filter if you prefer to pass through the raw transcript. You can also call [`nest_handoff_history`](agents.extensions.handoff_filters.nest_handoff_history) from your own filters to reuse the default behavior.
+-   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: When `True` (the default) the runner wraps the prior transcript in a developer-role summary message and keeps the latest user turn separate before invoking the next agent. Set this to `False` or provide a custom handoff filter if you prefer to pass through the raw transcript. You can also call [`nest_handoff_history`](agents.extensions.handoff_filters.nest_handoff_history) from your own filters to reuse the default behavior. 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.
 -   [`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.

examples/handoffs/log_handoff_history.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import asyncio
+import json
+
+from agents import Agent, HandoffInputData, Runner, handoff
+from agents.extensions.handoff_filters import nest_handoff_history
+from agents.items import ItemHelpers
+
+
+math_agent = Agent(
+    name="Math Agent",
+    instructions=(
+        "You are a friendly math expert. Explain your reasoning and finish with a clear answer."
+    ),
+)
+
+
+def log_handoff_history(data: HandoffInputData) -> HandoffInputData:
+    """Print the transcript that will be forwarded to the next agent."""
+
+    nested = nest_handoff_history(data)
+    history_items = (
+        nested.input_history
+        if isinstance(nested.input_history, tuple)
+        else tuple(ItemHelpers.input_to_new_input_list(nested.input_history))
+    )
+
+    print("\n--- Handoff transcript ---")
+    for idx, item in enumerate(history_items, start=1):
+        print(f"Turn {idx}: {json.dumps(item, indent=2, ensure_ascii=False)}")
+    print("--- end of transcript ---\n")
+
+    return nested
+
+
+router_agent = Agent(
+    name="Router",
+    instructions=(
+        "You greet the user and then call the math handoff tool whenever the user asks for"
+        " calculation help so the specialist can respond."
+    ),
+    handoffs=[handoff(math_agent, input_filter=log_handoff_history)],
+)
+
+
+async def main() -> None:
+    result = await Runner.run(
+        router_agent,
+        "Hi there! Could you compute 784 + 219 and explain how you got the result?",
+    )
+    print("Final output:\n", result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())