Tools
Writing your own tools
Learn how to write your own tools and how to use the @tool
decorator to modify the behavior of a tool.
In most production cases, you will need to write your own tools. Which is why we’re focused on provide the best tool-use experience in Agno.
The rule is simple:
- Any python function can be used as a tool by an Agent.
- Use the
@tool
decorator to modify what happens before and after this tool is called.
Any python function can be used as a tool
For example, here’s how to use a get_top_hackernews_stories
function as a tool:
hn_agent.py
Magic of the @tool decorator
To modify the behavior of a tool, use the @tool
decorator. Some notable features:
requires_confirmation=True
: Requires user confirmation before execution.requires_user_input=True
: Requires user input before execution. Useuser_input_fields
to specify which fields require user input.external_execution=True
: The tool will be executed outside of the agent’s control.show_result=True
: Show the output of the tool call in the Agent’s response. Without this flag, the result of the tool call is sent to the model for further processing.stop_after_tool_call=True
: Stop the agent run after the tool call.tool_hooks
: Run custom logic before and after this tool call.cache_results=True
: Cache the tool result to avoid repeating the same call. Usecache_dir
andcache_ttl
to configure the cache.
Here’s an example that uses many possible parameters on the @tool
decorator.
advanced_tool.py
@tool Parameters Reference
Parameter | Type | Description |
---|---|---|
name | str | Override for the function name |
description | str | Override for the function description |
show_result | bool | If True, shows the result after function call |
stop_after_tool_call | bool | If True, the agent will stop after the function call |
tool_hooks | list[Callable] | List of hooks that wrap the function execution |
pre_hook | Callable | Hook to run before the function is executed |
post_hook | Callable | Hook to run after the function is executed |
requires_confirmation | bool | If True, requires user confirmation before execution |
requires_user_input | bool | If True, requires user input before execution |
user_input_fields | list[str] | List of fields that require user input |
external_execution | bool | If True, the tool will be executed outside of the agent’s control |
cache_results | bool | If True, enable caching of function results |
cache_dir | str | Directory to store cache files |
cache_ttl | int | Time-to-live for cached results in seconds (default: 3600) |