Python: Relax Agent Invocation Methods to Allow Positional or Keyword Arguments for messages
#12248
Conversation
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
markwallace-microsoft
added
the
python
Python Unit Test Overview
|
4 tasks
TaoChenOSU
approved these changes
May 23, 2025
eavanvalkenburg
approved these changes
May 23, 2025
eavanvalkenburg
pushed a commit
that referenced
this pull request
May 26, 2025
… Arguments for `messages` (#12248) ### Motivation and Context This PR relaxes the API signatures of all agent invocation methods (`get_response`, `invoke`, `invoke_stream`) by changing the `messages` parameter from keyword-only to positional-or-keyword. This enhances ergonomics and Pythonic usability by allowing callers to pass messages either positionally or as a keyword argument: ```python agent.get_response("Why is the sky blue?") agent.get_response(messages="Why is the sky blue?") ``` With our current use of **kwargs, it is possible to explicitly pass None for messages (like `agent.get_response(messages=None)`). However, this does not feel idiomatic in Python. If a caller wishes to invoke the agent on an existing thread (which already contains all relevant context), it is more natural and Pythonic to simply write: ```python response = await agent.get_response() ``` This change makes the API more user-friendly, and removes unnecessary verbosity when no new messages need to be provided. Impact - Backward compatible for all previous usage. - Enables concise and intuitive API calls for primary message arguments. - Subclasses overriding the prior keyword-only signature will continue to work at runtime, but static type-checkers may require updating their signatures to match the new base definition. - No runtime breaking changes are expected. | Scenario | Breaks at runtime? | Breaks at type-check? | Notes | |----------------------------------|----------------------|-------------------------|--------------------------------------------------| | Subclass w/keyword-only | No | Yes | Type checker error, but runtime OK | | Subclass matching base | No | No | Fine | | Calls expecting keyword-only | No | No | Fine | | Calls expecting positional | No (now allowed) | No | Improved ergonomics | | Decorators relying on kw-only | No | No (unless strict sig) | Only if decorator is brittle, rare | | Code generation/docs | No | No | Needs updating docs, not an actual code break | | Reflection-based invocation | No | No | Slight difference in behavior, but not breaking | Documentation and usage examples will be updated to reflect the improved invocation style. <!-- Thank you for your contribution to the semantic-kernel repo! Please help reviewers and future users, providing the following information: 1. Why is this change required? 2. What problem does it solve? 3. What scenario does it contribute to? 4. If it fixes an open issue, please link to the issue here. --> ### Description Relaxes the API signatures of all agent invocation methods. <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [X] The code builds clean without any errors or warnings - [X] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [X] All unit tests pass, and I have added new tests where possible - [X] I didn't break anyone 😄
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.
Motivation and Context
This PR relaxes the API signatures of all agent invocation methods (
get_response,invoke,invoke_stream) by changing themessagesparameter from keyword-only to positional-or-keyword. This enhances ergonomics and Pythonic usability by allowing callers to pass messages either positionally or as a keyword argument:With our current use of **kwargs, it is possible to explicitly pass None for messages (like
agent.get_response(messages=None)). However, this does not feel idiomatic in Python. If a caller wishes to invoke the agent on an existing thread (which already contains all relevant context), it is more natural and Pythonic to simply write:This change makes the API more user-friendly, and removes unnecessary verbosity when no new messages need to be provided.
Impact
Documentation and usage examples will be updated to reflect the improved invocation style.
Description
Relaxes the API signatures of all agent invocation methods.
Contribution Checklist