toolset.mdx
1 --- 2 title: "Toolset" 3 id: toolset 4 slug: "/toolset" 5 description: "Group multiple Tools into a single unit." 6 --- 7 8 # Toolset 9 10 Group multiple Tools into a single unit. 11 12 <div className="key-value-table"> 13 14 | | | 15 | --- | --- | 16 | **Mandatory init variables** | `tools`: A list of tools | 17 | **API reference** | [Toolset](/reference/tools-api#toolset) | 18 | **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/tools/toolset.py | 19 20 </div> 21 22 ## Overview 23 24 A `Toolset` groups multiple Tool instances into a single manageable unit. It simplifies passing tools to components like Chat Generators, [`ToolInvoker`](../pipeline-components/tools/toolinvoker.mdx), or [`Agent`](../pipeline-components/agents-1/agent.mdx), and supports filtering, serialization, and reuse. 25 26 Additionally, by subclassing `Toolset`, you can create implementations that dynamically load tools from external sources like OpenAPI URLs, MCP servers, or other resources. 27 28 ### Initializing Toolset 29 30 Here’s how to initialize `Toolset` with [Tool](tool.mdx). Alternatively, you can use [ComponentTool](componenttool.mdx) or [MCPTool](mcptool.mdx) in `Toolset` as Tool instances. 31 32 ```python 33 from haystack.tools import Tool, Toolset 34 35 36 ## Define math functions 37 def add_numbers(a: int, b: int) -> int: 38 return a + b 39 40 41 def subtract_numbers(a: int, b: int) -> int: 42 return a - b 43 44 45 ## Create tools with proper schemas 46 add_tool = Tool( 47 name="add", 48 description="Add two numbers", 49 parameters={ 50 "type": "object", 51 "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}}, 52 "required": ["a", "b"], 53 }, 54 function=add_numbers, 55 ) 56 57 subtract_tool = Tool( 58 name="subtract", 59 description="Subtract b from a", 60 parameters={ 61 "type": "object", 62 "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}}, 63 "required": ["a", "b"], 64 }, 65 function=subtract_numbers, 66 ) 67 68 ## Create a toolset with the math tools 69 math_toolset = Toolset([add_tool, subtract_tool]) 70 ``` 71 72 ### Adding New Tools to Toolset 73 74 ```python 75 def multiply_numbers(a: int, b: int) -> int: 76 return a * b 77 78 79 multiply_tool = Tool( 80 name="multiply", 81 description="Multiply two numbers", 82 parameters={ 83 "type": "object", 84 "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}}, 85 "required": ["a", "b"], 86 }, 87 function=multiply_numbers, 88 ) 89 90 math_toolset.add(multiply_tool) 91 92 ## or, you can merge toolsets together 93 math_toolset.add(another_toolset) 94 ``` 95 96 ## Usage 97 98 You can use `Toolset` wherever you can use Tools in Haystack. 99 100 ### With ChatGenerator and ToolInvoker 101 102 ```python 103 from haystack.components.generators.chat import OpenAIChatGenerator 104 from haystack.components.tools import ToolInvoker 105 from haystack.dataclasses import ChatMessage 106 107 ## Create a toolset with the math tools 108 math_toolset = Toolset([add_tool, subtract_tool]) 109 110 chat_generator = OpenAIChatGenerator(model="gpt-4o-mini", tools=math_toolset) 111 112 ## Initialize the Tool Invoker with the weather tool 113 tool_invoker = ToolInvoker(tools=math_toolset) 114 115 user_message = ChatMessage.from_user("What is 10 minus 5?") 116 117 replies = chat_generator.run(messages=[user_message])["replies"] 118 print(f"assistant message: {replies}") 119 120 ## If the assistant message contains a tool call, run the tool invoker 121 if replies[0].tool_calls: 122 tool_messages = tool_invoker.run(messages=replies)["tool_messages"] 123 print(f"tool result: {tool_messages[0].tool_call_result.result}") 124 ``` 125 126 Output: 127 128 ``` 129 assistant message: [ChatMessage(_role=<ChatRole.ASSISTANT: 'assistant'>, _content=[ToolCall(tool_name='subtract', arguments={'a': 10, 'b': 5}, id='call_awGa5q7KtQ9BrMGPTj6IgEH1')], _name=None, _meta={'model': 'gpt-4o-mini-2024-07-18', 'index': 0, 'finish_reason': 'tool_calls', 'usage': {'completion_tokens': 18, 'prompt_tokens': 75, 'total_tokens': 93, 'completion_tokens_details': CompletionTokensDetails(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=0, rejected_prediction_tokens=0), 'prompt_tokens_details': PromptTokensDetails(audio_tokens=0, cached_tokens=0)}})] 130 tool result: 5 131 ``` 132 133 ### In a Pipeline 134 135 ```python 136 from haystack import Pipeline 137 from haystack.components.converters import OutputAdapter 138 from haystack.components.generators.chat import OpenAIChatGenerator 139 from haystack.components.tools import ToolInvoker 140 from haystack.dataclasses import ChatMessage 141 142 math_toolset = Toolset([add_tool, subtract_tool]) 143 144 pipeline = Pipeline() 145 pipeline.add_component( 146 "llm", 147 OpenAIChatGenerator(model="gpt-4o-mini", tools=math_toolset), 148 ) 149 pipeline.add_component("tool_invoker", ToolInvoker(tools=math_toolset)) 150 pipeline.add_component( 151 "adapter", 152 OutputAdapter( 153 template="{{ initial_msg + initial_tool_messages + tool_messages }}", 154 output_type=list[ChatMessage], 155 unsafe=True, 156 ), 157 ) 158 pipeline.add_component("response_llm", OpenAIChatGenerator(model="gpt-4o-mini")) 159 pipeline.connect("llm.replies", "tool_invoker.messages") 160 pipeline.connect("llm.replies", "adapter.initial_tool_messages") 161 pipeline.connect("tool_invoker.tool_messages", "adapter.tool_messages") 162 pipeline.connect("adapter.output", "response_llm.messages") 163 164 user_input = "What is 2+2?" 165 user_input_msg = ChatMessage.from_user(text=user_input) 166 167 result = pipeline.run( 168 { 169 "llm": {"messages": [user_input_msg]}, 170 "adapter": {"initial_msg": [user_input_msg]}, 171 }, 172 ) 173 174 print(result["response_llm"]["replies"][0].text) 175 ``` 176 177 Output: 178 179 ``` 180 2 + 2 equals 4. 181 ``` 182 183 ### With the Agent 184 185 ```python 186 from haystack.components.agents import Agent 187 from haystack.dataclasses import ChatMessage 188 from haystack.components.generators.chat import OpenAIChatGenerator 189 190 agent = Agent( 191 chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), 192 tools=math_toolset, 193 ) 194 195 response = agent.run(messages=[ChatMessage.from_user("What is 4 + 2?")]) 196 197 print(response["messages"][-1].text) 198 ``` 199 200 Output: 201 202 ``` 203 4 + 2 equals 6. 204 ```