Toolkit¶

class ibm_watsonx_ai.foundation_models.utils.Toolkit(api_client, params=None)[source]¶

Bases: WMLResource

Toolkit for utility agent tools.

Parameters:

api_client (APIClient) – initialized APIClient object
params (dict[str, dict], optional) – dict of config parameters for each tool, e.g. {“GoogleSearch”: {“maxResults”: 2}}

Example:

from ibm_watsonx_ai import APIClient, Credentials
from ibm_watsonx_ai.foundation_models.utils import Toolkit

credentials = Credentials(
    url = "<url>",
    api_key = IAM_API_KEY
)
tools_params = {
    "GoogleSearch": {"maxResults": 2}
}

api_client = APIClient(credentials)
toolkit = Toolkit(api_client=api_client, params=tools_params)

get_tool(tool_name)[source]¶

Get a utility agent tool with the given tool_name.

Parameters:: tool_name (str) – name of a specific tool
Returns:: tool with a given name
Return type:: Tool

Examples

toolkit = Toolkit(api_client=api_client)
google_search = toolkit.get_tool(tool_name='GoogleSearch')

get_tools()[source]¶

Get list of available utility agent tools. Cache tools as Tool objects on first call in Toolkit instance.

Returns:: list of available tools
Return type:: list[Tool]

Examples

toolkit = Toolkit(api_client=api_client)
tools = toolkit.get_tools()

Tool¶

class ibm_watsonx_ai.foundation_models.utils.Tool(api_client, name, description, agent_description=None, input_schema=None, config_schema=None, config=None)[source]¶

Bases: WMLResource

Instantiate the utility agent tool.

Parameters:

api_client (APIClient) – initialized APIClient object
name (str) – name of the tool
description (str) – description of what the tool is used for
agent_description (str, optional) – the precise instruction to agent LLMs and should be treated as part of the system prompt, if not provided, description can be used in its place
input_schema (dict, optional) – schema of the input that is provided when running the tool if applicable
config_schema (dict, optional) – schema of the config that is provided when running the tool if applicable
config (dict, optional) – configuration options that can be passed for some tools, must match the config schema for the tool

get(key, default=None)[source]¶

run(input, config=None)[source]¶

Run a utility agent tool given input.

Parameters:

input – input to be used when running tool
config (dict, optional) – configuration options that can be passed for some tools, must match the config schema for the tool

Returns:

the output from running the tool

Return type:

dict

Example for the tool without input schema:

toolkit = Toolkit(api_client=api_client)
google_search = toolkit.get_tool(tool_name='GoogleSearch')
result = google_search.run(input="Search IBM")

Example for the tool with input schema:

toolkit = Toolkit(api_client=api_client)
weather_tool = toolkit.get_tool(tool_name='Weather')
tool_input = {"location": "New York"}
result = weather_tool.run(input=tool_input)

Converters¶

ibm_watsonx_ai.foundation_models.utils.convert_to_watsonx_tool(utility_tool)[source]¶

Convert utility agent tool to watsonx tool format.

Parameters:: utility_tool (Tool) – utility agent tool
Returns:: watsonx tool structure
Return type:: dict

Examples

from ibm_watsonx_ai.foundation_models.utils import Toolkit

toolkit = Toolkit(api_client)
weather_tool = toolkit.get_tool("Weather")
convert_to_watsonx_tool(weather_tool)

# Return
# {
#     "type": "function",
#     "function": {
#         "name": "Weather",
#         "description": "Find the weather for a city.",
#         "parameters": {
#             "type": "object",
#             "properties": {
#                 "location": {
#                     "title": "location",
#                     "description": "Name of the location",
#                     "type": "string",
#                 },
#                 "country": {
#                     "title": "country",
#                     "description": "Name of the state or country",
#                     "type": "string",
#                 },
#             },
#             "required": ["location"],
#         },
#     },
# }

ibm_watsonx_ai.foundation_models.utils.convert_to_utility_tool_call(tool_call)[source]¶

Convert json format tool call to utility tool call format.

Parameters:: tool_call (dict) – watsonx tool call
Returns:: utility tool call
Return type:: dict

Examples

tool_call = {
    "id": "rcWg61ytv",
    "type": "function",
    "function": {"name": "GoogleSearch", "arguments": '{"input": "IBM"}'},
}
convert_to_utility_tool_call(tool_call)

# Return
# {"input": "IBM", "tool_name": "GoogleSearch"}