Python: ChatAgent.run(reasoning=...) parameter ignored - reasoning omitted from Responses API payload

[mortezahoolari]

When using AzureOpenAIResponsesClient with ChatAgent.run(), the reasoning parameter is silently ignored and not sent to the Azure OpenAI Responses API. This prevents access to reasoning summaries from GPT-5 series models.

Environment

• Python: 3.11
• agent-framework: 1.0.0b251001
• Model: gpt-5-mini (Azure OpenAI)
• API Version: preview
• Endpoint: /openai/v1/responses

Minimal Reproduction

import asyncio
import json
from agent_framework import ChatAgent
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential

async def main():
    client = AzureOpenAIResponsesClient(
        credential=AzureCliCredential(),
        deployment_name="gpt-5-mini",
        endpoint="https://YOUR-RESOURCE.openai.azure.com",
        api_version="preview"
    )

    # Intercept payload to see what's sent
    original_create = client.client.responses.create
    async def capture(**kwargs):
        print("Payload:", json.dumps(kwargs, indent=2, default=str))
        return await original_create(**kwargs)
    client.client.responses.create = capture

    agent = ChatAgent(chat_client=client, instructions="You are helpful.")
    thread = agent.get_new_thread()

    # Pass reasoning parameter
    result = await agent.run(
        "What is 2+2?",
        thread=thread,
        reasoning={"effort": "medium", "summary": "auto"}  # IGNORED!
    )

    # Check response
    response = result.raw_representation.raw_representation
    has_summary = any('Reasoning' in type(i).__name__ and i.summary
                      for i in response.output)
    print(f"Has reasoning summary: {has_summary}")  # False

asyncio.run(main())

Expected Behavior

Payload should include:

{
  "model": "gpt-5-mini",
  "input": [...],
  "reasoning": {
    "effort": "medium",
    "summary": "auto"
  }
}

Response should contain: ResponseReasoningItem with populated summary field.

Actual Behavior

Payload sent (reasoning missing):

{
  "model": "gpt-5-mini",
  "input": [...],
  "store": false
}

Response: No reasoning summary generated.

Root Cause

1. ChatOptions (_types.py) has no reasoning parameter
2. _prepare_options() (openai/_responses_client.py) does not extract or forward reasoning to the API

Proof

Tested three scenarios:

1. Direct OpenAI SDK: ✅ reasoning sent, summary received
2. Agent Framework (unpatched): ❌ reasoning NOT sent, NO summary
3. Agent Framework (patched): ✅ reasoning sent, summary received

The fix works when reasoning is manually added to the payload.

Workaround

Monkeypatch _prepare_options():

original_prepare = client._prepare_options

def patched_prepare(messages, chat_options):
    opts = original_prepare(messages, chat_options)
    if hasattr(chat_options, 'additional_properties'):
        if 'reasoning' in chat_options.additional_properties:
            opts['reasoning'] = chat_options.additional_properties['reasoning']
    return opts

client._prepare_options = patched_prepare

# Then use additional_properties to pass reasoning
result = await agent.run(
    "...",
    additional_properties={"reasoning": {"effort": "medium", "summary": "auto"}}
)

Impact

Users cannot access reasoning summaries from Azure OpenAI reasoning models (GPT-5 series) through Agent Framework, despite this being a documented feature of the Responses API.

Suggested Fix

Add reasoning parameter to:

1. ChatOptions.__init__()
2. _prepare_options() to forward it to the API payload
3. ChatAgent.run() signature

---

Full investigation with evidence: Available upon request (payload captures, assertions, tools+reasoning coexistence tests).

[eavanvalkenburg]

@mortezahoolari since there is no unified way to specify reasoning across api's, even OpenAI Chat Completion vs Responses has a different one, we do not intend to add this to ChatOptions at this time, I have done some improvements in handling to ensure this works, and improved the sample in PR #1255

[mortezahoolari]

Thanks @eavanvalkenburg —understood. We’ll use additional_properties["reasoning"] with the Responses client and update to model_id once #1255 lands. I’ll verify on the next build and report back.