{"id":23871,"library":"ibm-watsonx-orchestrate","title":"IBM watsonx Orchestrate Python SDK","description":"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.","status":"active","version":"2.9.0","language":"python","source_language":"en","source_url":"https://github.com/IBM/watsonx-orchestrate-python-sdk","tags":["ai","orchestration","skills","assistants","ibm-watsonx"],"install":[{"cmd":"pip install ibm-watsonx-orchestrate","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core authentication and HTTP client for IBM Cloud services","package":"ibm-cloud-sdk-core","optional":false},{"reason":"Required for invoking watsonx.ai models within skills","package":"ibm-watsonx-ai","optional":false}],"imports":[{"note":"Direct import from package root is correct; old documentation sometimes showed an 'api' submodule.","wrong":"from ibm_watsonx_orchestrate.api import Orchestrate","symbol":"Orchestrate","correct":"from ibm_watsonx_orchestrate import Orchestrate"},{"note":"Skill class is now at package top level, not in models submodule.","wrong":"from ibm_watsonx_orchestrate.models import Skill","symbol":"Skill","correct":"from ibm_watsonx_orchestrate import Skill"},{"note":"SkillConfig moved to skills module in v2.x.","wrong":"from ibm_watsonx_orchestrate.config import SkillConfig","symbol":"SkillConfig","correct":"from ibm_watsonx_orchestrate.skills import SkillConfig"}],"quickstart":{"code":"from ibm_watsonx_orchestrate import Orchestrate, Skill\n\norchestrate = Orchestrate(\n    api_key=os.environ.get('WATSONX_API_KEY', ''),\n    url=os.environ.get('WATSONX_URL', '')\n)\n\n# Create a skill\nskill = Skill(\n    name='HelloSkill',\n    description='A simple greeting skill',\n    actions=[\n        {\n            'name': 'greet',\n            'description': 'Greets the user',\n            'type': 'function',\n            'function': {\n                'parameters': {\n                    'type': 'object',\n                    'properties': {\n                        'name': {'type': 'string'}\n                    }\n                }\n            }\n        }\n    ]\n)\n\n# Deploy the skill\nresponse = orchestrate.skills.create(skill)\nprint(f'Skill created: {response['result']['id']}')\nprint('Quickstart complete!')","lang":"python","description":"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."},"warnings":[{"fix":"Update imports: `from ibm_watsonx_orchestrate import Orchestrate`. Replace `iam_apikey` parameter with `api_key`.","message":"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.","severity":"breaking","affected_versions":"<=1.x -> 2.0+"},{"fix":"Replace `list()` with `search()` and adjust parameters if needed.","message":"Method `orchestrate.skills.list()` is deprecated in favor of `orchestrate.skills.search()`.","severity":"deprecated","affected_versions":">=2.5.0"},{"fix":"Wrap calls with `tenacity` or `backoff` to handle retries.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install latest version and use `from ibm_watsonx_orchestrate import Orchestrate`.","cause":"Using an outdated import path (e.g., from `ibm_watsonx_orchestrate.api`).","error":"ImportError: cannot import name 'Orchestrate' from 'ibm_watsonx_orchestrate'"},{"fix":"Replace `iam_apikey` with `api_key`. Example: `Orchestrate(api_key='...', url='...')`.","cause":"Migrating from v1.x to v2.x without updating the authentication parameter.","error":"TypeError: Orchestrate.__init__() got an unexpected keyword argument 'iam_apikey'"},{"fix":"Ensure `WATSONX_API_KEY` is set and valid. Verify the API key has permissions to use watsonx Orchestrate.","cause":"API key is missing, incorrect, or not authorized for watsonx Orchestrate.","error":"ibm_cloud_sdk_core.api_exception.ApiException: Error: Invalid API key, Error code: 400"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}