Description

Update tools decorated with @tool to be subclasses of AgentTool instead of callable that look similar to python modules.

This means that the following:

@tool
def my_tool(a_string: str, a_number: number):
   ...

my_tool is actually an implementation of AgentTool (specifically DecoratedFunctionTool).

If you call my_tool() directly it acts just like a function call. But it also has the methods and properties of an AgentTool:

my_tool("a string", 13) # Works
my_tool.tool_spec       # Contains the tool spec of the AgentTool

This would allow us to include a helper utility in the future that act on AgentTool(s) without needing to special case decorated functions.

One such example is a bind utility which would use a constant value for a tool:

new_tool = tool.bind(my_tool, { a_str: "A value" })
new_tool(a_number = 3) # only expects a_number

though this is just an example of how unification benefits

Behavior Change:

We no longer allow passing ToolUse directly into the decorated functions (we do allow this right now for backwards compatibility but emit a warning - in the future we will not allow this):

tool_use = {"toolUseId": "test-id", "input": {"union_param": [1, 2, 3]}}

my_tool(tool_use)        # does not work
my_tool.invoke(tool_use) # does work

This was previously allowed because the tool decorator didn't differentiate between calls that were going to the function and calls that were being done as "tool"; instead this is now implemented via invoke like other AgentTools

Implementation Notes:

• Typing was a bit harder to implement here to satisfy mypy and the typechecker so in a couple place we ignore errors. The primary problem was around:
  • Implementing DecoratedFunctionTool in a way that typed it as both the original function and an AgentTool
  • Implementing a decorator that was usable as @tool() and @tool but was also typed correctly
  • MyPy seemingly can't detect that DecoratedFunctionTool derives from AgentTool, so I had to add a couple overloads around that
• I kept FunctionTool around for backwards compatibly with the idea that we'll remove it in the future. This is up for debate, but let me know if you disagree

Related Issues

N/A

Documentation PR

n/A

Type of Change

Refactor

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.