Python: [BREAKING] Simplify API: ChatAgent -> Agent, ChatMessage -> Message#3747
Merged
eavanvalkenburg merged 16 commits intomicrosoft:mainfrom Feb 10, 2026
Merged
Conversation
3d8cb28 to
0681218
Compare
moonbox3
reviewed
Feb 8, 2026
Contributor
moonbox3
left a comment
There was a problem hiding this comment.
LGTM. Can approve once CI/CD is green.
Member
d85dfc7 to
12ee5b7
Compare
12ee5b7 to
1c313a4
Compare
markwallace-microsoft
approved these changes
Feb 10, 2026
dmytrostruk
approved these changes
Feb 10, 2026
Member
dmytrostruk
left a comment
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 |
143b140 to
31d7fb6
Compare
d105ac7 to
53f0414
Compare
dmytrostruk
approved these changes
Feb 10, 2026
53f0414 to
a8f7b4c
Compare
dmytrostruk
approved these changes
Feb 10, 2026
dmytrostruk
approved these changes
Feb 10, 2026
368f296 to
5e9769e
Compare
dmytrostruk
approved these changes
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
132b0a4 to
58c4f9b
Compare
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: