feat(tools): Add CallableRetrieval for custom retrieval backends

[savula15]

Add a new CallableRetrieval class that wraps any user-provided sync or async callable as a BaseRetrievalTool, enabling custom retrieval backends (Elasticsearch, Pinecone, pgvector, etc.) to have first-class retrieval semantics without requiring specific framework dependencies.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Add CallableRetrieval tool for custom retrieval backends #4557

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Added 9 tests in tests/unittests/tools/retrieval/test_callable_retrieval.py:

• Sync callable returns results correctly
• Async callable awaits and returns results correctly
• isinstance(tool, BaseRetrievalTool) is True
• _get_declaration() returns standard {query: string} schema
• tool_context passthrough to callable that accepts it
• tool_context omission for callable without it
• Async callable with tool_context
• Sync callable object (class with __call__)
• Async callable object (class with async __call__)

Full suite:
==== 4383 passed, 1 skipped, 2085 warnings, 2 subtests passed in 56.82s ====

Retrieval suite:
==== 19 passed, 4 warnings in 2.04s ====

Manual End-to-End (E2E) Tests:
N/A. This is a new tool class with no UI or runner changes. Behavior is fully covered by unit tests. Import verified:

>>> from google.adk.tools.retrieval import CallableRetrieval
>>> from google.adk.tools.retrieval import BaseRetrievalTool
>>> tool = CallableRetrieval(name="test", description="test", retriever=lambda q: [])
>>> isinstance(tool, BaseRetrievalTool)
True

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

This fills a gap in the retrieval tool family. Existing BaseRetrievalTool subclasses (VertexAiRagRetrieval, LlamaIndexRetrieval, FilesRetrieval) all require specific backends. CallableRetrieval is the framework-agnostic entry point, users with custom retrieval logic get proper retrieval semantics (standardized query parameter, isinstance identity, graph visualization) without vendor lock-in.

Implementation follows the same pattern as LlamaIndexRetrieval. Zero external dependencies.

[gemini-code-assist]

Summary of Changes

Hello @savula15, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces the CallableRetrieval class, a significant enhancement to the ADK's retrieval tool ecosystem. It provides a flexible and framework-agnostic mechanism for developers to integrate their custom retrieval backends, such as Elasticsearch or Pinecone, by simply wrapping any Python callable. This allows for standardized retrieval semantics and graph visualization without imposing specific dependencies, thereby empowering users with greater control and adaptability in their retrieval strategies.

Highlights

• New CallableRetrieval class: Introduced CallableRetrieval to allow users to wrap any sync or async callable as a BaseRetrievalTool, providing a framework-agnostic way to integrate custom retrieval logic.
• Flexible callable support: The CallableRetrieval class supports both synchronous and asynchronous functions or callable objects, automatically detecting and awaiting async operations.
• ToolContext integration: The new tool intelligently passes ToolContext to the user-provided callable if the callable's signature includes a tool_context parameter, otherwise it omits it.
• Expanded retrieval tool family: This addition fills a gap by offering a generic retrieval tool, complementing existing backend-specific tools like VertexAiRagRetrieval and LlamaIndexRetrieval.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/tools/retrieval/init.py
  • Imported CallableRetrieval and added it to the __all__ export list.
• src/google/adk/tools/retrieval/callable_retrieval.py
  • Added the CallableRetrieval class, which extends BaseRetrievalTool and wraps user-provided sync or async callables.
  • Implemented logic to inspect the callable's signature for tool_context and handle async execution.
• tests/unittests/tools/retrieval/test_callable_retrieval.py
  • Added comprehensive unit tests covering sync/async callables, tool_context passthrough/omission, isinstance checks, _get_declaration behavior, and callable objects.

Activity

• The author has added 9 new unit tests for the CallableRetrieval class, covering various scenarios including sync/async callables, tool_context handling, and callable objects.
• All new and existing unit tests are reported to pass locally.
• Manual end-to-end testing was deemed not applicable as this is a new tool class without UI or runner changes, but import verification was performed.
• The author has confirmed reading CONTRIBUTING.md, self-reviewed the code, and commented on hard-to-understand areas.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The addition of CallableRetrieval provides a useful, framework-agnostic way to integrate custom retrieval logic into the ADK. The implementation is well-structured and includes comprehensive unit tests covering various callable types and context passthrough scenarios. I have suggested a refinement to the async dispatch logic to improve performance and robustness with wrapped callables like functools.partial.

[savula15]

Hi @seanzhou1023 @hangfei
I'd love your review on this PR when you get a chance. You both shaped the retrieval tool architecture, so your feedback would be especially valuable.

This adds a CallableRetrieval class, a framework-agnostic counterpart to LlamaIndexRetrieval so users with custom retrieval backends (Elasticsearch, Pinecone, pgvector, etc.) can get first-class BaseRetrievalTool semantics without needing a specific framework dependency.

The implementation is small, follows existing patterns closely and introduces zero new dependencies. Happy to iterate on any feedback. Thanks!

[ryanaiagent]

Hi @savula15, Thank you for your contribution! We appreciate you taking the time to submit this pull request.
Closing this PR here as it belongs to adk-python-community repo.
We highly recommend releasing the feature as a standalone package that we will then share through: https://google.github.io/adk-docs/integrations/