Create tools for your agents. With ADK, tools can be created using a Python program or an OpenAPI specification.

​
Creating Python-Based Tools

Python tools are created based on the functions of a Python file. To create a Python-based tool, include the @tool decorator and a docstring in your python function. These elements identify the function to be converted into a tool and provide a description that helps the agent understand the tool’s usage. Apart from the mandatory @tool decorator and docstring, you can design your Python function as needed to perform the desired actions. If your function requires inputs and outputs, you can use native Python types and Pydantic typings. Python tool example
Python
#test_tool.py
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission


@tool(name="myName", description="the description", permission=ToolPermission.ADMIN)
def my_tool(input: str) -> str:

    """
    This is my tool.
 
    :param input: The input of my tool.
    :returns: The action of my tool.
    """

    #functionality of the tool
If your Python function relies on external libraries or packages, you can ensure your tool works correctly by specifying these dependencies in the requirements.txt file. Python tool example
Python
#test_tool.py
import pytz
from timezonefinder import TimezoneFinder
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission


@tool(name="myName", description="the description", permission=ToolPermission.ADMIN)
def my_tool(input: str) -> str:

    """
    This is my tool.

    :param input: The input of my tool.
    :returns: The action of my tool.
    """

    #functionality of the tool
requirements.txt example
TEXT
pytz
timezonefinder

​
Creating tools that accept files

You can create Python tools that accept files or return files to download. To do that, you must comply with the following requirements:
  • To accept files as input, the tool must accept a sequence of bytes as arguments.
  • To return a file for download, the tool must return a sequence of bytes as output.
The following example accepts a file as input and returns the processed file for download: 
from typing import Union
from io import BytesIO
from typing import Any
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
import base64

@tool(permission=ToolPermission.READ_ONLY)
def create_image_with_filter(name: str, age: int, image_bytes: bytes) -> bytes:
    """
    Gets user information, processes the image with a filter, and returns the processed image

    :returns: Image details
    """
    import cv2
    import numpy as np
    from typing import Union
    from io import BytesIO
    # Convert bytes to numpy array
    image_array = np.frombuffer(image_bytes, np.uint8)
    image = cv2.imdecode(image_array, cv2.IMREAD_COLOR)

    if image is None:
        raise ValueError("Invalid image bytes provided")

    # Apply bilateral filter for smoothing while preserving edges
    smooth = cv2.bilateralFilter(image, d=9, sigmaColor=75, sigmaSpace=75)

    # Convert to grayscale and detect edges
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    edges = cv2.medianBlur(gray, 7)
    edges = cv2.adaptiveThreshold(
        edges, 255, cv2.ADAPTIVE_THRESH_MEAN_C, 
        cv2.THRESH_BINARY, blockSize=9, C=2
    )

    # Convert edges to color image
    edges_colored = cv2.cvtColor(edges, cv2.COLOR_GRAY2BGR)

    # Combine smoothed image with edges
    cartoon = cv2.bitwise_and(smooth, edges_colored)

    # Enhance color saturation
    hsv = cv2.cvtColor(cartoon, cv2.COLOR_BGR2HSV)
    hsv[..., 1] = cv2.multiply(hsv[..., 1], 1.4)  # increase saturation
    cartoon_enhanced = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)

    # Convert back to bytes
    success, buffer = cv2.imencode('.jpg', cartoon_enhanced)
    if not success:
        raise RuntimeError("Failed to encode image")
    
    return buffer.tobytes()

​
Creating OpenAPI based tools

OpenAPI tools are created based on an OpenAPI specification file. To import an OpenAPI tool, configure the servers and paths properties; the entire OpenAPI specification file is not required.
YAML
servers:
- url: mytoolserver
paths:
/:
   get:
      operationId: myTool
      summary: myName
      description: the description
      requestBody:
         ...
      responses:
         ...
You can import asynchronous APIs as tools using an OpenAPI specification. To support this, the OpenAPI specification must include a callback schema and an input parameter named callbackUrl. Use callbackUrl exactly as the parameter name; other names are not supported.
YAML
servers:
  - url: mytoolserver
paths:
/:
   post:
      operationId: myTool
      summary: myName
      description: the description
      parameters:
        - in: header
          name: callbackUrl
          description: The callback URL
          required: true
          schema:
            type: string
      requestBody:
         ...
      callbacks:
        callback:
          '{$request.header.callbackUrl}':
            post:
              requestBody:
              ...
              responses:
              ...