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/samples/getting_started/agents/openai/openai_assistants_basic.py
+2 -1
View File
@@ -5,10 +5,10 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
from agent_framework import tool
"""
OpenAI Assistants Basic Example
@@ -17,6 +17,7 @@ This sample demonstrates basic usage of OpenAIAssistantProvider with automatic
assistant lifecycle management, showing both streaming and non-streaming responses.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_assistants_provider_methods.py
+2 -1
View File
@@ -5,10 +5,10 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
from agent_framework import tool
"""
OpenAI Assistant Provider Methods Example
@@ -19,6 +19,7 @@ This sample demonstrates the methods available on the OpenAIAssistantProvider cl
- as_agent(): Wrap an SDK Assistant object without making HTTP calls
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_assistants_with_existing_assistant.py
+2 -1
View File
@@ -5,10 +5,10 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
from agent_framework import tool
"""
OpenAI Assistants with Existing Assistant Example
@@ -17,6 +17,7 @@ This sample demonstrates working with pre-existing OpenAI Assistants
using the provider's get_agent() and as_agent() methods.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py
+2 -1
View File
@@ -5,10 +5,10 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
from agent_framework import tool
"""
OpenAI Assistants with Explicit Settings Example
@@ -17,6 +17,7 @@ This sample demonstrates creating OpenAI Assistants with explicit configuration
settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_assistants_with_function_tools.py
+3 -1
View File
@@ -6,10 +6,10 @@ from datetime import datetime, timezone
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
from agent_framework import tool
"""
OpenAI Assistants with Function Tools Example
@@ -18,6 +18,7 @@ This sample demonstrates function tool integration with OpenAI Assistants,
showing both agent-level and query-level tool configuration patterns.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
@@ -27,6 +28,7 @@ def get_weather(
conditions = ["sunny", "cloudy", "rainy", "stormy"]
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}C."
@tool(approval_mode="never_require")
def get_time() -> str:
"""Get the current UTC time."""
python/samples/getting_started/agents/openai/openai_assistants_with_response_format.py
+6 -4
View File
@@ -59,13 +59,14 @@ async def main() -> None:
result1 = await agent.run(query1)
if weather := result1.try_parse_value(WeatherInfo):
try:
weather = result1.value
print("Agent:")
print(f" Location: {weather.location}")
print(f" Temperature: {weather.temperature}")
print(f" Conditions: {weather.conditions}")
print(f" Recommendation: {weather.recommendation}")
else:
except Exception:
print(f"Failed to parse response: {result1.text}")
# Request 2: Override response_format at runtime with CityInfo
@@ -75,12 +76,13 @@ async def main() -> None:
result2 = await agent.run(query2, options={"response_format": CityInfo})
if city := result2.try_parse_value(CityInfo):
try:
city = result2.value
print("Agent:")
print(f" City: {city.city_name}")
print(f" Population: {city.population}")
print(f" Country: {city.country}")
else:
except Exception:
print(f"Failed to parse response: {result2.text}")
finally:
await client.beta.assistants.delete(agent.id)
python/samples/getting_started/agents/openai/openai_assistants_with_thread.py
+2 -2
View File
@@ -5,8 +5,7 @@ import os
from random import randint
from typing import Annotated
from agent_framework import AgentThread
from agent_framework import tool
from agent_framework import AgentThread, tool
from agent_framework.openai import OpenAIAssistantProvider
from openai import AsyncOpenAI
from pydantic import Field
@@ -18,6 +17,7 @@ This sample demonstrates thread management with OpenAI Assistants, showing
persistent conversation threads and context preservation across interactions.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_chat_client_basic.py
+2 -1
View File
@@ -4,8 +4,8 @@ import asyncio
from random import randint
from typing import Annotated
from agent_framework.openai import OpenAIChatClient
from agent_framework import tool
from agent_framework.openai import OpenAIChatClient
"""
OpenAI Chat Client Basic Example
@@ -14,6 +14,7 @@ This sample demonstrates basic usage of OpenAIChatClient for direct chat-based
interactions, showing both streaming and non-streaming responses.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_chat_client_with_explicit_settings.py
+2 -1
View File
@@ -5,9 +5,9 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIChatClient
from pydantic import Field
from agent_framework import tool
"""
OpenAI Chat Client with Explicit Settings Example
@@ -16,6 +16,7 @@ This sample demonstrates creating OpenAI Chat Client with explicit configuration
settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_chat_client_with_function_tools.py
+3 -2
View File
@@ -5,8 +5,7 @@ from datetime import datetime, timezone
from random import randint
from typing import Annotated
from agent_framework import ChatAgent
from agent_framework import tool
from agent_framework import ChatAgent, tool
from agent_framework.openai import OpenAIChatClient
from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates function tool integration with OpenAI Chat Client,
showing both agent-level and query-level tool configuration patterns.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
@@ -26,6 +26,7 @@ def get_weather(
conditions = ["sunny", "cloudy", "rainy", "stormy"]
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
@tool(approval_mode="never_require")
def get_time() -> str:
"""Get the current UTC time."""
python/samples/getting_started/agents/openai/openai_chat_client_with_thread.py
+2 -2
View File
@@ -4,8 +4,7 @@ import asyncio
from random import randint
from typing import Annotated
from agent_framework import AgentThread, ChatAgent, ChatMessageStore
from agent_framework import tool
from agent_framework import AgentThread, ChatAgent, ChatMessageStore, tool
from agent_framework.openai import OpenAIChatClient
from pydantic import Field
@@ -16,6 +15,7 @@ This sample demonstrates thread management with OpenAI Chat Client, showing
conversation threads and message history preservation across interactions.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_responses_client_basic.py
+2 -2
View File
@@ -4,8 +4,7 @@ import asyncio
from random import randint
from typing import Annotated
from agent_framework import ChatAgent
from agent_framework import tool
from agent_framework import ChatAgent, tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field
@@ -16,6 +15,7 @@ This sample demonstrates basic usage of OpenAIResponsesClient for structured
response generation, showing both streaming and non-streaming responses.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter.py
-1
View File
@@ -8,7 +8,6 @@ from agent_framework import (
CodeInterpreterToolResultContent,
Content,
HostedCodeInterpreterTool,
tool,
)
from agent_framework.openai import OpenAIResponsesClient
python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py
+2 -1
View File
@@ -5,9 +5,9 @@ import os
from random import randint
from typing import Annotated
from agent_framework import tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field
from agent_framework import tool
"""
OpenAI Responses Client with Explicit Settings Example
@@ -16,6 +16,7 @@ This sample demonstrates creating OpenAI Responses Client with explicit configur
settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py
+3 -2
View File
@@ -5,8 +5,7 @@ from datetime import datetime, timezone
from random import randint
from typing import Annotated
from agent_framework import ChatAgent
from agent_framework import tool
from agent_framework import ChatAgent, tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field
@@ -17,6 +16,7 @@ This sample demonstrates function tool integration with OpenAI Responses Client,
showing both agent-level and query-level tool configuration patterns.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
@@ -26,6 +26,7 @@ def get_weather(
conditions = ["sunny", "cloudy", "rainy", "stormy"]
return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
@tool(approval_mode="never_require")
def get_time() -> str:
"""Get the current UTC time."""
python/samples/getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py
+3 -3
View File
@@ -29,10 +29,10 @@ async def handle_approvals_without_thread(query: str, agent: "AgentProtocol"):
f"User Input Request for function from {agent.name}: {user_input_needed.function_call.name}"
f" with arguments: {user_input_needed.function_call.arguments}"
)
new_inputs.append(ChatMessage(role="assistant", contents=[user_input_needed]))
new_inputs.append(ChatMessage("assistant", [user_input_needed]))
user_approval = input("Approve function call? (y/n): ")
new_inputs.append(
ChatMessage(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
ChatMessage("user", [user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
)
result = await agent.run(new_inputs)
@@ -70,7 +70,7 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "AgentProtoc
new_input_added = True
while new_input_added:
new_input_added = False
new_input.append(ChatMessage(role="user", text=query))
new_input.append(ChatMessage("user", [query]))
async for update in agent.run_stream(new_input, thread=thread, store=True):
if update.user_input_requests:
for user_input_needed in update.user_input_requests:
python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py
+2 -2
View File
@@ -4,8 +4,7 @@ import asyncio
from random import randint
from typing import Annotated
from agent_framework import AgentThread, ChatAgent
from agent_framework import tool
from agent_framework import AgentThread, ChatAgent, tool
from agent_framework.openai import OpenAIResponsesClient
from pydantic import Field
@@ -16,6 +15,7 @@ This sample demonstrates thread management with OpenAI Responses Client, showing
persistent conversation context and simplified response handling.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(