Python: [Bug]: HandoffBuilder + OpenAIChatClient tool approval causes duplicate tool_calls messages (400 error)

[pamelafox]

Description

When using HandoffBuilder with OpenAIChatClient (Chat Completions API) and a tool that has approval_mode="always_require", the workflow crashes with a 400 error after the user approves a tool call. The OpenAI API rejects the request because the message array contains a duplicate assistant message with tool_calls that has no matching tool response message.

Root cause

HandoffAgentExecutor._run_agent_and_emit() replays _full_conversation as the message cache. The default InMemoryHistoryProvider also independently stores and loads messages via the agent session. When the workflow resumes after tool approval, both sources contribute messages, causing the assistant tool_calls message to appear twice — once from history and once from _full_conversation. The first copy has no matching tool response, so the OpenAI Chat Completions API rejects it:

An assistant message with 'tool_calls' must be followed by tool messages
responding to each 'tool_call_id'. The following tool_call_ids did not have
response messages: call_XXXXX

Debug output showing the duplicated messages sent to the API:

[0] role=system  (instructions)
[1] role=user    (initial message)           ← from InMemoryHistoryProvider
[2] role=assistant, tool_call=call_XXX       ← from InMemoryHistoryProvider (NO matching tool response)
[3] role=user    (initial message)           ← from _full_conversation
[4] role=assistant, tool_call=call_XXX       ← from _full_conversation
[5] role=tool, tool_call_id=call_XXX         ← approval result

Message [2] is the orphaned tool_calls that triggers the 400 error.

Relationship to #4376

Issue #4376 describes a related but distinct bug: HandoffBuilder forces store=False, which breaks AzureOpenAIResponsesClient because the FunctionInvocationLayer captures response.conversation_id and references a non-persisted response. That bug is specific to the Responses API path. This bug affects the Chat Completions API path (OpenAIChatClient) where store=False doesn't prevent InMemoryHistoryProvider from duplicating messages.

Steps to reproduce

1. Create agents with OpenAIChatClient (or any Chat Completions-based client)
2. Add a tool with @tool(approval_mode="always_require")
3. Build a HandoffBuilder workflow
4. Run the workflow with stream=True
5. When the tool approval request_info event fires, approve it
6. Resume with workflow.run(responses=responses, stream=True)

Code Sample

from agent_framework import Agent, Content, WorkflowEvent, tool
from agent_framework.openai import OpenAIChatClient
from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder

client = OpenAIChatClient(
    base_url="https://models.github.ai/inference",
    api_key="...",
    model_id="openai/gpt-5-mini",
)

@tool(approval_mode="always_require")
def submit_refund(order_id: str, amount: str) -> str:
    """Process a refund."""
    return f"Refund of {amount} for order {order_id}"

triage = client.as_agent(name="triage", instructions="Route to refund agent.")
refund = client.as_agent(name="refund", instructions="Process refunds.", tools=[submit_refund])

workflow = (
    HandoffBuilder(name="demo", participants=[triage, refund])
    .with_start_agent(triage)
    .build()
)

# Initial run triggers tool approval request
events = []
async for event in workflow.run("Refund order 123", stream=True):
    if event.type == "request_info":
        events.append(event)

# Approve and resume → crashes with 400
responses = {}
for e in events:
    if isinstance(e.data, Content) and e.data.type == "function_approval_request":
        responses[e.request_id] = e.data.to_function_approval_response(approved=True)

async for event in workflow.run(responses=responses, stream=True):  # 💥 400 error
    pass

I also verified this reproduces when adapting the official handoff_with_tool_approval_checkpoint_resume.py sample to use OpenAIChatClient instead of AzureOpenAIResponsesClient.

Error Messages / Stack Traces

openai.BadRequestError: Error code: 400 - {'error': {'message': "An assistant message
with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'.
The following tool_call_ids did not have response messages: call_XXXXX",
'type': 'invalid_request_error', 'param': 'messages.[3].role', 'code': None}}

Package Versions

agent-framework-core pinned at commit 11628c3166a1845683c5aef1e0d389eb862bcbaa (post-rc2)

Python Version

Python 3.12

Additional Context

The HandoffAgentExecutor already manages full conversation replay via _full_conversation and sets store=False. The InMemoryHistoryProvider (auto-added by Agent.__init__) should either be suppressed or have load_messages=False in handoff workflows to prevent this duplication. As a workaround, explicitly passing context_providers=[InMemoryHistoryProvider(load_messages=False)] to each agent prevents the error for the first tool approval round, but subsequent rounds still fail due to the same duplication in _full_conversation itself.

[pamelafox]

Full adapted version of official samples with Chat client:

"""Official MAF sample adapted for OpenAIChatClient (GitHub Models).

Original: github.com/microsoft/agent-framework/.../handoff_with_tool_approval_checkpoint_resume.py
Adapted: Replaced AzureOpenAIResponsesClient with OpenAIChatClient,
         removed checkpoint/resume logic since we just want to test the
         handoff + tool-approval flow end-to-end.

Run:
    uv run examples/official_handoff_tool_approval.py
"""

import asyncio
import json
import os
from typing import Any

from agent_framework import (
    Agent,
    Content,
    WorkflowEvent,
    tool,
)
from agent_framework.openai import OpenAIChatClient
from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
from dotenv import load_dotenv

load_dotenv(override=True)
API_HOST = os.getenv("API_HOST", "github")

# Configure the chat client based on the API host
if API_HOST == "azure":
    from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider

    async_credential = DefaultAzureCredential()
    token_provider = get_bearer_token_provider(async_credential, "https://cognitiveservices.azure.com/.default")
    client = OpenAIChatClient(
        base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT']}/openai/v1/",
        api_key=token_provider,
        model_id=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT"],
    )
elif API_HOST == "github":
    async_credential = None
    client = OpenAIChatClient(
        base_url="https://models.github.ai/inference",
        api_key=os.environ["GITHUB_TOKEN"],
        model_id=os.getenv("GITHUB_MODEL", "openai/gpt-5-mini"),
    )
else:
    async_credential = None
    client = OpenAIChatClient(
        api_key=os.environ["OPENAI_API_KEY"], model_id=os.environ.get("OPENAI_MODEL", "gpt-5-mini")
    )


# --- Tool (matches official sample) ---


@tool(approval_mode="always_require")
def submit_refund(refund_description: str, amount: str, order_id: str) -> str:
    """Capture a refund request for manual review before processing."""
    return f"refund recorded for order {order_id} (amount: {amount}) with details: {refund_description}"


# --- Agents (matches official sample, using client.as_agent) ---

triage = client.as_agent(
    name="triage_agent",
    instructions=(
        "You are a customer service triage agent. Listen to customer issues and determine "
        "if they need refund help or order tracking. Use handoff_to_refund_agent or "
        "handoff_to_order_agent to transfer them."
    ),
)

refund = client.as_agent(
    name="refund_agent",
    instructions=(
        "You are a refund specialist. Help customers with refund requests. "
        "Be empathetic and ask for order numbers if not provided. "
        "When the user confirms they want a refund and supplies order details, call submit_refund "
        "to record the request before continuing."
    ),
    tools=[submit_refund],
)

order = client.as_agent(
    name="order_agent",
    instructions=(
        "You are an order tracking specialist. Help customers track their orders. "
        "Ask for order numbers and provide shipping updates."
    ),
)


# --- Workflow (matches official sample) ---

workflow = (
    HandoffBuilder(
        name="tool_approval_test",
        participants=[triage, refund, order],
        termination_condition=lambda conv: sum(1 for msg in conv if msg.role == "user") >= 5,
    )
    .with_start_agent(triage)
    .build()
)


# --- Helpers (from official sample) ---


def print_handoff_agent_user_request(request: HandoffAgentUserRequest, request_id: str) -> None:
    """Log pending handoff request details."""
    print(f"\n{'=' * 60}")
    print("User input needed")
    print(f"Request ID: {request_id}")
    response = request.agent_response
    if not response.messages:
        print("(No agent messages)")
        return
    for message in response.messages:
        if not message.text:
            continue
        speaker = message.author_name or message.role
        print(f"{speaker}: {message.text}")
    print(f"{'=' * 60}\n")


def print_function_approval_request(request: Content, request_id: str) -> None:
    """Log pending tool approval details."""
    args = request.function_call.parse_arguments() or {}  # type: ignore
    print(f"\n{'=' * 60}")
    print("Tool approval required")
    print(f"Request ID: {request_id}")
    print(f"Function: {request.function_call.name}")  # type: ignore
    print(f"Arguments:\n{json.dumps(args, indent=2)}")
    print(f"{'=' * 60}\n")


# --- Main (simplified: no checkpoint, same event loop structure) ---


async def main() -> None:
    """Run the handoff workflow with scripted responses (no checkpoint)."""
    # Scripted human input for demo purposes
    handoff_responses = [
        (
            "The headphones in order 12345 arrived cracked. "
            "Please submit the refund for $89.99 and send a replacement to my original address."
        ),
        "Yes, that covers the damage and refund request.",
        "That's everything I needed for the refund.",
        "Thanks for handling the refund.",
    ]

    print("=" * 60)
    print("HANDOFF WORKFLOW TOOL APPROVAL TEST")
    print("=" * 60)

    initial_request = "Hi, my order 12345 arrived damaged. I need a refund."
    print(f"\nUser: {initial_request}\n")

    # Phase 1: Initial run
    print("Running initial workflow...")
    request_events: list[WorkflowEvent] = []
    async for event in workflow.run(initial_request, stream=True):
        if event.type == "request_info":
            request_events.append(event)

    if not request_events:
        print("Workflow completed without needing user input")
        return

    print("=" * 60)
    print("WORKFLOW PAUSED with pending requests")
    print("=" * 60)

    # Phase 2: Interactive loop (same pattern as official sample, minus checkpoint)
    while request_events:
        responses: dict[str, Any] = {}
        for request_event in request_events:
            print(f"Pending request ID: {request_event.request_id}, Type: {type(request_event.data)}")
            if isinstance(request_event.data, HandoffAgentUserRequest):
                print_handoff_agent_user_request(request_event.data, request_event.request_id)
                if not handoff_responses:
                    print("No more scripted responses, ending.")
                    return
                response = handoff_responses.pop(0)
                print(f"Responding with: {response}")
                responses[request_event.request_id] = HandoffAgentUserRequest.create_response(response)
            elif isinstance(request_event.data, Content) and request_event.data.type == "function_approval_request":
                print_function_approval_request(request_event.data, request_event.request_id)
                print("Approving tool call...")
                responses[request_event.request_id] = request_event.data.to_function_approval_response(approved=True)
            else:
                raise ValueError(f"Unsupported request type: {type(request_event.data)}")

        print("Resuming workflow...")
        request_events = []
        async for event in workflow.run(responses=responses, stream=True):
            if event.type == "request_info":
                request_events.append(event)

    print("\n" + "=" * 60)
    print("DEMO COMPLETE")
    print("=" * 60)

    if async_credential:
        await async_credential.close()


if __name__ == "__main__":
    asyncio.run(main())

[TaoChenOSU]

Related issues:

• Python: [Bug]: HandoffBuilder store=False breaks FunctionInvocationLayer tool result submission #4376
• Python: [Bug]: Handoff workflow with store=False sends server-assigned item IDs (rs_*, fc_*) in input, causing "Item not found" API errors #4357
• Python: [Bug]: HandoffBuilder with AzureOpenAIResponsesClient fails with stale previous_response_id and loses conversation context on handoff #4053
• Python: [Bug]: STORES_BY_DEFAULT seems to cause agents have neither local nor remote storage #4488

Related PRs:

• Python: Fix handoff workflow with store=False sending server-assigned item IDs #4368

We will be addressing these all at once by formalizing context management in Handoff.