feat: replace kwargs with invocation_state in agent APIs

[JackYPCOnline]

Description

The current Agent APIs (Agent.call, Agent.invoke_async, Agent.stream_async) accept arbitrary keyword arguments via **kwargs, which are then converted to invocation_state and passed through the execution pipeline to tools. This has the downside that any new parameter we want to add to these methods could potentially conflict with user-provided kwargs, making it impossible to evolve the API without breaking changes.

Change:
Add invocation_state as parameter to agent's APIs.
Still keep **kwargs for now to keep backward compatible, merge **kwargs to invocation_state instead.

Related Issues

#919

Documentation PR

Type of Change

Bug fix
New feature
Breaking change
Documentation update
Other (please describe):

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• [x ] I have read the CONTRIBUTING document
• [x ] I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• [x ] My changes generate no new warnings
• [x ] Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[pgrayy]

Can you add details to the PR description explaining the purpose of this change?

[Unshure]

Can you add unit tests for this

[mkmeral]

aren't we double nesting here?

4. Backward compatibility breaks silently
Old code using agent("prompt", user_id="123") will work but 
with a deprecation warning. However, if someone tries to migrate 
by wrapping it: agent("prompt", invocation_state={"user_id": "123"}), 
the data ends up in a different location in the state dict.

so when you try to use agent("prompt", invocation_state={"user_id": "123"}), you would need to do this in the tool:

tool_context.invocation_state.invocation_state.user_id

is this the desired devx for now?

[JackYPCOnline]

yep, see comment

[zastrowm]

I'm not sure I agree with this; see the Unit Test comment below. But the intent is that users would replace kwargs with invocation_state - but if they're already using kwargs, then we mimic the old behavior to avoid a breaking change, while nudging them towards invocation_state

Basically it should be something like:

if kwargs:
   merged_state = kwargs
   # emit warning
   if invocation_state:
       # If the user is using kwargs, that means they intended all arguments to be kwargs
       merged_state["invocation_state'] = kwargs
else:
    merged_state = invocation_state

[JackYPCOnline]

Adjusted.

if xxx:
 ........
else:
    if invocation_state is not none: # Added this line, we are not accepting `None` now.

[JackYPCOnline]

Can you add unit tests for this

Actually this change is covered by origin test code but I can add a specific one

[zastrowm]

I'm not sure I agree with this; see the Unit Test comment below. But the intent is that users would replace kwargs with invocation_state - but if they're already using kwargs, then we mimic the old behavior to avoid a breaking change, while nudging them towards invocation_state

Basically it should be something like:

if kwargs:
   merged_state = kwargs
   # emit warning
   if invocation_state:
       # If the user is using kwargs, that means they intended all arguments to be kwargs
       merged_state["invocation_state'] = kwargs
else:
    merged_state = invocation_state