agent/agent-framework
1
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] Simplify API: ChatAgent -> Agent, ChatMessage -> Message (#3747)

Browse Source 
* [BREAKING] Rename ChatAgent -> Agent, ChatMessage -> Message, ChatClientProtocol -> SupportsChatGetResponse

Simplify the public API by removing redundant 'Chat' prefix from core types:
- ChatAgent -> Agent
- RawChatAgent -> RawAgent
- ChatMessage -> Message
- ChatClientProtocol -> SupportsChatGetResponse

Also renamed internal WorkflowMessage (was Message in _runner_context) to avoid collision.

No backward compatibility aliases - this is a clean breaking change.

* [BREAKING] Rename Agent chat_client parameter to client

* Fix rebase issues: WorkflowMessage references and broken markdown links

* Fix formatting and lint issues from code quality checks

* Fix import ordering in workflow sample files

* fixed rebase

* Fix test failures: use WorkflowMessage and A2AMessage after ChatMessage→Message rename

- Replace Message(data=..., source_id=...) with WorkflowMessage(...) in workflow tests
- Fix isinstance check in A2A agent to use A2AMessage instead of Message
- Fix import in test_workflow_observability.py (Message→WorkflowMessage)

* Fix lint, fmt, and sample errors after ChatMessage→Message rename

- Auto-fix 70+ ruff lint issues across samples (ChatMessage→Message refs)
- Fix HostedVectorStoreContent→Content.from_hosted_vector_store in file search sample
- Fix _normalize_messages→normalize_messages in custom agent sample
- Fix context.terminate→raise MiddlewareTermination in middleware samples
- Fix with_update_hook→with_transform_hook in override middleware sample
- Add TOptions_co import back to custom_chat_client sample
- Add noqa for FastAPI File() default in chatkit sample
- Fix B023 loop variable capture in weather agent sample

* fix: update Agent constructor calls from chat_client to client in declaration-only tool tests

* fix: add register_cleanup to devui lazy-loading proxy and type stub

* fixed tests and updated new pieces

* fix agui typevar

* fix merge errors

* fix merge conflicts

* fiux merge

* Remove unused links

---------

Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
This commit is contained in:
Eduard van Valkenburg
2026-02-11 00:04:32 +01:00
committed by GitHub
Unverified
parent a4c9e43afb
commit 0521f5bed8
418 changed files with 5385 additions and 5389 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/packages/chatkit/README.md
+5 -5
View File
@@ -7,9 +7,9 @@ Specifically, it mirrors the [Agent SDK integration](https://github.com/openai/c
- `stream_agent_response`: A helper to convert a streamed `AgentResponseUpdate`
from a Microsoft Agent Framework agent that implements `SupportsAgentRun` to ChatKit events.
- `ThreadItemConverter`: A extendable helper class to convert ChatKit thread items to
`ChatMessage` objects that can be consumed by an Agent Framework agent.
`Message` objects that can be consumed by an Agent Framework agent.
- `simple_to_agent_input`: A helper function that uses the default implementation
of `ThreadItemConverter` to convert a ChatKit thread to a list of `ChatMessage`,
of `ThreadItemConverter` to convert a ChatKit thread to a list of `Message`,
useful for getting started quickly.
## Installation
@@ -63,7 +63,7 @@ from azure.identity import AzureCliCredential
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse
from agent_framework import ChatAgent
from agent_framework import Agent
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework.chatkit import simple_to_agent_input, stream_agent_response
@@ -74,8 +74,8 @@ from chatkit.types import ThreadMetadata, UserMessageItem, ThreadStreamEvent
from your_store import YourStore # type: ignore[import-not-found] # Replace with your Store implementation
# Define your agent with tools
agent = ChatAgent(
chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
agent = Agent(
client=AzureOpenAIChatClient(credential=AzureCliCredential()),
instructions="You are a helpful assistant.",
tools=[], # Add your tools here
)
python/packages/chatkit/agent_framework_chatkit/_converter.py
+45 -47
View File
@@ -9,8 +9,8 @@ import sys
from collections.abc import Awaitable, Callable, Sequence
from agent_framework import (
ChatMessage,
Content,
Message,
)
from chatkit.types import (
AssistantMessageItem,
@@ -39,7 +39,7 @@ logger = logging.getLogger(__name__)
class ThreadItemConverter:
"""Helper class to convert ChatKit thread items to Agent Framework ChatMessage objects.
"""Helper class to convert ChatKit thread items to Agent Framework Message objects.
This class provides a base implementation for converting ChatKit thread items
to Agent Framework messages. It can be extended to handle attachments,
@@ -64,8 +64,8 @@ class ThreadItemConverter:
async def user_message_to_input(
self, item: UserMessageItem, is_last_message: bool = True
) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit UserMessageItem to Agent Framework ChatMessage(s).
) -> Message | list[Message] | None:
"""Convert a ChatKit UserMessageItem to Agent Framework Message(s).
This method is called internally by `to_agent_input()`. Override this method
to customize how user messages are converted.
@@ -75,7 +75,7 @@ class ThreadItemConverter:
is_last_message: Whether this is the last message in the thread (used for quoted_text handling).
Returns:
A ChatMessage, list of messages, or None to skip.
A Message, list of messages, or None to skip.
Note:
Instead of calling this method directly, use `to_agent_input()` which handles
@@ -102,19 +102,19 @@ class ThreadItemConverter:
# If only text and no attachments, use text parameter for simplicity
if text_content.strip() and not data_contents:
user_message = ChatMessage(role="user", text=text_content.strip())
user_message = Message(role="user", text=text_content.strip())
else:
# Build contents list with both text and attachments
contents: list[Content] = []
if text_content.strip():
contents.append(Content.from_text(text=text_content.strip()))
contents.extend(data_contents)
user_message = ChatMessage(role="user", contents=contents)
user_message = Message(role="user", contents=contents)
# Handle quoted text if this is the last message
messages = [user_message]
if item.quoted_text and is_last_message:
quoted_context = ChatMessage(
quoted_context = Message(
role="user",
text=f"The user is referring to this in particular:\n{item.quoted_text}",
)
@@ -179,10 +179,8 @@ class ThreadItemConverter:
# Subclasses can override this method to provide custom handling
return None
def hidden_context_to_input(
self, item: HiddenContextItem | SDKHiddenContextItem
) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit HiddenContextItem or SDKHiddenContextItem to Agent Framework ChatMessage(s).
def hidden_context_to_input(self, item: HiddenContextItem | SDKHiddenContextItem) -> Message | list[Message] | None:
"""Convert a ChatKit HiddenContextItem or SDKHiddenContextItem to Agent Framework Message(s).
This method is called internally by `to_agent_input()`. Override this method
to customize how hidden context is converted.
@@ -195,7 +193,7 @@ class ThreadItemConverter:
item: The ChatKit hidden context item to convert.
Returns:
A ChatMessage with system role, a list of messages, or None to skip.
A Message with system role, a list of messages, or None to skip.
Note:
Instead of calling this method directly, use `to_agent_input()` which handles
@@ -213,9 +211,9 @@ class ThreadItemConverter:
content="User's email: user@example.com",
)
message = converter.hidden_context_to_input(hidden_item)
# Returns: ChatMessage(role=SYSTEM, text="<HIDDEN_CONTEXT>User's email: ...</HIDDEN_CONTEXT>")
# Returns: Message(role=SYSTEM, text="<HIDDEN_CONTEXT>User's email: ...</HIDDEN_CONTEXT>")
"""
return ChatMessage(role="system", text=f"<HIDDEN_CONTEXT>{item.content}</HIDDEN_CONTEXT>")
return Message(role="system", text=f"<HIDDEN_CONTEXT>{item.content}</HIDDEN_CONTEXT>")
def tag_to_message_content(self, tag: UserMessageTagContent) -> Content:
"""Convert a ChatKit tag (@-mention) to Agent Framework content.
@@ -250,8 +248,8 @@ class ThreadItemConverter:
name = getattr(tag.data, "name", tag.text if hasattr(tag, "text") else "unknown")
return Content.from_text(text=f"<TAG>Name:{name}</TAG>")
def task_to_input(self, item: TaskItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit TaskItem to Agent Framework ChatMessage(s).
def task_to_input(self, item: TaskItem) -> Message | list[Message] | None:
"""Convert a ChatKit TaskItem to Agent Framework Message(s).
This method is called internally by `to_agent_input()`. Override this method
to customize how tasks are converted.
@@ -263,7 +261,7 @@ class ThreadItemConverter:
item: The ChatKit task item to convert.
Returns:
A ChatMessage, a list of messages, or None to skip the task.
A Message, a list of messages, or None to skip the task.
Note:
Instead of calling this method directly, use `to_agent_input()` which handles
@@ -294,10 +292,10 @@ class ThreadItemConverter:
f"A message was displayed to the user that the following task was performed:\n<Task>\n{task_text}\n</Task>"
)
return ChatMessage(role="user", text=text)
return Message(role="user", text=text)
def workflow_to_input(self, item: WorkflowItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit WorkflowItem to Agent Framework ChatMessage(s).
def workflow_to_input(self, item: WorkflowItem) -> Message | list[Message] | None:
"""Convert a ChatKit WorkflowItem to Agent Framework Message(s).
This method is called internally by `to_agent_input()`. Override this method
to customize how workflows are converted.
@@ -336,7 +334,7 @@ class ThreadItemConverter:
messages = converter.workflow_to_input(workflow_item)
# Returns list of messages for each task
"""
messages: list[ChatMessage] = []
messages: list[Message] = []
for task in item.workflow.tasks:
if task.type != "custom" or (not task.title and not task.content):
continue
@@ -349,12 +347,12 @@ class ThreadItemConverter:
f"<Task>\n{task_text}\n</Task>"
)
messages.append(ChatMessage(role="user", text=text))
messages.append(Message(role="user", text=text))
return messages if messages else None
def widget_to_input(self, item: WidgetItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit WidgetItem to Agent Framework ChatMessage(s).
def widget_to_input(self, item: WidgetItem) -> Message | list[Message] | None:
"""Convert a ChatKit WidgetItem to Agent Framework Message(s).
This method is called internally by `to_agent_input()`. Override this method
to customize how widgets are converted.
@@ -367,7 +365,7 @@ class ThreadItemConverter:
item: The ChatKit widget item to convert.
Returns:
A ChatMessage describing the widget, or None to skip.
A Message describing the widget, or None to skip.
Note:
Instead of calling this method directly, use `to_agent_input()` which handles
@@ -391,13 +389,13 @@ class ThreadItemConverter:
try:
widget_json = item.widget.model_dump_json(exclude_unset=True, exclude_none=True)
text = f"The following graphical UI widget (id: {item.id}) was displayed to the user:{widget_json}"
return ChatMessage(role="user", text=text)
return Message(role="user", text=text)
except Exception:
# If JSON serialization fails, skip the widget
return None
async def assistant_message_to_input(self, item: AssistantMessageItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit AssistantMessageItem to Agent Framework ChatMessage(s).
async def assistant_message_to_input(self, item: AssistantMessageItem) -> Message | list[Message] | None:
"""Convert a ChatKit AssistantMessageItem to Agent Framework Message(s).
The default implementation extracts text from all content parts and creates
an assistant message.
@@ -406,7 +404,7 @@ class ThreadItemConverter:
item: The ChatKit assistant message item to convert.
Returns:
A ChatMessage with assistant role, or None to skip.
A Message with assistant role, or None to skip.
Note:
Instead of calling this method directly, use `to_agent_input()` which handles
@@ -417,10 +415,10 @@ class ThreadItemConverter:
if not text_parts:
return None
return ChatMessage(role="assistant", text="".join(text_parts))
return Message(role="assistant", text="".join(text_parts))
async def client_tool_call_to_input(self, item: ClientToolCallItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit ClientToolCallItem to Agent Framework ChatMessage(s).
async def client_tool_call_to_input(self, item: ClientToolCallItem) -> Message | list[Message] | None:
"""Convert a ChatKit ClientToolCallItem to Agent Framework Message(s).
The default implementation converts completed tool calls into function call
and result content.
@@ -442,7 +440,7 @@ class ThreadItemConverter:
import json
# Create function call message
function_call_msg = ChatMessage(
function_call_msg = Message(
role="assistant",
contents=[
Content.from_function_call(
@@ -454,7 +452,7 @@ class ThreadItemConverter:
)
# Create function result message
function_result_msg = ChatMessage(
function_result_msg = Message(
role="tool",
contents=[
Content.from_function_result(
@@ -466,8 +464,8 @@ class ThreadItemConverter:
return [function_call_msg, function_result_msg]
async def end_of_turn_to_input(self, item: EndOfTurnItem) -> ChatMessage | list[ChatMessage] | None:
"""Convert a ChatKit EndOfTurnItem to Agent Framework ChatMessage(s).
async def end_of_turn_to_input(self, item: EndOfTurnItem) -> Message | list[Message] | None:
"""Convert a ChatKit EndOfTurnItem to Agent Framework Message(s).
The default implementation skips end-of-turn markers as they are only UI hints.
@@ -488,15 +486,15 @@ class ThreadItemConverter:
self,
item: ThreadItem,
is_last_message: bool = True,
) -> list[ChatMessage]:
"""Internal method to convert a single ThreadItem to ChatMessage(s).
) -> list[Message]:
"""Internal method to convert a single ThreadItem to Message(s).
Args:
item: The thread item to convert.
is_last_message: Whether this is the last item in the thread.
Returns:
A list of ChatMessage objects (may be empty).
A list of Message objects (may be empty).
"""
match item:
case UserMessageItem():
@@ -535,7 +533,7 @@ class ThreadItemConverter:
async def to_agent_input(
self,
thread_items: Sequence[ThreadItem] | ThreadItem,
) -> list[ChatMessage]:
) -> list[Message]:
"""Convert ChatKit thread items to Agent Framework ChatMessages.
This is the main entry point for converting ChatKit thread items. It handles
@@ -546,7 +544,7 @@ class ThreadItemConverter:
thread_items: A single ThreadItem or a sequence of ThreadItems to convert.
Returns:
A list of ChatMessage objects that can be sent to an Agent Framework agent.
A list of Message objects that can be sent to an Agent Framework agent.
Examples:
.. code-block:: python
@@ -562,14 +560,14 @@ class ThreadItemConverter:
messages = await converter.to_agent_input([user_message_item, assistant_message_item, task_item])
# Use with agent
from agent_framework import ChatAgent
from agent_framework import Agent
agent = ChatAgent(...)
agent = Agent(...)
response = await agent.run(messages)
"""
thread_items = list(thread_items) if isinstance(thread_items, Sequence) else [thread_items]
output: list[ChatMessage] = []
output: list[Message] = []
for item in thread_items:
output.extend(
await self._thread_item_to_input_item(
@@ -584,7 +582,7 @@ class ThreadItemConverter:
_DEFAULT_CONVERTER = ThreadItemConverter()
async def simple_to_agent_input(thread_items: Sequence[ThreadItem] | ThreadItem) -> list[ChatMessage]:
async def simple_to_agent_input(thread_items: Sequence[ThreadItem] | ThreadItem) -> list[Message]:
"""Helper function that uses the default ThreadItemConverter.
This function provides a quick way to get started with ChatKit integration
@@ -594,7 +592,7 @@ async def simple_to_agent_input(thread_items: Sequence[ThreadItem] | ThreadItem)
thread_items: A single ThreadItem or a sequence of ThreadItems to convert.
Returns:
A list of ChatMessage objects that can be sent to an Agent Framework agent.
A list of Message objects that can be sent to an Agent Framework agent.
Examples:
.. code-block:: python
python/packages/chatkit/tests/test_converter.py
+10 -10
View File
@@ -5,7 +5,7 @@
from unittest.mock import Mock
import pytest
from agent_framework import ChatMessage
from agent_framework import Message
from chatkit.types import UserMessageTextContent
from agent_framework_chatkit import ThreadItemConverter, simple_to_agent_input
@@ -43,7 +43,7 @@ class TestThreadItemConverter:
result = await converter.to_agent_input(input_item)
assert len(result) == 1
assert isinstance(result[0], ChatMessage)
assert isinstance(result[0], Message)
assert result[0].role == "user"
assert result[0].text == "Hello, how can you help me?"
@@ -110,13 +110,13 @@ class TestThreadItemConverter:
assert result[0].text == "Hello world!"
def test_hidden_context_to_input(self, converter):
"""Test converting hidden context item to ChatMessage."""
"""Test converting hidden context item to Message."""
hidden_item = Mock()
hidden_item.content = "This is hidden context information"
result = converter.hidden_context_to_input(hidden_item)
assert isinstance(result, ChatMessage)
assert isinstance(result, Message)
assert result.role == "system"
assert result.text == "<HIDDEN_CONTEXT>This is hidden context information</HIDDEN_CONTEXT>"
@@ -288,7 +288,7 @@ class TestThreadItemConverter:
assert message.contents[1].media_type == "application/pdf"
def test_task_to_input(self, converter):
"""Test converting TaskItem to ChatMessage."""
"""Test converting TaskItem to Message."""
from datetime import datetime
from chatkit.types import CustomTask, TaskItem
@@ -302,7 +302,7 @@ class TestThreadItemConverter:
)
result = converter.task_to_input(task_item)
assert isinstance(result, ChatMessage)
assert isinstance(result, Message)
assert result.role == "user"
assert "Analysis: Analyzed the data" in result.text
assert "<Task>" in result.text
@@ -347,7 +347,7 @@ class TestThreadItemConverter:
result = converter.workflow_to_input(workflow_item)
assert isinstance(result, list)
assert len(result) == 2
assert all(isinstance(msg, ChatMessage) for msg in result)
assert all(isinstance(msg, Message) for msg in result)
assert "Step 1: First step" in result[0].text
assert "Step 2: Second step" in result[1].text
@@ -369,7 +369,7 @@ class TestThreadItemConverter:
assert result is None
def test_widget_to_input(self, converter):
"""Test converting WidgetItem to ChatMessage."""
"""Test converting WidgetItem to Message."""
from datetime import datetime
from chatkit.types import WidgetItem
@@ -384,7 +384,7 @@ class TestThreadItemConverter:
)
result = converter.widget_to_input(widget_item)
assert isinstance(result, ChatMessage)
assert isinstance(result, Message)
assert result.role == "user"
assert "widget_1" in result.text
assert "graphical UI widget" in result.text
@@ -417,6 +417,6 @@ class TestSimpleToAgentInput:
result = await simple_to_agent_input(input_item)
assert len(result) == 1
assert isinstance(result[0], ChatMessage)
assert isinstance(result[0], Message)
assert result[0].role == "user"
assert result[0].text == "Test message"