Python: [BREAKING] Simplify API: ChatAgent -> Agent, ChatMessage -> Message - #3747
Merged
eavanvalkenburg merged 16 commits intoFeb 10, 2026
Merged
Conversation
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 7, 2026 17:50
3d8cb28 to
0681218
Compare
moonbox3
reviewed
Feb 8, 2026
moonbox3
left a comment
Contributor
There was a problem hiding this comment.
LGTM. Can approve once CI/CD is green.
Contributor
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 10, 2026 07:37
d85dfc7 to
12ee5b7
Compare
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 10, 2026 13:03
12ee5b7 to
1c313a4
Compare
eavanvalkenburg
marked this pull request as ready for review
February 10, 2026 15:49
markwallace-microsoft
approved these changes
Feb 10, 2026
dmytrostruk
approved these changes
Feb 10, 2026
dmytrostruk
left a comment
Member
There was a problem hiding this comment.
Based on PR description, I had a comment about chat parameter in this example:
agent = Agent(
chat=client,
name="assistant",
instructions="You are a helpful assistant."
)But I wasn't able to find it in code changes. Other than that, LGTM.
Member
Author
That should be client instead. I'll doublecheck |
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 10, 2026 19:57
143b140 to
31d7fb6
Compare
eavanvalkenburg
enabled auto-merge
February 10, 2026 19:58
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
2 times, most recently
from
February 10, 2026 20:28
d105ac7 to
53f0414
Compare
dmytrostruk
approved these changes
Feb 10, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Feb 10, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Feb 10, 2026
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 10, 2026 20:55
53f0414 to
a8f7b4c
Compare
eavanvalkenburg
enabled auto-merge
February 10, 2026 20:55
dmytrostruk
approved these changes
Feb 10, 2026
dmytrostruk
approved these changes
Feb 10, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Feb 10, 2026
github-merge-queue
Bot
removed this pull request from the merge queue due to a conflict with the base branch
Feb 10, 2026
…entProtocol -> 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.
…ge→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)
- 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
…laration-only tool tests
eavanvalkenburg
force-pushed
the
edvan/rename-chat-agent-message
branch
from
February 10, 2026 22:37
132b0a4 to
58c4f9b
Compare
eavanvalkenburg
enabled auto-merge
February 10, 2026 22:47
dmytrostruk
approved these changes
Feb 10, 2026
dmytrostruk
approved these changes
Feb 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR simplifies the public API by removing redundant
Chatprefix from core types that users interact with most frequently.Motivation
Why
Agentinstead ofChatAgentWhile the .NET side of Agent Framework favors globally unique type names (and has a relatively limited number of orchestration packages to contend with), the Python ecosystem is fundamentally different. Python has a large and growing number of agent-focused packages — LangChain/LangGraph, CrewAI, AutoGen, PydanticAI, Smolagents, and others — and virtually all of them use
Agentas their primary class name. By staying withChatAgent, we miss the opportunity for naming parity with the broader ecosystem, making our API feel less natural to Python developers coming from (or evaluating against) other frameworks.Agentis the name Python developers expect.Why
Messageinstead ofChatMessageRenaming to
Messagebetter emphasizes the generic, multimodal nature of what can be passed through a message. Messages in Agent Framework are not limited to text chat — they carry structured content including images, function calls, function results, and other content types. TheChatprefix incorrectly implies a text-only chat paradigm and undersells the capability of the type.Breaking Changes
ChatAgentAgentRawChatAgentRawAgentChatMessageMessageChatClientProtocolSupportsChatGetResponseNo backward compatibility aliases - this is a clean breaking change.
API Examples
Creating an Agent (Before)
Creating an Agent (After)
Working with Messages (Before)
Working with Messages (After)
Multi-turn Conversations (After)
Using Tools (After)
Streaming Responses (After)
Custom Chat Client Protocol (After)
Internal Changes
Messagein_workflows/_runner_context.pytoWorkflowMessageto avoid collision with the newMessagetypeMigration Guide
Find and replace in your codebase:
ChatAgent→AgentRawChatAgent→RawAgentChatMessage→MessageChatClientProtocol→SupportsChatGetResponseUpdate imports: