Remove metadata from nested handoff history

Author: jhills20

docs/handoffs.md

@@ -100,35 +100,6 @@ 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 so you can see the `<CONVERSATION HISTORY>` block that will be passed to the next agent.
-
 ## 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.

examples/handoffs/log_handoff_history.py

@@ -41,8 +41,6 @@ def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData:
 
 _CONVERSATION_HISTORY_START = "<CONVERSATION HISTORY>"
 _CONVERSATION_HISTORY_END = "</CONVERSATION HISTORY>"
-_NEST_HISTORY_METADATA_KEY = "nest_handoff_history"
-_NEST_HISTORY_TRANSCRIPT_KEY = "transcript"
 
 
 def nest_handoff_history(handoff_input_data: HandoffInputData) -> HandoffInputData:
@@ -100,9 +98,6 @@ def _build_developer_message(transcript: list[TResponseInputItem]) -> TResponseI
     return {
         "role": "developer",
         "content": content,
-        "metadata": {
-            _NEST_HISTORY_METADATA_KEY: {_NEST_HISTORY_TRANSCRIPT_KEY: transcript_copy}
-        },
     }
 
 
@@ -163,20 +158,55 @@ def _extract_nested_history_transcript(
 ) -> list[TResponseInputItem] | None:
     if item.get("role") != "developer":
         return None
-    metadata = item.get("metadata")
-    if not isinstance(metadata, dict):
+    content = item.get("content")
+    if not isinstance(content, str):
         return None
-    payload = metadata.get(_NEST_HISTORY_METADATA_KEY)
-    if not isinstance(payload, dict):
+    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
-    transcript = payload.get(_NEST_HISTORY_TRANSCRIPT_KEY)
-    if not isinstance(transcript, list):
+    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
-    normalized: list[TResponseInputItem] = []
-    for entry in transcript:
-        if isinstance(entry, dict):
-            normalized.append(deepcopy(entry))
-    return normalized if normalized else []
+    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: TResponseInputItem = {"role": role}
+    if name:
+        reconstructed["name"] = name
+    content = remainder.strip()
+    if content:
+        reconstructed["content"] = content
+    return 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:

src/agents/extensions/handoff_filters.py

@@ -247,15 +247,6 @@ def test_nest_handoff_history_wraps_transcript() -> None:
     assert "<CONVERSATION HISTORY>" in developer_content
     assert "</CONVERSATION HISTORY>" in developer_content
     assert "Assist reply" in developer_content
-    metadata = nested.input_history[0].get("metadata")
-    assert isinstance(metadata, dict)
-    history_payload = metadata.get("nest_handoff_history")
-    assert isinstance(history_payload, dict)
-    transcript = history_payload.get("transcript")
-    assert isinstance(transcript, list)
-    assert len(transcript) == 4
-    assert transcript[0]["role"] == "user"
-    assert transcript[1]["role"] == "assistant"
     assert nested.input_history[1]["role"] == "user"
     assert nested.input_history[1]["content"] == "Hello"
     assert len(nested.pre_handoff_items) == 0