ADK Tools
A collection of utilities and patterns for building agents with Google's Agent Development Kit (ADK).
Installation
pip install adktools
Features
@adk_tooldecorator: Standardize your ADK tools with consistent error handling and response formatting- Domain error models: Create rich, domain-specific error types that automatically convert to standard responses
- Tool discovery: Automatically find all tool functions in your modules
- Response utilities: Standardized success and error response generation
- Type safety: Comprehensive typing support for better IDE integration
Quick Start
Basic Tool Creation
from adktools import adk_tool
from pydantic import BaseModel
class WeatherResult(BaseModel):
location: str
temperature: float
conditions: str
@adk_tool
def get_weather(location: str) -> WeatherResult:
"""Get current weather for a location."""
# Your implementation here
return WeatherResult(
location=location,
temperature=72.5,
conditions="Sunny"
)
Domain-Specific Error Handling
from adktools import adk_tool
from adktools.models import DomainError
from typing import Literal, Union
from pydantic import BaseModel
class TimeResult(BaseModel):
timezone: str
datetime: str
is_dst: bool
class InvalidTimezoneError(DomainError):
timezone: str
error_type: Literal["invalid_timezone"] = "invalid_timezone"
@adk_tool(
name="get_time",
description="Get the current time in a specified timezone."
)
def get_current_time(timezone: str) -> Union[TimeResult, InvalidTimezoneError]:
try:
# Implementation...
if timezone == "invalid":
return InvalidTimezoneError(
timezone=timezone,
error_message=f"Unknown timezone: {timezone}"
)
return TimeResult(
timezone=timezone,
datetime="2025-04-12T12:34:56",
is_dst=True
)
except Exception as e:
# The decorator will catch and format any exceptions
raise RuntimeError(f"Error getting time: {str(e)}")
Tool Discovery
from adktools import discover_adk_tools
from google.adk.agents import Agent
# Import your modules containing tools
import myagent.weather_tools
import myagent.time_tools
# Create an agent with auto-discovered tools
agent = Agent(
name="my_assistant",
description="A helpful assistant",
tools=discover_adk_tools(myagent.weather_tools)
)
# Or discover tools across multiple modules
all_tools = discover_adk_tools_in_modules([
myagent.weather_tools,
myagent.time_tools
])
Documentation
The @adk_tool Decorator
The decorator standardizes ADK tool responses and provides additional metadata for tools:
@adk_tool # Simple usage
def simple_tool(param: str):
# Implementation...
@adk_tool(
name="custom_name", # Override function name
description="Custom description", # Override docstring
detailed_errors=True # Include stack traces in errors
)
def custom_tool(param: str):
# Implementation...
Response Models
ADK Tools provides standardized response models:
from adktools.models import ErrorResponse, SuccessResponse, DomainError
# Success response
success = SuccessResponse(result={"key": "value"})
# Or without data
empty_success = SuccessResponse() # result is optional
# Error response
error = ErrorResponse(error_message="Something went wrong")
# Domain-specific error base class
class MyCustomError(DomainError):
error_type: Literal["custom_error"] = "custom_error"
error_message: str # Matches ErrorResponse field name
additional_field: str
Helper Functions
from adktools import success_response, error_response
# Create success response dictionary
response = success_response({"data": "value"})
# {"status": "success", "result": {"data": "value"}}
# Create success response without data
empty_response = success_response()
# {"status": "success"}
# Create error response dictionary
response = error_response("Something went wrong")
# {"status": "error", "error_message": "Something went wrong"}
Response Format
By default, ADK Tools uses the following standardized response formats:
Success Response
{
"status": "success",
"result": { ... } // Optional result data
}
Error Response
{
"status": "error",
"error_message": "Description of what went wrong"
}
This consistent response format makes it easy for agents to handle tool responses predictably.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
Distributed under the MIT License. See LICENSE for more information.
Metadata
Release files for adktools 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| adktools-0.1.2.tar.gz | 12.1 kB | Without provenance | Details for adktools-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adktools-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for adktools-0.1.2-py3-none-any.whl |
Total release size: 22.5 kB
Release files / adktools-0.1.2.tar.gz
| Download URL | adktools-0.1.2.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
205349d1019e0d0178f29f428caff67e247999b4b14d6fd2abc76312a130f805
|
|
BLAKE2b-256 checksum How to use checksums |
7daf030dd933d439e1266e88782ce159e209da0b1540cc8d9db47e9da38ce8ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Release files / adktools-0.1.2-py3-none-any.whl
| Download URL | adktools-0.1.2-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2b1adc94db24098c571eeffdfcdf4535fd47595dc47a9215c4079f8daf7e82f9
|
|
BLAKE2b-256 checksum How to use checksums |
a090d96a3cf8d8c2bf4b3680de1ba78602301fabd3e6600e34c3ed7fa13786cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Security for adktools 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.