feat: add class based tool loader to enable easier integation with existing codebases

[dbschmigelski]

Description

Class-based Tool Loader for Existing Codebases

While the @tool annotation works great for new projects, we often face the challenge of integrating existing codebases that already have established repository patterns and service implementations. This PR addresses this challenge by introducing a class-based tool loader that dramatically simplifies the process of exposing existing functionality to agents.

The core of this implementation is the load_tools_from_instance function, which automatically converts public methods from existing classes into AgentTools. It handles instance, static, and class methods seamlessly, while providing automatic name disambiguation when dealing with multiple instances. This means teams can leverage their existing codebase without having to modify their code with decorators or make significant structural changes.

The implementation is flexible and forward-looking. While it currently provides the essential functionality needed to quickly onboard existing codebases, it sets the foundation for future enhancements. We can build upon this base to add features like base class support, enhanced method descriptions, conditional loading via annotations, and custom filtering mechanisms.

This approach significantly reduces the barrier to entry for teams wanting to integrate with Strands SDK. Instead of requiring extensive refactoring or decoration of existing code, teams can now expose their business logic to agents with minimal effort. The included test files demonstrate both simple use cases with the WeatherTimeTool and more complex scenarios involving multiple instances with static methods, showing the versatility of this approach.

The primary goal is to accelerate adoption in existing codebases, making it easier for teams to start using agents with their current implementations while maintaining the flexibility to evolve their integration over time.

For example, consider an existing code base with a class DynamoDBUserRepository:

class UserRepository(ABC):
   @abstractmethod
   def create(self, ...):
   def delete(self, ...):
   ...

class DynamoDBUserRepository(UserRepository):
   ...

this feature would enable

user_repository: UserRepository = DynamoDBUserRepository(...)
Agent(tools=load_tools_from_instance(user_repository))

Documentation PR

• TODO after this exits draft stage

Type of Change

• New feature

Testing

All

• hatch fmt --linter
• hatch fmt --formatter
• hatch test --all
• Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

Getting throttled with integ tests. But running inisolation we get

hatch test tests-integ/test_class_loader.py

======================================================= 1 passed, 39 warnings in 8.11s ========================================================

Checklist

• I have read the CONTRIBUTING document
• I have added tests that prove my fix is effective or my feature works
• [TODO] I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature
• 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.

[zastrowm]

The callout of the goal

While the @tool annotation works great for new projects, we often face the challenge of integrating existing codebases that already have established repository patterns and service implementations.

Do we expect enough folks would use this without modifying their classes for usage in LLMs? - my first inclination is that most callers would want to create specific tools vs just providing existing apis/descriptors.

If developers are already modifying stuff for LLMs, then IMHO opt-in via decorator or something would be more clear/customizable. If that's not the case or if the goal is to expose classes/apis that don't depend on strands, then not annotating makes more sense, albeit with a bit more control

[dbschmigelski]

The callout of the goal

While the @tool annotation works great for new projects, we often face the challenge of integrating existing codebases that already have established repository patterns and service implementations.

Do we expect enough folks would use this without modifying their classes for usage in LLMs? - my first inclination is that most callers would want to create specific tools vs just providing existing apis/descriptors.

If developers are already modifying stuff for LLMs, then IMHO opt-in via decorator or something would be more clear/customizable. If that's not the case or if the goal is to expose classes/apis that don't depend on strands, then not annotating makes more sense, albeit with a bit more control

I think I see this solving for " expose classes/apis that don't depend on strands". Companies have a wealth of classes that "do useful things", so this PR attempts to expose that quickly.

To gauge interest how would you feel about me creating an issue to gather customer input? Then we can merge this here, or perhaps in strands tools, if theres sufficient demand?

[zastrowm]

Works for me - if we know of customers that are asking for this, I think it's a stronger argument forit.

In the meantime, do you think it's worth supporting member classes decorated by @tool (IIRC we had a PR for that)?

[dbschmigelski]

Works for me - if we know of customers that are asking for this, I think it's a stronger argument forit.

In the meantime, do you think it's worth supporting member classes decorated by @tool (IIRC we had a PR for that)?

Yeah I closed that out in favor of this. The class method annotation doesn't really make much sense because it is not linked to an instance, so this PR addresses that.

Unless we just treat this PR as the answer for #199