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.
Choosing between standalone tools and toolkits:You can import Python tools as standalone tools (using this page’s instructions) or group them into Python toolkits for better performance. For help deciding which approach is right for your scenario, see Choosing a tool type.Key differences:
  • Standalone Python tools: Process-per-invocation model, supports non-thread-safe operations, ~100-300ms overhead per call
  • Python toolkits: Shared process model, requires thread-safety, no process overhead, better for frequently called tools
For migration guidance from standalone tools to toolkits, see Migrating to Python toolkits.
For Python tools: Dependencies specified in requirements.txt are installed server-side at deployment time, not during import. For details on dependency management, see Python dependency management.

​
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.
When to use standalone Python tools:
  • You have a single, independent tool
  • The tool uses non-thread-safe operations (file I/O, global state, etc.)
  • You need process isolation between tool invocations
  • You’re prototyping or testing a new tool
  • The tool is called infrequently (less than 10 times per minute)
When to use Python toolkits instead:
  • You have multiple related tools that are thread-safe
  • Tools are called frequently and performance matters
  • You want to share dependencies across tools
  • You’re deploying to live premium environment
For detailed guidance, see Choosing a tool type.

​
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 (_).
  • Dependencies in requirements.txt will be installed server-side when the tool is deployed to an environment. See Python dependency management for best practices.

​
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.
  • Dependencies in requirements.txt will be installed server-side when the tool is deployed. For enterprise patterns and best practices, see Python dependency management.

​
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.
BASH
orchestrate tools import -k openapi -f <path to openapi spec>
When to use OpenAPI tools:
  • You have existing REST APIs to expose as tools
  • You want declarative tool definitions without custom code
  • You don’t need custom Python logic
  • Your API already has an OpenAPI specification
For comparison with other tool types, see Choosing a tool type.

​
Next steps