Unified abstractions to represent tools across the framework.
Module tool
Tool
Data class representing a Tool that Language Models can prepare a call for.
Accurate definitions of the textual attributes such as name and description
are important for the Language Model to correctly prepare the call.
Arguments:
name: Name of the Tool.description: Description of the Tool.parameters: A JSON schema defining the parameters expected by the Tool.function: The function that will be invoked when the Tool is called.
Tool.tool_spec
@property
def tool_spec() -> Dict[str, Any]
Return the Tool specification to be used by the Language Model.
Tool.invoke
def invoke(**kwargs) -> Any
Invoke the Tool with the provided keyword arguments.
Tool.to_dict
def to_dict() -> Dict[str, Any]
Serializes the Tool to a dictionary.
Returns:
Dictionary with serialized data.
Tool.from_dict
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Tool"
Deserializes the Tool from a dictionary.
Arguments:
data: Dictionary to deserialize from.
Returns:
Deserialized Tool.
deserialize_tools_inplace
def deserialize_tools_inplace(data: Dict[str, Any], key: str = "tools")
Deserialize Tools in a dictionary inplace.
Arguments:
data: The dictionary with the serialized data.key: The key in the dictionary where the Tools are stored.
Module from_function
create_tool_from_function
def create_tool_from_function(function: Callable,
name: Optional[str] = None,
description: Optional[str] = None) -> "Tool"
Create a Tool instance from a function.
Allows customizing the Tool name and description.
For simpler use cases, consider using the @tool decorator.
Usage example
from typing import Annotated, Literal
from haystack.tools import create_tool_from_function
def get_weather(
city: Annotated[str, "the city for which to get the weather"] = "Munich",
unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
'''A simple function to get the current weather for a location.'''
return f"Weather report for {city}: 20 {unit}, sunny"
tool = create_tool_from_function(get_weather)
print(tool)
>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
>>> parameters={
>>> 'type': 'object',
>>> 'properties': {
>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
>>> 'unit': {
>>> 'type': 'string',
>>> 'enum': ['Celsius', 'Fahrenheit'],
>>> 'description': 'the unit for the temperature',
>>> 'default': 'Celsius',
>>> },
>>> }
>>> },
>>> function=<function get_weather at 0x7f7b3a8a9b80>)
Arguments:
function: The function to be converted into a Tool. The function must include type hints for all parameters. The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple). Other input types may work but are not guaranteed. If a parameter is annotated usingtyping.Annotated, its metadata will be used as parameter description.name: The name of the Tool. If not provided, the name of the function will be used.description: The description of the Tool. If not provided, the docstring of the function will be used. To intentionally leave the description empty, pass an empty string.
Raises:
ValueError: If any parameter of the function lacks a type hint.SchemaGenerationError: If there is an error generating the JSON schema for the Tool.
Returns:
The Tool created from the function.
tool
def tool(function: Callable) -> Tool
Decorator to convert a function into a Tool.
Tool name, description, and parameters are inferred from the function.
If you need to customize more the Tool, use create_tool_from_function instead.
Usage example
from typing import Annotated, Literal
from haystack.tools import tool
@tool
def get_weather(
city: Annotated[str, "the city for which to get the weather"] = "Munich",
unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
'''A simple function to get the current weather for a location.'''
return f"Weather report for {city}: 20 {unit}, sunny"
print(get_weather)
>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
>>> parameters={
>>> 'type': 'object',
>>> 'properties': {
>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
>>> 'unit': {
>>> 'type': 'string',
>>> 'enum': ['Celsius', 'Fahrenheit'],
>>> 'description': 'the unit for the temperature',
>>> 'default': 'Celsius',
>>> },
>>> }
>>> },
>>> function=<function get_weather at 0x7f7b3a8a9b80>)
Module component_tool
ComponentTool
A Tool that wraps Haystack components, allowing them to be used as tools by LLMs.
ComponentTool automatically generates LLM-compatible tool schemas from component input sockets,
which are derived from the component's run method signature and type hints.
Key features:
- Automatic LLM tool calling schema generation from component input sockets
- Type conversion and validation for component inputs
- Support for types:
- Dataclasses
- Lists of dataclasses
- Basic types (str, int, float, bool, dict)
- Lists of basic types
- Automatic name generation from component class name
- Description extraction from component docstrings
To use ComponentTool, you first need a Haystack component - either an existing one or a new one you create. You can create a ComponentTool from the component by passing the component to the ComponentTool constructor. Below is an example of creating a ComponentTool from an existing SerperDevWebSearch component.
from haystack import component, Pipeline
from haystack.tools import ComponentTool
from haystack.components.websearch import SerperDevWebSearch
from haystack.utils import Secret
from haystack.components.tools.tool_invoker import ToolInvoker
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
# Create a SerperDev search component
search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3)
# Create a tool from the component
tool = ComponentTool(
component=search,
name="web_search", # Optional: defaults to "serper_dev_web_search"
description="Search the web for current information on any topic" # Optional: defaults to component docstring
)
# Create pipeline with OpenAIChatGenerator and ToolInvoker
pipeline = Pipeline()
pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=[tool]))
pipeline.add_component("tool_invoker", ToolInvoker(tools=[tool]))
# Connect components
pipeline.connect("llm.replies", "tool_invoker.messages")
message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla")
# Run pipeline
result = pipeline.run({"llm": {"messages": [message]}})
print(result)
ComponentTool.__init__
def __init__(component: Component,
name: Optional[str] = None,
description: Optional[str] = None)
Create a Tool instance from a Haystack component.
Arguments:
component: The Haystack component to wrap as a tool.name: Optional name for the tool (defaults to snake_case of component class name).description: Optional description (defaults to component's docstring).
Raises:
ValueError: If the component is invalid or schema generation fails.
ComponentTool.to_dict
def to_dict() -> Dict[str, Any]
Serializes the ComponentTool to a dictionary.
ComponentTool.from_dict
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Tool"
Deserializes the ComponentTool from a dictionary.
ComponentTool.tool_spec
@property
def tool_spec() -> Dict[str, Any]
Return the Tool specification to be used by the Language Model.
ComponentTool.invoke
def invoke(**kwargs) -> Any
Invoke the Tool with the provided keyword arguments.