Skip to main content
Use the orchestrate tools import command to import the tools you create in your active environment. The type of the tool that you import can be controlled by the tool kind flag (-k or --kind). There are two types of tools which can be imported: Python tools and OpenAPI tools.

​
Importing Python tools

Python tools can be imported in two different ways: as a single Python tool file and as a multi Python tool files.
Note: Both subtypes use the same tool kind CLI flag value.

​
Importing a single Python tool file

This importing type can be used when all the Python code that your tool needs are housed in a single .py file. Typically, a single file import can be initiated through omitting the package root CLI flag (--package-root or -r). Setting the value of said CLI flag to an empty string or white space will also have the same effect. Let’s assume that the single file tool is placed in the following folder structure, relative to the root of an assumed working directory.
BASH
─── my_agentic_project/
    └── agents/
    └── connections/
    └── tools/
        └── single_file_tool/
            └── sample_tool.py
            └── requirements.txt
        └── multi_file_tool/
            └── utils/
               └── auth_utils.txt
               └── __init__.py
            └── my_tool.py
            └── requirements.txt
The following are the contents of orchestrate_tools/py/single_file_tool/source/sample_tool.py.
Python
# sample_tool.py
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission


@tool(name="orchestrator_single_file_sample_tool", description="the description", permission=ToolPermission.ADMIN)
def my_tool(input: str) -> str:
    # functionality of the tool that performs some magic.
Then, the following is the command that you have to run to import this tool.
BASH
orchestrate tools import -k python \
    -f "orchestrate_tools/py/single_file_tool/source/sample_tool.py" \
    -r "orchestrate_tools/py/single_file_tool/requirements.txt"
Note:
  • The system will only accept strings composed of alphanumeric characters and underscores (_) in the name attribute of the @tool decorator in sample_tool.py.
  • The system will only accept tool file names composed of alphanumeric characters and underscores (_).

​
Importing a multi Python tool files

In case that the tool you want to import into watsonx Orchestrate is more complex and spans several files and folders, the system allows you to provide a package root folder which houses all the files and folders your tool requires during import. Let’s assume that the multifile tool has the following folder structure, relative to the root of an assumed working directory.
BASH
─── orchestrate_tools/
    └── py/
        └── multi_file_tool/ 
            └── requirements.txt
            └── source/ 
                └── tool_entry_point.py 
                └── requirements.txt
                └── sub_module/ 
                    └── sub_module_index.py
                    └── mod_utils.py
                    └── requirements.txt
                └── resources/ 
                    └── logo.png
                    └── sample_data.csv
The following are the contents of orchestrate_tools/py/multi_file_tool/source/tool_entry_point.py.
Python
# tool_entry_point.py.py
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
# imports that reference code in "sub_module", etc.  


@tool(name="multi_file_tool_sample", description="multi file tool description", permission=ToolPermission.READ_ONLY)
def multi_file_tool_main(input: str) -> str:
    # functionality of the tool that does some magic.
Then, the following example command shows you how to import a multifile tool.
BASH
orchestrate tools import \
    -k python \
    -f "orchestrate_tools/py/multi_file_tool/source/tool_entry_point.py" \
    -p "orchestrate_tools/py/multi_file_tool" \
    -r "orchestrate_tools/py/multi_file_tool/source/requirements.txt"
Notes:
  • The system will only accept strings composed of alphanumeric characters and underscores (_) in the name attribute of the @tool decorator in tool_entry_point.py.
  • The system will only accept tool file names composed of alphanumeric characters and underscores (_).
  • The package root folder and the tool file path CLI flags MUST share a common base path.
  • The path of the tool file folder relative to the package root folder, must be composed of folder names which are only composed of alphanumeric characters and underscores (_).
  • Any whitespace like characters which prefix or suffix provided package root path will be stripped by the system.
  • A package root folder path that resolves to an empty string will make the system assume that no package root was specified. Then, the system falls back to single Python file tool import.

​
Importing OpenAPI tools

This requires a yaml (.yaml/.yml) or json (.json) file passed through the --file of -f flag. This yaml or json should be a valid OpenAPI spec for the API you want to generate tools from. 
orchestrate tools import -k openapi -f <path to openapi spec>
⌘I