.to_input_list() provides unparsable data if handoff happens in that run w/ nest_handoff_history: true

[HailTheLotusJewel]

I ran into an issue. Consider a two agent scenario where handoff happens in between the run:

async def main():
    agent_two = Agent(
        name="Agent Two",
        handoff_description="Pass control to Agent Two to finish the run.",
        instructions="Call your only tool to finish the request, then end the run cleanly.",
        tools=[finisher_tool],
    )

    agent_one = Agent(
        name="Agent One",
        # handoff_description=,
        instructions=(
            "Use your single tool to gather the starter response, then hand off to Agent Two "
            "so they can finish."
        ),
        tools=[starter_tool],
        handoffs=[handoff(agent=agent_two)],
    )

    input_items = [
        {"role": "user", "content": "Kick off the two-agent workflow."},
    ]

    result = await Runner.run(agent_one, input_items)
    print("Final output:", result.final_output)

    history = result.to_input_list()
    save_history("two_agent_history.json", history)

This is the raw history of this run:

[
  {
    "role": "assistant",
    "content": "For context, here is the conversation so far between the user and the previous agent:\n<CONVERSATION HISTORY>\n1. user: Kick off the two-agent workflow.\n2. function_call: {\"arguments\": \"{}\", \"call_id\": \"call_4aRTBpoGzHfMwFzQXT8W2jFC\", \"name\": \"starter_tool\", \"id\": \"fc_0cb86b419925643100695acd645bbc8194b69e50c876313b97\", \"status\": \"completed\"}\n3. function_call_output: {\"call_id\": \"call_4aRTBpoGzHfMwFzQXT8W2jFC\", \"output\": \"Agent One's tool ran and prepared the handoff note.\"}\n4. function_call: {\"arguments\": \"{}\", \"call_id\": \"call_u533nEOSzFSsjJ8nnEqTr09p\", \"name\": \"transfer_to_agent_two\", \"id\": \"fc_0cb86b419925643100695acd6529508194b706a3283855e29b\", \"status\": \"completed\"}\n5. function_call_output: {\"call_id\": \"call_u533nEOSzFSsjJ8nnEqTr09p\", \"output\": \"{\\\"assistant\\\": \\\"Agent Two\\\"}\"}\n</CONVERSATION HISTORY>"
  },
  {
    "arguments": "{}",
    "call_id": "call_4aRTBpoGzHfMwFzQXT8W2jFC",
    "name": "starter_tool",
    "type": "function_call",
    "id": "fc_0cb86b419925643100695acd645bbc8194b69e50c876313b97",
    "status": "completed"
  },
  {
    "call_id": "call_4aRTBpoGzHfMwFzQXT8W2jFC",
    "output": "Agent One's tool ran and prepared the handoff note.",
    "type": "function_call_output"
  },
  {
    "arguments": "{}",
    "call_id": "call_u533nEOSzFSsjJ8nnEqTr09p",
    "name": "transfer_to_agent_two",
    "type": "function_call",
    "id": "fc_0cb86b419925643100695acd6529508194b706a3283855e29b",
    "status": "completed"
  },
  {
    "call_id": "call_u533nEOSzFSsjJ8nnEqTr09p",
    "output": "{\"assistant\": \"Agent Two\"}",
    "type": "function_call_output"
  },
  {
    "arguments": "{}",
    "call_id": "call_LQp6Vo0xMjnNQTNArZkrzGrv",
    "name": "finisher_tool",
    "type": "function_call",
    "id": "fc_0cb86b419925643100695acd660b8c819482c9ccefc5051ba3",
    "status": "completed"
  },
  {
    "call_id": "call_LQp6Vo0xMjnNQTNArZkrzGrv",
    "output": "Agent Two's tool ran and wrapped up the workflow.",
    "type": "function_call_output"
  },
  {
    "id": "msg_0cb86b419925643100695acd66c5108194ba18a7865584484c",
    "content": [
      {
        "annotations": [],
        "text": "The two-agent workflow has successfully completed. Agent One initiated the process and prepared the handoff note, and Agent Two received the handoff and wrapped up the workflow. If you need to run another workflow or have any questions, let me know!",
        "type": "output_text",
        "logprobs": []
      }
    ],
    "role": "assistant",
    "status": "completed",
    "type": "message"
  }
]

If you see over here, the first assistant message is something which I guess is SDK/Handoff specific behaviour. What if I want the normal input list which just lists all the actions taken by the agent(s) ? Is there a separate inbuilt method which supports normal agent run history ?

Originally posted by @HailTheLotusJewel in #2253

[HailTheLotusJewel]

@seratch I actually solved this issue by passing nest_handoff_history=False in the handoff function call. As per my knowledge, the only downside is that this approach uses more tokens as compared to the default approach (nest_handoff_history=True). But it resolves the unparseable data issue.

[ihower]

@HailTheLotusJewel This behavior is expected.

With the current handoff design, when a handoff happens the SDK wraps the previous conversation history into one assistant message. This is intentional behavior. You can see the original design here: #1996

If you need a history that can be parsed as a normal input list, using nest_handoff_history=False is the correct and supported solution.

Also, the default nest_handoff_history=True does not actually save tokens, because no summarization or compression is done. It only changes the structure of the history.

Personally, I recommend using nest_handoff_history=False unless you have cross-model handoff compatibility issues that require the nested format.

This behavior was also discussed here: #2211 and it may change in the future.

[HailTheLotusJewel]

@ihower Got it. Thanks!