agent_framework_input_converters rejects nested message format from official documentation

[ghooc]

• Package Name: azure-ai-agentserver-agentframework
• Package Version: 1.0.0b10
• Operating System: Windows
• Python Version: 3.12.10

Describe the bug
The agent_framework_input_converters.py module rejects the nested message format ({"messages": [...]}) shown in the official Microsoft documentation, causing a TypeError when using the documented payload structure for local testing.

Error:

TypeError: Unsupported input type: <class 'dict'>

Traceback:

Traceback (most recent call last):
File "C:\Users<username>\OneDrive\Documents\VSCode Hosted Agent Test2\hostedagenttest.venv\Lib\site-packages\azure\ai\agentserver\agentframework\models\agent_framework_input_converters.py", line 137, in _transform_input_internal
raise TypeError(f"Unsupported input type: {type(input)}")
TypeError: Unsupported input type: <class 'dict'>

To Reproduce
Steps to reproduce the behavior:

1. Create a hosted agent using Agent Framework following the official documentation:

2. Run the agent locally:

from azure.ai.agentserver.agentframework import from_agent_framework

if __name__ == "__main__":
    from_agent_framework(agent).run()  # localhost:8088

3. Send a POST request using the documented payload format:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Where is Seattle?"
            }
        ]
    }
}'

4. Result:

{"code":"server_error","message":"Error processing messages: Unsupported input type: <class 'dict'>"}

Expected behavior
The converter should accept the nested format shown in the official documentation:

POST {{baseUrl}}/responses
Content-Type: application/json
 
{
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Where is Seattle?"
            }
        ]
    }
}

Screenshots
N/A

Additional context

Current workaround:
The only working format is flattened (removing the messages wrapper):

{
    "input": [
        {
            "role": "user",
            "content": "Where is Seattle?"
        }
    ]
}

Root cause:
In agent_framework_input_converters.py (line 63-66), the type hint only accepts str | List[Dict] | None:

   def _transform_input_internal(
        self,
        input: str | List[Dict] | None,
    ) -> str | ChatMessage | list[str] | list[ChatMessage] | None:

Line 137 explicitly rejects dict type:

            raise TypeError(f"Unsupported input type: {type(input)}")

Impact:

• Documentation/implementation mismatch causes confusion for developers
• Local testing requires a different payload format than what is documented
• Unclear whether production deployment behavior differs from local testing

Questions:

• Is this intentional behavior? If so, why does the official documentation show a different format?
• Should the documentation be updated to reflect the flattened format, or should the implementation support the nested format?
• Does the production Foundry Responses API (when deployed to Azure) accept the nested format, or does it also require the flattened format?

[github-actions]

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @dargilco @glharper @howieleung @nick863 @trangevi @trrwilson.