Description

Previously, @tool-decorated functions could not access the same contextual information available to module-based tools, specifically the tool_use_id and other framework-provided data. This limitation made it impossible for decorated tools to implement features like global storage indexing or request tracking that required access to tool execution metadata.

Solution

Reserved keys are an issue for decorated tools. This is because the user is the one who can freely add parameters. Rather than making an assumption about override behavior, and potential breaking changes in the event we want to pass along new information. The proposal opts to use one additional keyword, tool_context.
The keyword will NOT be breaking for customers who may already have a tool defined with a tool_context param. This is because we will add a new annotation like

# default to False, if True injects param named tool_context with ToolContext 
# object. Alternatively, a custom param name can be used by passing a string
@tool(context: str | bool) 

@tool(context=True)
def some_tool(message: str, tool_context: ToolContext) -> str:
    ....
@tool(context="custom_context_name")
def some_other_tool(message: str, custom_context_name: ToolContext) -> str:
    ....

Module and class based tools(AgentTool/PythonAgentTool) do not have the same as the user does not have control over the inputs. HOWEVER, they do have control over kwargs which are passed along to tools. These kwargs are passed in via invocation_state. For class the invocation_state is kept as a dict, meaning we can add new fields.

For module, unfortunately, they are unpacked.
Invocation state is used to store BOTH user defined kwargs, and internal data (1,2,3...) This means there is are existing hidden keywords which can conflict with customer tool definitions. If we add more, we risk breaking them. For module for any new fields we want to pass, or tool context, we would want an opt-in mechanism similar to the one we have for decorated tools.

A follow up issue will be created to discuss exposing ToolContext and what that means regarding backwards compatibility

Related Issues

#194

Documentation PR

Documentation PR to be raised before merging after naming is aligned.

Type of Change

New feature
Breaking change

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

• I have read the CONTRIBUTING document
• 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
• My changes generate no new warnings
• 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.