Why Custom Tools Matter

Large Language Models (LLMs) are great at conversational synthesis, but on their own, they cannot query your company database, call an internal microservice, or run deterministic business calculations.

In IBM watsonx Orchestrate (WXO), tools give your AI agents hands and feet. You can write custom logic in plain Python, decorate it with @tool, and publish it directly to your Orchestrate catalog. From there, the LLM autonomously extracts parameters from conversational dialogue and executes your Python code.

In this quick, hands-on tutorial (adapted from Lab 1 of our WXO Labs & Tutorial Guide), we will build, deploy, and chat with your very first custom Python tool and native AI agent from scratch in under 15 minutes.

Prerequisites

Before starting, ensure you have:

1. Python 3.10+ installed on your workstation.
2. The IBM watsonx Orchestrate CLI installed:

pip install ibm-watsonx-orchestrate

Verify your CLI environment is active:

orchestrate env list

Step 1: Write Your Python Tool (greetings.py)

Create a new folder for your project and create a file named greetings.py:

from ibm_watsonx_orchestrate import tool

@tool
def greet_user(name: str) -> str:
    """
    Generate a personalized greeting for a user.

    Args:
        name: The name of the person to greet.

    Returns:
        A friendly greeting message.
    """
    return f"Hello, {name}! Welcome to IBM watsonx Orchestrate."

What makes this work?

• @tool decorator: Automatically registers the Python function as an Orchestrate tool.
• Type annotations (name: str): Orchestrate inspects Python type hints to generate the JSON Schema.
• Docstrings: The LLM reads the function description and Args: documentation to decide when to call the tool and which arguments to parse from the user prompt!

Step 2: Create requirements.txt

Create a requirements.txt file in the same directory to declare the tool dependency:

ibm-watsonx-orchestrate>=2.9.0

Step 3: Import the Tool into WXO Catalog

Run the following CLI command to package and upload your Python tool to your Orchestrate environment:

orchestrate tools import -k python -f greetings.py -r requirements.txt

You should see:

[INFO] - Successfully imported tool 'greet_user'

Verify that it appears in your catalog:

orchestrate tools list | grep greet_user

Step 4: Define Your AI Agent (agent.yaml)

Now let's build an AI agent that knows how to use our new tool. Create a file named agent.yaml:

spec_version: v1
kind: native
name: hello_world_greeter
title: "Hello World Greeter"
description: "A friendly onboarding agent that greets users using custom Python tools."
model: ibm/granite-3-8b-instruct
instructions: |
  You are a friendly and welcoming assistant.
  When a user introduces themselves or asks you to greet someone, extract their name
  and call the `greet_user` tool to deliver a personalized welcome.
tools:
  - greet_user

Step 5: Deploy & Test Your Agent

Import and deploy your agent with two simple commands:

# 1. Import the agent manifest
orchestrate agents import -f agent.yaml

# 2. Deploy to active environment
orchestrate agents deploy -n hello_world_greeter

Now, test your agent conversationally in your terminal:

orchestrate chat ask -n hello_world_greeter "Say hello to Markus"

Live Response:

[hello_world_greeter] Hello, Markus! Welcome to IBM watsonx Orchestrate.

The agent parsed your prompt, recognized that it should greet "Markus", extracted name="Markus", called greet_user(name="Markus") in Python, and returned the greeting!

Challenge: Add Multi-Language Greetings!

Try modifying greetings.py to support a language parameter:

from ibm_watsonx_orchestrate import tool

@tool
def greet_user(name: str, language: str = "en") -> str:
    """
    Generate a personalized greeting in the requested language.

    Args:
        name: The person to greet.
        language: Language code ('en' for English, 'es' for Spanish, 'fr' for French, 'de' for German).
    """
    greetings = {
        "en": f"Hello, {name}! Welcome to IBM watsonx Orchestrate.",
        "es": f"¡Hola, {name}! Bienvenido a IBM watsonx Orchestrate.",
        "fr": f"Bonjour, {name}! Bienvenue dans IBM watsonx Orchestrate.",
        "de": f"Guten Tag, {name}! Willkommen bei IBM watsonx Orchestrate."
    }
    return greetings.get(language.lower(), greetings["en"])

Re-import the tool:

orchestrate tools import -k python -f greetings.py -r requirements.txt

Now ask your agent:

orchestrate chat ask -n hello_world_greeter "Greet Carlos in Spanish"

The agent will automatically map language="es" and reply in Spanish!

What's Next in the Series?

Congratulations! You have completed Lab 1. This is the first of 15 progressive hands-on labs designed to take you from foundational Python tools to enterprise production architectures:

• Foundation (Labs 1-3): UI input defaults, file uploads, and document parsing pipelines.
• Intermediate (Labs 4-8): Ambient user context injection ({wxo_user_name}), async long-running jobs, file streaming, and Model Context Protocol (MCP) servers.
• Advanced (Labs 9-11, 15): Role-Based Access Control (RBAC), Entra ID SSO, CI/CD export/import, and remote containerized MCP services.
• Expert (Labs 12-14): Enterprise audit vaults, live observability dashboards, and RAG evaluation pipelines.

Explore the complete interactive curriculum and source code:

• Interactive Portal: https://markusvankempen.github.io/wxo-labs/
• GitHub Repository: https://github.com/markusvankempen/wxo-labs
• Author Research: https://markusvankempen.github.io/

Author: Markus van Kempen | mvk@ca.ibm.com
Research | Floor 7½ 🏢🤏
No bug too small, no syntax too weird.