agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Python: [BREAKING] Types API Review improvements (#3647)

Browse Source 
* Replace Role and FinishReason classes with NewType + Literal

- Remove EnumLike metaclass from _types.py
- Replace Role class with NewType('Role', str) + RoleLiteral
- Replace FinishReason class with NewType('FinishReason', str) + FinishReasonLiteral
- Update all usages across codebase to use string literals
- Remove .value access patterns (direct string comparison now works)
- Add backward compatibility for legacy dict serialization format
- Update tests to reflect new string-based types

Addresses #3591, #3615

* Simplify ChatResponse and AgentResponse type hints (#3592)

- Remove overloads from ChatResponse.__init__
- Remove text parameter from ChatResponse.__init__
- Remove | dict[str, Any] from finish_reason and usage_details params
- Remove **kwargs from AgentResponse.__init__
- Both now accept ChatMessage | Sequence[ChatMessage] | None for messages
- Update docstrings and examples to reflect changes
- Fix tests that were using removed kwargs
- Fix Role type hint usage in ag-ui utils

* Remove text parameter from ChatResponseUpdate and AgentResponseUpdate (#3597)

- Remove text parameter from ChatResponseUpdate.__init__
- Remove text parameter from AgentResponseUpdate.__init__
- Remove **kwargs from both update classes
- Simplify contents parameter type to Sequence[Content] | None
- Update all usages to use contents=[Content.from_text(...)] pattern
- Fix imports in test files
- Update docstrings and examples

* Rename from_chat_response_updates to from_updates (#3593)

- ChatResponse.from_chat_response_updates → ChatResponse.from_updates
- ChatResponse.from_chat_response_generator → ChatResponse.from_update_generator
- AgentResponse.from_agent_run_response_updates → AgentResponse.from_updates

* Remove try_parse_value method from ChatResponse and AgentResponse (#3595)

- Remove try_parse_value method from ChatResponse
- Remove try_parse_value method from AgentResponse
- Remove try_parse_value calls from from_updates and from_update_generator methods
- Update samples to use try/except with response.value instead
- Update tests to use response.value pattern
- Users should now use response.value with try/except for safe parsing

* Add agent_id to AgentResponse and clarify author_name documentation (#3596)

- Add agent_id parameter to AgentResponse class
- Document that author_name is on ChatMessage objects, not responses
- Update ChatResponse docstring with author_name note
- Update AgentResponse docstring with author_name note

* Simplify ChatMessage.__init__ signature (#3618)

- Make contents a positional argument accepting Sequence[Content | str]
- Auto-convert strings in contents to TextContent
- Remove overloads, keep text kwarg for backward compatibility with serialization
- Update _parse_content_list to handle string items
- Update all usages across codebase to use new format: ChatMessage("role", ["text"])

* Allow Content as input on run and get_response

- Update prepare_messages and normalize_messages to accept Content
- Update type signatures in _agents.py and _clients.py
- Add tests for Content input handling

* Fix ChatMessage usage across packages and samples

Update all remaining ChatMessage(role=..., text=...) to use new
ChatMessage('role', ['text']) signature.

* Fix Role string usage and response format parsing

- Fix redis provider: remove .value access on string literals
- Fix durabletask ensure_response_format: set _response_format before accessing .value

* Fix ollama .value and ai_model_id issues, handle None in content list

- Fix ollama _chat_client: remove .value on string literals
- Fix ollama _chat_client: rename ai_model_id to model_id
- Fix _parse_content_list: skip None values gracefully

* Fix A2AAgent type signature to include Content

* Fix Role/FinishReason NewType dict annotations and improve test coverage to 95%

* Fix mypy errors for Role/FinishReason NewType usage

* Fix Role.TOOL and Role.ASSISTANT usage in _orchestrator_helpers.py

* Fix Role NewType usage in durabletask _models.py
This commit is contained in:
Eduard van Valkenburg
2026-02-04 11:13:23 +01:00
committed by GitHub
Unverified
parent ef798629e5
commit 838a7fd61d
341 changed files with 3766 additions and 3228 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/packages/durabletask/agent_framework_durabletask/_durable_agent_state.py
+2 -2
View File
@@ -797,7 +797,7 @@ class DurableAgentStateMessage:
DurableAgentStateMessage with converted content items and metadata
"""
return DurableAgentStateMessage(
role=request.role.value,
role=request.role,
contents=[DurableAgentStateTextContent(text=request.message)],
created_at=_parse_created_at(request.created_at) if request.created_at else None,
)
@@ -817,7 +817,7 @@ class DurableAgentStateMessage:
]
return DurableAgentStateMessage(
role=chat_message.role.value,
role=chat_message.role,
contents=contents_list,
author_name=chat_message.author_name,
extension_data=dict(chat_message.additional_properties) if chat_message.additional_properties else None,
python/packages/durabletask/agent_framework_durabletask/_entities.py
+2 -3
View File
@@ -14,7 +14,6 @@ from agent_framework import (
AgentResponseUpdate,
ChatMessage,
Content,
Role,
get_logger,
)
from durabletask.entities import DurableEntity
@@ -176,7 +175,7 @@ class AgentEntity:
logger.exception("[AgentEntity.run] Agent execution failed.")
error_message = ChatMessage(
role=Role.ASSISTANT, contents=[Content.from_error(message=str(exc), error_code=type(exc).__name__)]
role="assistant", contents=[Content.from_error(message=str(exc), error_code=type(exc).__name__)]
)
error_response = AgentResponse(messages=[error_message])
@@ -247,7 +246,7 @@ class AgentEntity:
await self._notify_stream_update(update, callback_context)
if updates:
response = AgentResponse.from_agent_run_response_updates(updates)
response = AgentResponse.from_updates(updates)
else:
logger.debug("[AgentEntity] No streaming updates received; creating empty response")
response = AgentResponse(messages=[])
python/packages/durabletask/agent_framework_durabletask/_executors.py
+4 -4
View File
@@ -16,7 +16,7 @@ from abc import ABC, abstractmethod
from datetime import datetime, timezone
from typing import Any, Generic, TypeVar
from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, Role, get_logger
from agent_framework import AgentResponse, AgentThread, ChatMessage, Content, get_logger
from durabletask.client import TaskHubGrpcClient
from durabletask.entities import EntityInstanceId
from durabletask.task import CompletableTask, CompositeTask, OrchestrationContext, Task
@@ -180,7 +180,7 @@ class DurableAgentExecutor(ABC, Generic[TaskT]):
AgentResponse: Acceptance response with correlation ID
"""
acceptance_message = ChatMessage(
role=Role.SYSTEM,
role="system",
contents=[
Content.from_text(
f"Request accepted for processing (correlation_id: {correlation_id}). "
@@ -361,7 +361,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
correlation_id,
)
error_message = ChatMessage(
role=Role.SYSTEM,
role="system",
contents=[
Content.from_error(
message=f"Error processing agent response: {e}",
@@ -376,7 +376,7 @@ class ClientAgentExecutor(DurableAgentExecutor[AgentResponse]):
correlation_id,
)
error_message = ChatMessage(
role=Role.SYSTEM,
role="system",
contents=[
Content.from_error(
message=f"Timeout waiting for agent response after {self.max_poll_retries} attempts",
python/packages/durabletask/agent_framework_durabletask/_models.py
+9 -11
View File
@@ -16,7 +16,7 @@ from datetime import datetime, timezone
from importlib import import_module
from typing import TYPE_CHECKING, Any, cast
from agent_framework import AgentThread, Role
from agent_framework import AgentThread
from ._constants import REQUEST_RESPONSE_FORMAT_TEXT
@@ -115,7 +115,7 @@ class RunRequest:
message: str
request_response_format: str
correlation_id: str
role: Role = Role.USER
role: str = "user"
response_format: type[BaseModel] | None = None
enable_tool_calls: bool = True
wait_for_response: bool = True
@@ -128,7 +128,7 @@ class RunRequest:
message: str,
correlation_id: str,
request_response_format: str = REQUEST_RESPONSE_FORMAT_TEXT,
role: Role | str | None = Role.USER,
role: str | None = "user",
response_format: type[BaseModel] | None = None,
enable_tool_calls: bool = True,
wait_for_response: bool = True,
@@ -148,16 +148,14 @@ class RunRequest:
self.options = options if options is not None else {}
@staticmethod
def coerce_role(value: Role | str | None) -> Role:
"""Normalize various role representations into a Role instance."""
if isinstance(value, Role):
return value
def coerce_role(value: str | None) -> str:
"""Normalize various role representations into a role string."""
if isinstance(value, str):
normalized = value.strip()
if not normalized:
return Role.USER
return Role(value=normalized.lower())
return Role.USER
return "user"
return normalized.lower()
return "user"
def to_dict(self) -> dict[str, Any]:
"""Convert to dictionary for JSON serialization."""
@@ -165,7 +163,7 @@ class RunRequest:
"message": self.message,
"enable_tool_calls": self.enable_tool_calls,
"wait_for_response": self.wait_for_response,
"role": self.role.value,
"role": self.role,
"request_response_format": self.request_response_format,
"correlationId": self.correlation_id,
"options": self.options,
python/packages/durabletask/agent_framework_durabletask/_response_utils.py
+5 -2
View File
@@ -55,9 +55,12 @@ def ensure_response_format(
Raises:
ValueError: If response_format is specified but response.value cannot be parsed
"""
if response_format is not None and not isinstance(response.value, response_format):
response.try_parse_value(response_format)
if response_format is not None:
# Set the response format on the response so .value knows how to parse
response._response_format = response_format
response._value_parsed = False # Reset to allow re-parsing with new format
# Access response.value to trigger parsing (may raise ValidationError)
# Validate that parsing succeeded
if not isinstance(response.value, response_format):
raise ValueError(
python/packages/durabletask/tests/test_durable_entities.py
+6 -8
View File
@@ -11,7 +11,7 @@ from typing import Any, TypeVar
from unittest.mock import AsyncMock, Mock
import pytest
from agent_framework import AgentResponse, AgentResponseUpdate, ChatMessage, Content, Role
from agent_framework import AgentResponse, AgentResponseUpdate, ChatMessage, Content
from pydantic import BaseModel
from agent_framework_durabletask import (
@@ -81,9 +81,7 @@ def _role_value(chat_message: DurableAgentStateMessage) -> str:
def _agent_response(text: str | None) -> AgentResponse:
"""Create an AgentResponse with a single assistant message."""
message = (
ChatMessage(role="assistant", text=text) if text is not None else ChatMessage(role="assistant", contents=[])
)
message = ChatMessage("assistant", [text]) if text is not None else ChatMessage("assistant", [])
return AgentResponse(messages=[message])
@@ -222,8 +220,8 @@ class TestAgentEntityRunAgent:
async def test_run_agent_streaming_callbacks_invoked(self) -> None:
"""Ensure streaming updates trigger callbacks and run() is not used."""
updates = [
AgentResponseUpdate(text="Hello"),
AgentResponseUpdate(text=" world"),
AgentResponseUpdate(contents=[Content.from_text(text="Hello")]),
AgentResponseUpdate(contents=[Content.from_text(text=" world")]),
]
async def update_generator() -> AsyncIterator[AgentResponseUpdate]:
@@ -595,7 +593,7 @@ class TestRunRequestSupport:
request = RunRequest(
message="Test message",
role=Role.USER,
role="user",
enable_tool_calls=True,
correlation_id="corr-runreq-1",
)
@@ -644,7 +642,7 @@ class TestRunRequestSupport:
# Send as system role
request = RunRequest(
message="System message",
role=Role.SYSTEM,
role="system",
correlation_id="corr-runreq-3",
)
python/packages/durabletask/tests/test_executors.py
+6 -6
View File
@@ -11,7 +11,7 @@ from typing import Any
from unittest.mock import Mock
import pytest
from agent_framework import AgentResponse, Role
from agent_framework import AgentResponse
from durabletask.entities import EntityInstanceId
from durabletask.task import Task
from pydantic import BaseModel
@@ -241,7 +241,7 @@ class TestClientAgentExecutorFireAndForget:
# Verify it contains an acceptance message
assert isinstance(result, AgentResponse)
assert len(result.messages) == 1
assert result.messages[0].role == Role.SYSTEM
assert result.messages[0].role == "system"
# Check message contains key information
message_text = result.messages[0].text
assert "accepted" in message_text.lower()
@@ -294,7 +294,7 @@ class TestOrchestrationAgentExecutorFireAndForget:
response = result.get_result()
assert isinstance(response, AgentResponse)
assert len(response.messages) == 1
assert response.messages[0].role == Role.SYSTEM
assert response.messages[0].role == "system"
assert "test-789" in response.messages[0].text
def test_orchestration_blocking_mode_calls_call_entity(self, mock_orchestration_context: Mock) -> None:
@@ -392,7 +392,7 @@ class TestDurableAgentTask:
result = task.get_result()
assert isinstance(result, AgentResponse)
assert len(result.messages) == 1
assert result.messages[0].role == Role.ASSISTANT
assert result.messages[0].role == "assistant"
def test_durable_agent_task_propagates_failure(self, configure_failed_entity_task: Any) -> None:
"""Verify DurableAgentTask propagates task failures."""
@@ -519,8 +519,8 @@ class TestDurableAgentTask:
result = task.get_result()
assert isinstance(result, AgentResponse)
assert len(result.messages) == 2
assert result.messages[0].role == Role.ASSISTANT
assert result.messages[1].role == Role.ASSISTANT
assert result.messages[0].role == "assistant"
assert result.messages[1].role == "assistant"
def test_durable_agent_task_is_not_complete_initially(self, mock_entity_task: Mock) -> None:
"""Verify DurableAgentTask is not complete when first created."""
python/packages/durabletask/tests/test_models.py
+13 -14
View File
@@ -3,7 +3,6 @@
"""Unit tests for data models (RunRequest)."""
import pytest
from agent_framework import Role
from pydantic import BaseModel
from agent_framework_durabletask._models import RunRequest
@@ -22,7 +21,7 @@ class TestRunRequest:
assert request.message == "Hello"
assert request.correlation_id == "corr-001"
assert request.role == Role.USER
assert request.role == "user"
assert request.response_format is None
assert request.enable_tool_calls is True
assert request.wait_for_response is True
@@ -33,7 +32,7 @@ class TestRunRequest:
request = RunRequest(
message="Hello",
correlation_id="corr-002",
role=Role.SYSTEM,
role="system",
response_format=schema,
enable_tool_calls=False,
wait_for_response=False,
@@ -41,7 +40,7 @@ class TestRunRequest:
assert request.message == "Hello"
assert request.correlation_id == "corr-002"
assert request.role == Role.SYSTEM
assert request.role == "system"
assert request.response_format is schema
assert request.enable_tool_calls is False
assert request.wait_for_response is False
@@ -50,7 +49,7 @@ class TestRunRequest:
"""Ensure string role values are coerced into Role instances."""
request = RunRequest(message="Hello", correlation_id="corr-003", role="system") # type: ignore[arg-type]
assert request.role == Role.SYSTEM
assert request.role == "system"
def test_to_dict_with_defaults(self) -> None:
"""Test to_dict with default values."""
@@ -71,7 +70,7 @@ class TestRunRequest:
request = RunRequest(
message="Hello",
correlation_id="corr-005",
role=Role.ASSISTANT,
role="assistant",
response_format=schema,
enable_tool_calls=False,
wait_for_response=False,
@@ -95,7 +94,7 @@ class TestRunRequest:
assert request.message == "Hello"
assert request.correlation_id == "corr-006"
assert request.role == Role.USER
assert request.role == "user"
assert request.enable_tool_calls is True
assert request.wait_for_response is True
@@ -122,7 +121,7 @@ class TestRunRequest:
assert request.message == "Test"
assert request.correlation_id == "corr-008"
assert request.role == Role.SYSTEM
assert request.role == "system"
assert request.response_format is ModuleStructuredResponse
assert request.enable_tool_calls is False
@@ -131,8 +130,8 @@ class TestRunRequest:
data = {"message": "Test", "correlationId": "corr-009", "role": "reviewer"}
request = RunRequest.from_dict(data)
assert request.role.value == "reviewer"
assert request.role != Role.USER
assert request.role == "reviewer"
assert request.role != "user"
def test_from_dict_empty_message(self) -> None:
"""Test from_dict with empty message."""
@@ -140,7 +139,7 @@ class TestRunRequest:
assert request.message == ""
assert request.correlation_id == "corr-010"
assert request.role == Role.USER
assert request.role == "user"
def test_from_dict_missing_correlation_id_raises(self) -> None:
"""Test from_dict raises when correlationId is missing."""
@@ -152,7 +151,7 @@ class TestRunRequest:
original = RunRequest(
message="Test message",
correlation_id="corr-011",
role=Role.SYSTEM,
role="system",
response_format=ModuleStructuredResponse,
enable_tool_calls=False,
)
@@ -232,7 +231,7 @@ class TestRunRequest:
"""Test round-trip to_dict and from_dict with correlationId."""
original = RunRequest(
message="Test message",
role=Role.SYSTEM,
role="system",
correlation_id="corr-124",
)
@@ -292,7 +291,7 @@ class TestRunRequest:
"""Test round-trip to_dict and from_dict with orchestration_id."""
original = RunRequest(
message="Test message",
role=Role.SYSTEM,
role="system",
correlation_id="corr-129",
orchestration_id="orch-123",
)
python/packages/durabletask/tests/test_shim.py
+3 -3
View File
@@ -77,7 +77,7 @@ class TestDurableAIAgentMessageNormalization:
def test_run_accepts_chat_message(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
"""Verify run accepts and normalizes ChatMessage objects."""
chat_msg = ChatMessage(role="user", text="Test message")
chat_msg = ChatMessage("user", ["Test message"])
test_agent.run(chat_msg)
mock_executor.run_durable_agent.assert_called_once()
@@ -95,8 +95,8 @@ class TestDurableAIAgentMessageNormalization:
def test_run_accepts_list_of_chat_messages(self, test_agent: DurableAIAgent[Any], mock_executor: Mock) -> None:
"""Verify run accepts and joins list of ChatMessage objects."""
messages = [
ChatMessage(role="user", text="Message 1"),
ChatMessage(role="assistant", text="Message 2"),
ChatMessage("user", ["Message 1"]),
ChatMessage("assistant", ["Message 2"]),
]
test_agent.run(messages)