IBM watsonx Orchestrate Python SDK

2.9.0 verified Fri May 01 auth: no python

The IBM watsonx Orchestrate Python SDK (ADK) enables developers to build, orchestrate, and deploy AI assistants and workflows using watsonx Orchestrate capabilities. Current version is 2.9.0, with a rapid release cadence. Requires Python >=3.11,<3.14.

pip install ibm-watsonx-orchestrate

Common errors

error ImportError: cannot import name 'Orchestrate' from 'ibm_watsonx_orchestrate' ↓

cause Using an outdated import path (e.g., from `ibm_watsonx_orchestrate.api`).

fix

Install latest version and use from ibm_watsonx_orchestrate import Orchestrate.

error TypeError: Orchestrate.__init__() got an unexpected keyword argument 'iam_apikey' ↓

cause Migrating from v1.x to v2.x without updating the authentication parameter.

fix

Replace iam_apikey with api_key. Example: Orchestrate(api_key='...', url='...').

error ibm_cloud_sdk_core.api_exception.ApiException: Error: Invalid API key, Error code: 400 ↓

cause API key is missing, incorrect, or not authorized for watsonx Orchestrate.

fix

Ensure WATSONX_API_KEY is set and valid. Verify the API key has permissions to use watsonx Orchestrate.

Warnings

breaking In v2.0, the SDK was restructured: imports changed from `ibm_watsonx_orchestrate.api` to `ibm_watsonx_orchestrate`. The `Orchestrate` client no longer accepts `iam_apikey`; use `api_key` instead. ↓

fix Update imports: `from ibm_watsonx_orchestrate import Orchestrate`. Replace `iam_apikey` parameter with `api_key`.

deprecated Method `orchestrate.skills.list()` is deprecated in favor of `orchestrate.skills.search()`. ↓

fix Replace `list()` with `search()` and adjust parameters if needed.

gotcha The SDK does not automatically retry on rate limits (429 errors). You must implement your own retry logic or use an HTTP client with backoff. ↓

fix Wrap calls with `tenacity` or `backoff` to handle retries.

Imports

Orchestrate
wrong
```
from ibm_watsonx_orchestrate.api import Orchestrate
```
correct
```
from ibm_watsonx_orchestrate import Orchestrate
```
Direct import from package root is correct; old documentation sometimes showed an 'api' submodule.

Skill

wrong

from ibm_watsonx_orchestrate.models import Skill

correct

from ibm_watsonx_orchestrate import Skill

Skill class is now at package top level, not in models submodule.

SkillConfig

wrong

from ibm_watsonx_orchestrate.config import SkillConfig

correct

from ibm_watsonx_orchestrate.skills import SkillConfig

SkillConfig moved to skills module in v2.x.

Quickstart

Initialize the SDK, create a skill with a simple function, and deploy it to watsonx Orchestrate. Requires WATSONX_API_KEY and WATSONX_URL environment variables.

from ibm_watsonx_orchestrate import Orchestrate, Skill

orchestrate = Orchestrate(
    api_key=os.environ.get('WATSONX_API_KEY', ''),
    url=os.environ.get('WATSONX_URL', '')
)

# Create a skill
skill = Skill(
    name='HelloSkill',
    description='A simple greeting skill',
    actions=[
        {
            'name': 'greet',
            'description': 'Greets the user',
            'type': 'function',
            'function': {
                'parameters': {
                    'type': 'object',
                    'properties': {
                        'name': {'type': 'string'}
                    }
                }
            }
        }
    ]
)

# Deploy the skill
response = orchestrate.skills.create(skill)
print(f'Skill created: {response['result']['id']}')
print('Quickstart complete!')