Python: [Bug]: HandoffBuilder with AzureOpenAIResponsesClient fails with stale previous_response_id and loses conversation context on handoff

[frdeange]

Description

When using HandoffBuilder with AzureOpenAIResponsesClient in autonomous mode, the workflow fails after the first handoff cycle. There are two distinct bugs:

Bug 1: Stale previous_response_id causes "No tool output found for function call"

What happened:
After the coordinator invokes a handoff tool (function_call) and hands off to a specialist, the coordinator's response ID (resp_XXX) is stored in session.service_session_id. When the specialist hands back and the coordinator runs again, this stale response ID is sent as previous_response_id to the Responses API. Since the original response contained a pending function_call (the handoff tool) whose output was cleaned from the conversation by clean_conversation_for_handoff(), the API rejects the request.

What I expected:
The handoff workflow should complete without API errors.

Bug 2: Conversation context lost after handoff — agents receive empty/partial history

What happened:
After fixing Bug 1, agents on their 2nd+ invocation receive only partial conversation history. The _cache in HandoffAgentExecutor._run_agent_and_emit() only contains recently broadcast messages, not the full conversation. Since the Responses API no longer carries context via previous_response_id (cleared to fix Bug 1), the agent runs with incomplete context and produces off-topic responses (e.g., researching "French Revolution" instead of the requested topic).

What I expected:
Each agent should see the complete conversation history when it runs, regardless of how many handoffs have occurred.

Steps to reproduce (both bugs):

1. Create a HandoffBuilder workflow with AzureOpenAIResponsesClient and multiple agents
2. Configure autonomous mode with .with_autonomous_mode()
3. Run the workflow — Bug 1 crashes on first handoff back to coordinator; fixing Bug 1 reveals Bug 2

Code Sample

import asyncio
import os
from typing import cast

from agent_framework import Agent, AgentResponseUpdate, Message, resolve_agent_id
from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import HandoffBuilder
from azure.identity import AzureCliCredential

async def main():
    client = AzureOpenAIResponsesClient(
        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
        deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"),
        credential=AzureCliCredential(),
    )

    coordinator = client.as_agent(
        instructions="You are a coordinator. Route tasks to specialists.",
        name="coordinator",
    )
    research_agent = client.as_agent(
        instructions="You are a research specialist. Research the topic briefly, then return control to coordinator.",
        name="research_agent",
    )
    summary_agent = client.as_agent(
        instructions="You summarize research findings. When done, return control to coordinator.",
        name="summary_agent",
    )

    workflow = (
        HandoffBuilder(
            name="test_handoff",
            participants=[coordinator, research_agent, summary_agent],
            termination_condition=lambda conv: (
                sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant") >= 2
            ),
        )
        .with_start_agent(coordinator)
        .add_handoff(coordinator, [research_agent, summary_agent])
        .add_handoff(research_agent, [coordinator])
        .add_handoff(summary_agent, [coordinator])
        .with_autonomous_mode(
            turn_limits={
                resolve_agent_id(coordinator): 2,
                resolve_agent_id(research_agent): 2,
                resolve_agent_id(summary_agent): 2,
            }
        )
        .build()
    )

    async for event in workflow.run("Research Microsoft Agent Framework.", stream=True):
        if event.type == "handoff_sent":
            print(f"\nHandoff: {event.data.source} -> {event.data.target}\n")
        elif event.type == "output":
            data = event.data
            if isinstance(data, AgentResponseUpdate) and data.text:
                print(data.text, end="", flush=True)
            elif isinstance(data, list):
                print("\n\nFinal Transcript:")
                for msg in cast(list[Message], data):
                    print(f"{msg.author_name or msg.role}: {msg.text}\n")

asyncio.run(main())

Error Messages / Stack Traces

Bug 1 error (before fix):

openai.BadRequestError: Error code: 400 - {'error': {'message': 'No tool output found for function call call_qgTofhhnqcvlozSsO1OgsgPK.', 'type': 'invalid_request_error', 'param': 'input', 'code': None}}

Full traceback:

File ".../agent_framework/openai/_responses_client.py", line 317, in _stream
    async for chunk in await client.responses.create(stream=True, **run_options):
File ".../openai/_base_client.py", line 1669, in request
    raise self._make_status_error_from_response(err.response) from None
openai.BadRequestError: Error code: 400 - {'error': {'message': 'No tool output found for function call call_qgTofhhnqcvlozSsO1OgsgPK.', ...}}

Bug 2 symptom (after fixing Bug 1):

No error — but agents produce completely off-topic content because they don't see the original user query or prior conversation turns. Only the system message reaches the agent.

Root Cause Analysis

Bug 1: Stale previous_response_id

In _handoff.py, when _is_handoff_requested() detects a handoff, the agent's session.service_session_id still holds the response ID from the coordinator's last response (which contained a pending handoff function_call). On the next invocation, Agent._prepare_run_context() (line 1063 of _agents.py) reads session.service_session_id and passes it as conversation_id, which _responses_client.py translates to previous_response_id. The Responses API rejects this because the referenced response has an unresolved function_call.

Meanwhile, clean_conversation_for_handoff() strips function_call content from the conversation messages — so the handoff tool call is removed from messages but still lives in the server-side response referenced by previous_response_id.

Bug 2: Lost conversation context

In HandoffAgentExecutor._run_agent_and_emit(), the agent runs with self._cache which only contains messages received since the last _cache.clear(). After a handoff, the cache only has the broadcast messages from the other agent (the cleaned response), not the full conversation history including the original user query and prior turns. The _full_conversation list has everything, but it's not used as input to the agent — only _cache is passed to agent.run().

With the Chat Completions API, this was partially masked because the full conversation was usually rebuilt from messages. With the Responses API, once previous_response_id is cleared (to fix Bug 1), there's no implicit context carry-over, making the context loss visible.

Suggested Fixes

Bug 1 fix — Clear session.service_session_id on handoff

In _handoff.py, after detecting a handoff, clear the session to prevent stale previous_response_id:

# In HandoffAgentExecutor._run_agent_and_emit(), after _is_handoff_requested() returns True:
if handoff_target := self._is_handoff_requested(response):
    # ... validation ...

    # Clear the session's service_session_id to prevent stale previous_response_id
    if self._session and self._session.service_session_id:
        self._session.service_session_id = None

    await cast(WorkflowContext[AgentExecutorRequest], ctx).send_message(
        AgentExecutorRequest(messages=[], should_respond=True), target_id=handoff_target
    )
    # ... rest of handoff logic ...

Bug 2 fix — Use full conversation for agent runs

In _handoff.py, replace _cache with the full conversation before running the agent:

# In HandoffAgentExecutor._run_agent_and_emit(), after extending _full_conversation:
self._full_conversation.extend(self._cache)

# Use full conversation history instead of partial cache
self._cache = list(self._full_conversation)

Both fixes have been tested locally and the workflow completes successfully with correct context in all agent invocations.

Package Versions

agent-framework: 1.0.0b260212, agent-framework-orchestrations: 1.0.0b260212

Python Version

Python 3.13.9

Additional Context

• Bug 1 is specific to AzureOpenAIResponsesClient — it does not occur with AzureOpenAIChatClient because the Chat Completions API uses explicit message history rather than previous_response_id continuation.
• Bug 2 affects both clients, but with AzureOpenAIChatClient the symptoms may be less visible because the chat completions API doesn't have the same context model as Responses.
• The AzureOpenAIChatClient has a separate bug with HandoffBuilder — see companion issue Python: [Bug]: HandoffBuilder with AzureOpenAIChatClient crashes with "Invalid type for messages[N].content: expected string, got object" #4052.
• Related closed issues: Azure Foundry v2 (AzureAIClient) - Invalid Payload Error During Workflow Handoffs with HandoffBuilder #3097, Python: HandoffBuilder incompatible with Azure AI Agent Service (tools cannot be added at request time) #3713, Python: [Bug]: Group Chat orchestrator message cleanup issue #3705.

[frdeange]

Note on installed version: The package was installed directly from the main branch of this repository via:

pip install "agent-framework @ git+https://github.com/microsoft/agent-framework.git@main#subdirectory=python"

The installed version includes up to commit 1b87a07 (PR #4049, merged Feb 18, 2026 at 20:24 UTC — approximately 1 hour before this issue was filed). So these bugs are present in the latest code on main, not just in the PyPI release.

[TaoChenOSU]

Hi @frdeange,

I am not able to reproduce the first error with the code provided. Could you please provide more details such as the model used. Handoff doesn't clean the function calls and results from the agent. The cleaned chat history is stored separately for orchestration output only (not for invoking the agent).

I am able to reproduce the second error and am now looking.

[TaoChenOSU]

The issue I am seeing with the research agent is that it doesn't attempt to perform the research as requested but instead hands off back to the coordinator. This results in the following exception: agent_framework.exceptions.ServiceInvalidRequestError: Messages are required for chat completions, because research agent didn't produce non-function calling contents before the conversation is handed back to the coordinator.

[moonbox3]

@TaoChenOSU these are fixed in either Ben's PR (linked) or in the PR I have open for AG-UI workflows.

[TaoChenOSU]

@TaoChenOSU these are fixed in either Ben's PR (linked) or in the PR I have open for AG-UI workflows.

I believe the solution can be simpler.

There are two issues I discovered when running the provided code:

1. agent_framework.exceptions.ServiceInvalidRequestError: Messages are required for chat completions: this is because the research agent calls the handoff tool without generating any non-function call/result contents. When the control is handed back to the coordinator, the coordinator's cache is empty since it was cleared in the first round, thus the error.
2. {'error': {'message': 'No tool output found for function call call_oW6T0esQitUjcYvXN3uJvkkN.', 'type': 'invalid_request_error', 'param': 'input', 'code': None}}: this is because we terminate the loop and the function result is not provided back to the agent.

Solutions:

1. We always send a message (user/system) along with a handoff. Something like "Continue the conversation" or user defined.
2. We save the function result in the cache and send the result along with all pending messages to the agent the next time it's invoked.

The reason why I hold reservation on erasing the session id on each run is that it's invasive. It breaks the continuity of the session and it's very targeted. With the abstraction, we should not be worrying about if the agent is a response agent or something else.

[TaoChenOSU]

The _full_conversation property is meant to hold the conversation between agents and is meant to be used as the output of the workflow. It doesn't contain function calls and results and those are considered internal to the agents.

If we use that as the context for agent invocation, we are artificially modifying the agents' context, making them unaware of the tools that they have invoked.

[moonbox3]

To your point then it looks like the issue is in _agents.py, I currently see that when store=False, service_session_id should never be used as previous_response_id. That belongs in _agents.py where the session is mapped to options, not what we currently have in the orchestrator.

# Current:
"conversation_id": active_session.service_session_id
    if active_session
    else opts.pop("conversation_id", None),

when it looks like it should be:

# Proposed:
"conversation_id": active_session.service_session_id
    if active_session and opts.get("store") is not False
    else opts.pop("conversation_id", None),

This makes store=False having precedence over service_session_id at the right abstraction layer. The handoff executor wouldn't need to touch the session at all. It just sets store=False on the agent (which it already does) and the rest follows naturally.

[frdeange]

Hi @TaoChenOSU, @moonbox3 — thanks for the thorough analysis!

Quick update with empirical data: We just re-tested against the latest main (commit 0086d38, which includes PR #4055) in a clean venv. Both bugs are still fully reproducible:

Bug 1 (No tool output found) — confirmed with AzureOpenAIResponsesClient + gpt-4.1. Crash happens right after the first handoff back to the coordinator:

Handoff Event: from research_agent to coordinator

openai.BadRequestError: Error code: 400 - {'error': {'message': 'No tool output found 
for function call call_cKxEBcdasxTazxKgXdHnYf1V.', ...}}

Bug 2 (context loss) — confirmed with AzureOpenAIChatClient + gpt-4.1. The workflow completes but the coordinator enters a loop printing "User did not respond. Continue assisting autonomously." and agents produce off-topic content, consistent with partial/missing conversation history.

On the proposed solutions:

We agree that @moonbox3's approach is cleaner than our original suggestion of clearing session.service_session_id. Making store=False take precedence over service_session_id in _agents.py is the right abstraction — the handoff executor already sets store=False, so this would fix Bug 1 without invasive session manipulation.

Regarding _full_conversation — @TaoChenOSU's point is valid that it strips function calls/results, which would make agents unaware of their own tool usage. @TaoChenOSU's solution #2 (saving the function result in the cache and replaying it along with pending messages on next invocation) sounds like the correct approach for Bug 2.

Note on the reproduction script: It's directly based on the official sample in this repo: python/samples/03-workflows/orchestrations/handoff_autonomous.py, adapted to use AzureOpenAIResponsesClient.

Versions tested:

• agent-framework: 1.0.0rc1
• agent-framework-orchestrations: 1.0.0b260219
• Commit: 0086d38f587ffe517478d886d55c2c710b52088b
• Model: gpt-4.1
• Python: 3.13.9

Happy to run any additional tests or provide debug logs if it helps!

[frdeange]

Hi @TaoChenOSU, @moonbox3, @alliscode —

Following up on this issue. We can confirm that both fixes from PR #3911 (clearing service_session_id and using _full_conversation for cache) are present in the current release (agent-framework-orchestrations 1.0.0b260225) and correctly address the stale previous_response_id and context loss issues described here.

However, we've identified a third, distinct bug that is still present and causes the handoff_autonomous.py sample (and any HandoffBuilder workflow) to crash. We've filed it separately as #4357:

Bug: When store=False (forced by the handoff), the conversation replay includes server-assigned IDs (rs_* for reasoning items, fc_* for function_call items) in the input payload. Since these items were never persisted (because store=False), the Responses API rejects them with:

Item with id 'rs_...' not found. Items are not persisted when store is set to false.

Root cause is in _responses_client.py → _prepare_content_for_openai(), which unconditionally serializes server-assigned IDs into reasoning and function_call items regardless of the store setting. Full analysis, reproduction steps, and a working monkeypatch are in #4357.

Tested with:

• agent-framework: 1.0.0rc2 / agent-framework-orchestrations: 1.0.0b260225
• Both AzureOpenAIResponsesClient and AzureAIClient
• Python 3.13, models: gpt-5.2-chat, gpt-4.1