From 8500aebc8f0ce489413d1ea8f430593b6ce014e9 Mon Sep 17 00:00:00 2001 From: "L. Elaine Dazzio" Date: Fri, 10 Apr 2026 16:07:52 -0400 Subject: [PATCH 1/4] feat: add finish_reason support to AgentResponse and AgentResponseUpdate Add finish_reason field to AgentResponse and AgentResponseUpdate classes, propagate it through _process_update() and map_chat_to_agent_update(), and add comprehensive unit tests. Fixes #4622 --- .../core/tests/core/test_finish_reason.py | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 python/packages/core/tests/core/test_finish_reason.py diff --git a/python/packages/core/tests/core/test_finish_reason.py b/python/packages/core/tests/core/test_finish_reason.py new file mode 100644 index 0000000000..1c01215f22 --- /dev/null +++ b/python/packages/core/tests/core/test_finish_reason.py @@ -0,0 +1,100 @@ +from agent_framework import ( + AgentResponse, + AgentResponseUpdate, + ChatResponseUpdate, + Content, + Message, +) +from agent_framework._types import _process_update, map_chat_to_agent_update + + +def test_agent_response_init_with_finish_reason() -> None: + """Test that AgentResponse correctly initializes and stores finish_reason.""" + response = AgentResponse( + messages=[Message("assistant", [Content.from_text("test")])], + finish_reason="stop", + ) + assert response.finish_reason == "stop" + + +def test_agent_response_update_init_with_finish_reason() -> None: + """Test that AgentResponseUpdate correctly initializes and stores finish_reason.""" + update = AgentResponseUpdate( + contents=[Content.from_text("test")], + role="assistant", + finish_reason="stop", + ) + assert update.finish_reason == "stop" + + +def test_map_chat_to_agent_update_forwards_finish_reason() -> None: + """Test that mapping a ChatResponseUpdate with finish_reason forwards it.""" + chat_update = ChatResponseUpdate( + contents=[Content.from_text("test")], + finish_reason="length", + ) + agent_update = map_chat_to_agent_update(chat_update, agent_name="test_agent") + + assert agent_update.finish_reason == "length" + assert agent_update.author_name == "test_agent" + + +def test_process_update_propagates_finish_reason_to_agent_response() -> None: + """Test that _process_update correctly updates an AgentResponse from an AgentResponseUpdate.""" + response = AgentResponse(messages=[Message("assistant", [Content.from_text("test")])]) + update = AgentResponseUpdate( + contents=[Content.from_text("more text")], + role="assistant", + finish_reason="stop", + ) + + # Process the update + _process_update(response, update) + + assert response.finish_reason == "stop" + + +def test_process_update_does_not_overwrite_with_none() -> None: + """Test that _process_update does not overwrite an existing finish_reason with None.""" + response = AgentResponse( + messages=[Message("assistant", [Content.from_text("test")])], + finish_reason="length", + ) + update = AgentResponseUpdate( + contents=[Content.from_text("more text")], + role="assistant", + finish_reason=None, + ) + + # Process the update + _process_update(response, update) + + assert response.finish_reason == "length" + + +def test_agent_response_serialization_includes_finish_reason() -> None: + """Test that AgentResponse serializes correctly, including finish_reason.""" + response = AgentResponse( + messages=[Message("assistant", [Content.from_text("test")])], + response_id="test_123", + finish_reason="stop", + ) + + # Serialize using the framework's API and verify finish_reason is included. + data = response.to_dict() + assert "finish_reason" in data + assert data["finish_reason"] == "stop" + + +def test_agent_response_update_serialization_includes_finish_reason() -> None: + """Test that AgentResponseUpdate serializes correctly, including finish_reason.""" + update = AgentResponseUpdate( + contents=[Content.from_text("test")], + role="assistant", + response_id="test_456", + finish_reason="tool_calls", + ) + + data = update.to_dict() + assert "finish_reason" in data + assert data["finish_reason"] == "tool_calls" From 8342bda8f3af2fa1a9021ed70cf0ffc4514a5f37 Mon Sep 17 00:00:00 2001 From: LEDazzio01 <170764058+LEDazzio01@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:35:48 -0400 Subject: [PATCH 2/4] feat: add finish_reason to AgentResponse and AgentResponseUpdate --- python/packages/core/agent_framework/_types.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/python/packages/core/agent_framework/_types.py b/python/packages/core/agent_framework/_types.py index a4e3a57330..8f2fcbdf55 100644 --- a/python/packages/core/agent_framework/_types.py +++ b/python/packages/core/agent_framework/_types.py @@ -1866,6 +1866,9 @@ def _process_update(response: ChatResponse | AgentResponse, update: ChatResponse response.finish_reason = update.finish_reason if update.model_id is not None: response.model_id = update.model_id + if isinstance(response, AgentResponse) and isinstance(update, AgentResponseUpdate): + if update.finish_reason is not None: + response.finish_reason = update.finish_reason response.continuation_token = update.continuation_token @@ -2369,6 +2372,7 @@ def __init__( response_id: str | None = None, agent_id: str | None = None, created_at: CreatedAtT | None = None, + finish_reason: FinishReasonLiteral | FinishReason | None = None, usage_details: UsageDetails | None = None, value: ResponseModelT | None = None, response_format: type[BaseModel] | None = None, @@ -2410,6 +2414,7 @@ def __init__( self.response_id = response_id self.agent_id = agent_id self.created_at = created_at + self.finish_reason = finish_reason self.usage_details = usage_details self._value: ResponseModelT | None = value self._response_format: type[BaseModel] | None = response_format @@ -2604,6 +2609,7 @@ def __init__( response_id: str | None = None, message_id: str | None = None, created_at: CreatedAtT | None = None, + finish_reason: FinishReasonLiteral | FinishReason | None = None, continuation_token: ContinuationToken | None = None, additional_properties: dict[str, Any] | None = None, raw_representation: Any | None = None, @@ -2645,6 +2651,7 @@ def __init__( self.response_id = response_id self.message_id = message_id self.created_at = created_at + self.finish_reason = finish_reason self.continuation_token = continuation_token self.additional_properties = _restore_compaction_annotation_in_additional_properties( additional_properties, @@ -2677,6 +2684,7 @@ def map_chat_to_agent_update(update: ChatResponseUpdate, agent_name: str | None) response_id=update.response_id, message_id=update.message_id, created_at=update.created_at, + finish_reason=update.finish_reason, continuation_token=update.continuation_token, additional_properties=update.additional_properties, raw_representation=update, From 000fe5b5bbbe4781f0a3635c523cbb6bd3c67f52 Mon Sep 17 00:00:00 2001 From: "L. Elaine Dazzio" Date: Fri, 10 Apr 2026 17:02:04 -0400 Subject: [PATCH 3/4] style: add copyright header to test_finish_reason.py --- python/packages/core/tests/core/test_finish_reason.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/python/packages/core/tests/core/test_finish_reason.py b/python/packages/core/tests/core/test_finish_reason.py index 1c01215f22..67a3dd7ded 100644 --- a/python/packages/core/tests/core/test_finish_reason.py +++ b/python/packages/core/tests/core/test_finish_reason.py @@ -1,3 +1,5 @@ +# Copyright (c) Microsoft. All rights reserved. + from agent_framework import ( AgentResponse, AgentResponseUpdate, From 3447c1409d52e6f23ed4ace8f158f2b9dcddcbb5 Mon Sep 17 00:00:00 2001 From: LEDazzio01 <170764058+LEDazzio01@users.noreply.github.com> Date: Fri, 10 Apr 2026 17:02:43 -0400 Subject: [PATCH 4/4] docs: add finish_reason to AgentResponse and AgentResponseUpdate docstrings --- python/packages/core/agent_framework/_types.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/python/packages/core/agent_framework/_types.py b/python/packages/core/agent_framework/_types.py index 8f2fcbdf55..299b364d17 100644 --- a/python/packages/core/agent_framework/_types.py +++ b/python/packages/core/agent_framework/_types.py @@ -2388,6 +2388,9 @@ def __init__( agent_id: The identifier of the agent that produced this response. Useful in multi-agent scenarios to track which agent generated the response. created_at: A timestamp for the chat response. + finish_reason: The reason the model stopped generating. Common values include + ``"stop"`` (natural completion), ``"length"`` (token limit), and + ``"tool_calls"`` (the model invoked a tool). usage_details: The usage details for the chat response. value: The structured output of the agent run response, if applicable. response_format: Optional response format for the agent response. @@ -2625,6 +2628,9 @@ def __init__( response_id: Optional ID of the response of which this update is a part. message_id: Optional ID of the message of which this update is a part. created_at: Optional timestamp for the chat response update. + finish_reason: The reason the model stopped generating. Common values include + ``"stop"`` (natural completion), ``"length"`` (token limit), and + ``"tool_calls"`` (the model invoked a tool). continuation_token: Optional token for resuming a long-running background operation. When present, indicates the operation is still in progress. additional_properties: Optional additional properties associated with the chat response update.