[FEATURE] Replace kwargs with explicit invocation_args parameter in Agent APIs

[zastrowm]

Problem Statement

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.

Proposed Solution

Replace **kwargs with an explicit invocation_state parameter:

from typing import Optional, Dict, Any

# New API
def __call__(
    self, 
    prompt: AgentInput = None, 
    *, 
    invocation_state: dict | None  = None
) -> AgentResult:

async def invoke_async(
    self, 
    prompt: AgentInput = None, 
    *, 
    invocation_state: dict | None  = None
) -> AgentResult:

async def stream_async(
    self, 
    prompt: AgentInput = None, 
    *, 
    invocation_state: dict | None  = None
) -> AsyncIterator[Any]:

To allow for incremental adoption, I'd propose:

• For 1.X we emit a warning to notify consumers of the future change
• For 1.Y we accept both, preferring invocation_args if it's present
• For 2.0, we only accept invocation_args

Use Case

Primarily to enable API evolution without breaking changes and make it explicit to callers what the invocation_state parameters are used throughout the code base.

Alternatives Solutions

No response

Additional Context

No response

[cagataycali]

It looks like we have to migrate "invocation_args" if we proceed with proposal, but that would increase the scaffolding needs. I'd prefer to not throw a warning when kwargs used.

[mkmeral]

Should we keep the naming consistent and use invocation_state?

[Unshure]

Worked on some sudo-code for what this might looks like:

def __call__(self, prompt: AgentInput = None, *, invocation_state: dict[str, Any],  **kwargs: Any) -> AgentResult:
  if len(kwargs) > 0:
    logger.warn("Kwargs is deprecated, use the `invocation_state` parameter instead. Check these docs for migration: ..."
    self.invocation_state = kwargs
    self.invocation_state["invocation_state"] = invocation_state
  else:
    self.invocation_state = invocation_state
  ...

We can add new keyword arguments to the agent invocation definition. If any kwargs are provided, then we fall back to the old behavior with the invocation state. Otherwise, we can add new keyword arguments to the function signature.