Python: [Breaking] Python: Respond with AgentRunResponse with serialized structured output

[larohra]

Motivation and Context

• Fixed the DurableAIAgent.run function to respond with AgentRunResponse rather than Any to be more in line with agent-framework's protocols.
• Handling deserialization of the response.value as part of the agent run, making it easier for the customer to author their codes.
• Remove unnecessary class wrappers (AgentResponse).
• Fixes https://github.com/Azure/durable-agent-framework/issues/133 and https://github.com/Azure/durable-agent-framework/issues/164

Description

The changes bring parity with Dotnet experience and also with agent-framework in general.

This introduces a breaking change where now we need to use yield from when calling the DurableAIAgent (vs just yield before) -

initial_raw = yield from writer.run(
        messages=f"Write a short article about '{payload.topic}'.",
        thread=writer_thread,
        response_format=GeneratedContent,
    )

Additionally, the responses are now of type AgentRunResponse and the structured response is stored in AgentRunResponse.value (as opposed to response["structured_response"] before).

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azurefunctions/agent_framework_azurefunctions
_entities.py	179	21	88%	120, 160–161, 212, 220, 225–226, 253–254, 263, 270, 281, 287–288, 307–308, 378, 410–412, 414
_models.py	150	12	92%	204, 207, 210, 222, 225, 244, 247, 252, 257, 274, 329, 348
_orchestration.py	87	18	79%	168, 173, 175–176, 178, 193, 202–203, 205, 261, 266–273
TOTAL	15449	2360	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2220	130 💤	0 ❌	0 🔥	53.413s ⏱️

[Copilot]

Pull Request Overview

This PR introduces a breaking change to make DurableAIAgent.run() return AgentRunResponse instead of raw dictionaries, aligning with the agent-framework protocols and bringing parity with the .NET experience. The key changes include:

• Modified DurableAIAgent.run() to use generator protocol (yield from) and return typed AgentRunResponse
• Removed the AgentResponse wrapper class in favor of using AgentRunResponse directly with metadata in additional_properties
• Deserialization of structured output (response.value) now happens in the orchestration layer via _ensure_response_format()
• Updated all samples and tests to use yield from syntax and access structured responses via .value property

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
python/packages/azurefunctions/agent_framework_azurefunctions/_orchestration.py	Added generator-based run() method returning AgentRunResponse, with helper methods _load_agent_response() and _ensure_response_format() for response handling and structured output parsing
python/packages/azurefunctions/agent_framework_azurefunctions/_entities.py	Modified run_agent() to return AgentRunResponse directly, removed JSON parsing logic (now handled at orchestration layer), updated metadata handling via additional_properties
python/packages/azurefunctions/agent_framework_azurefunctions/_models.py	Removed AgentResponse dataclass as it's replaced by AgentRunResponse
python/samples/getting_started/azure_functions/04_single_agent_orchestration_chaining/function_app.py	Updated to use yield from and access response via .text property
python/samples/getting_started/azure_functions/05_multi_agent_orchestration_concurrency/function_app.py	Updated to manually advance generators for concurrent execution, accessing results via .text property
python/samples/getting_started/azure_functions/06_multi_agent_orchestration_conditionals/function_app.py	Updated to use yield from and access structured responses via .value property, removed _coerce_structured() helper
python/samples/getting_started/azure_functions/07_single_agent_orchestration_hitl/function_app.py	Updated to use yield from and access structured responses via .value property with validation, removed _coerce_generated_content() helper
python/packages/azurefunctions/tests/test_orchestration.py	Added tests for _load_agent_response() helper method covering instance, serialized, and None cases
python/packages/azurefunctions/tests/test_models.py	Removed all tests for the deleted AgentResponse class
python/packages/azurefunctions/tests/test_entities.py	Updated assertions to check AgentRunResponse type and access metadata via additional_properties
python/packages/azurefunctions/tests/test_app.py	Updated assertions to check AgentRunResponse type and access metadata via additional_properties

[Copilot]

Pull Request Overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[cgillum]

In addition to the feedback below, can we open an issue to track updating the snippets lab (the one we used for Ignite) to account for these breaking changes?

[cgillum]

It looks like you're creating a custom error response from the entity when something unexpected happens, but I don't believe we're doing this in .NET. I'm also not sure if this is the right thing for us to do since it hides the fact that an error occurred from Functions telemetry. Regardless of what design we think is best, we should do the same thing in both languages. Can you open an issue to review the implementation and track consistent error handling for agent invocations?

[larohra]

I agree, the experiences should be consistent.
Created an issue to track this separately - #2434

[cgillum]

I've never seen this direct access of generators and send in durable Python apps before, and I don't think it's intended that we make this a normal part of the programming model. Why is this needed, and can it be replaced with something more conventional?

[larohra]

I've added a comment at the top of this file, but this is basically only for the advance cases where the customers want true parallelism with invoking multi-agents with generators.

 """Fan out to two domain-specific agents and aggregate their responses.

    Note: The generator protocol lets us extract the Durable Task objects so we
    can pass them to task_all for true parallelism. If you only use `yield
    from` on each run call, the agents execute sequentially.
    For sequential execution, you can simply use:
        physicist_result = yield from physicist.run(messages=prompt, thread=physicist_thread)
        chemist_result = yield from chemist.run(messages=prompt, thread=chemist_thread)
    """

The conventional method is defined throughout the rest of the samples with using the yield from model. The only catch here is that that convention is more synchronous -

email_result_raw = yield from email_agent.run(
        messages=email_prompt,
        thread=email_thread,
        response_format=EmailResponse,
    )

[cgillum]

I understand what the sample is doing, but I don't understand why we can't use normal generator syntax. This is not something durable customers need to do in Python today: https://learn.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview?tabs=in-process%2Cnodejs-v3%2Cv1-model&pivots=python#fan-in-out

[larohra]

The difference is in the response type of the types. The context.task_all expects a list[TaskBase] but the agent.run responds with a Generator[.., .., AgentRunResponse] due to which it can't resolve properly. The main reason why this is happening is because we do some post-processing after we get the result back from the entity after we signal it using context.signal_entity() and return an object of AgentRunResponse. Earlier, we were just returning the same task that we got when executing teh signal_entity command without any post-processing.

result = yield self.context.call_entity(entity_id, "run_agent", run_request.to_dict())

logger.debug(
    "[DurableAIAgent] Entity call completed for correlation_id %s",
    correlation_id,
)

response = self._load_agent_response(result)

if response_format is not None:
    self._ensure_response_format(response_format, correlation_id, response)

return response

[larohra]

In addition to the feedback below, can we open an issue to track updating the snippets lab (the one we used for Ignite) to account for these breaking changes?

Opened an issue #2435