Part 1 of 15 • 🟢 Easy (Beginner) • ⏱️ 30 minutes

Getting Started with watsonx Orchestrate: Build Your First Custom Python Tool & AI Agent in 15 Minutes

Step-by-step hands-on tutorial on writing Python tools with @tool, configuring Granite 3 agents in YAML, and testing live via CLI.

#watsonxOrchestrate#AIAgents#Python#Granite3#CLI#BeginnerTutorial#EnterpriseAI

Why This Pattern Matters

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.

Step 1: Write Tool Logic (`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."

Step 2: Dependencies (`requirements.txt`)

ibm-watsonx-orchestrate>=2.9.0

Step 3: Agent Manifest (`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 4: Live Execution

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

╭─ 🤖 hello_world_greeter ───────────────────────────────────────────────╮
│                                                                        │
│  Hello, Markus! Welcome to IBM watsonx Orchestrate.                    │
│                                                                        │
╰────────────────────────────────────────────────────────────────────────╯

💡 Pro Tips & Architecture Insights

💡 The @tool decorator

Automatically registers the function signature and docstrings into the tool JSON Schema.

💡 Type annotations

Parameter types like name: str are required by Orchestrate to generate the API contract for the LLM.

💡 ModuleNotFoundError

Always include -r requirements.txt when importing tools via CLI.

📋 Open IBM Community Ready HTML