The watsonx Orchestrate Agent Development Kit (ADK)
May 28, 2026 · View on GitHub
Important Links:
ADK Documentation, Agent Connect & Examples.The IBM watsonx Orchestrate Agent Development Kit (ADK) is a set of tools designed to make it easy to build and deploy agents using IBM watsonx Orchestrate. It is packaged as a Python library and command line tool that allows builders to configure agents that run on the IBM watsonx Orchestrate platform. The ADK also supports integrating agents and tools built on other frameworks.
These agents and tools can be run developed locally via an offering known as the watsonx Orchestrate Developer Edition, a fully self-contained local copy of watsonx Orchestrate that can run on your laptop or desktop where you can rapidly iterate in isolation.
Once you are satisfied with what you built, it is possible to connect the ADK to a production instance of watsonx Orchestrate to share what you have built locally with your team and run at scale!
To learn more, check out our ADK Documentation!
Prerequisites
The Agent Developer Kit (ADK)
Python 3.11-3.14
Ensure you have Python 3.11-3.14 installed.
watsonx Orchestrate Developer Edition
Machine Specs
- 16GB RAM
- 8 cores
- 25GB disk space
Note: If you run with Document Processing enabled, you will need at least an additional 3GB of memory (i.e., a total of 19GB RAM) to ensure stable operation.
A docker engine Ensure that you have a docker engine installed capable of running docker compose. The watsonx Orchestrate team recommends either Rancher or Colima.
Please make sure your instance of Rancher or Colima is configured with the following settings:
Getting started
In order to install the watonx Orchestrate Agent Developer Kit simply run:
pip install --upgrade ibm-watsonx-orchestrate
The ADK command line tool
After installation, you will have access to the WXO CLI tool. This tool can be accessed using the orchestrate command
which exposes the following functionality.
Check out our documentation to get started building today!
$ orchestrate --help
Usage: orchestrate [OPTIONS] COMMAND [ARGS]...
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version Show the installed version of the ADK and Developer Edition Tags │
│ --debug Enable debug mode │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ env Add, remove, or select the activate env other commands will interact with (either your local server or a production instance) │
│ agents Interact with the agents in your active env │
│ tools Interact with the tools in your active env │
│ toolkits Interact with the toolkits in your active env │
│ knowledge-bases Upload knowledge your agents can search through to your active env │
│ connections Manage authentication connections for external systems in your active env │
│ voice-configs Configure voice providers to enable voice interaction with your agents │
│ server Manipulate your local Orchestrate Developer Edition server │
│ chat Launch the chat ui and CLI chat interface for your local Developer Edition server │
│ models List the available large language models (llms) that can be used in your agent definitions │
│ channels Configure channels where your agent can exist on (such as embedded webchat, whatsapp, etc.) │
│ phone Manage phone configurations (global resources that can be attached to multiple agents) │
│ evaluations Evaluate the performance of your agents in your active env │
│ settings Configure the settings for your active env │
│ partners Generate a well-structured, submission-ready agent artifact package for partner-built agents │
│ observability Search and export trace data from the observability platform for analysis in third-party tools │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
watsonx Orchestrate Developer Edition
The Developer Edition of Watsonx Orchestrate can be installed following the instructions here. After which you will be able to start, activate, import into and rapidly reset a local server of watsonx Orchestrate.
Starting the Developer Edition
orchestrate server start --help
Usage: orchestrate server start [OPTIONS]
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --env-file -e TEXT Path to a .env file that overrides default.env. Then environment variables override both. │
│ [default: None] │
│ --with-langfuse -l Option to enable Langfuse support. │
│ --with-ibm-telemetry -i │
│ --accept-terms-and-conditions By providing this flag you accept the terms and conditions outlined in the logs on server start. │
│ --with-doc-processing -d Enable IBM Document Processing to extract information from your business documents. Enabling this │
│ activates the Watson Document Understanding service. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Example:
$ orchestrate server start -e .env
[INFO] - Logging into Docker registry: us.icr.io ...
[INFO] - Successfully logged in to Docker.
[INFO] - Detected architecture: arm64, using DBTAG: 22-04-2025
[INFO] - Starting database container...
[+] Running 1/0
✔ Container docker-wxo-server-db-1 Running 0.0s
[INFO] - Database container started successfully. Now starting other services...
[INFO] - Starting docker-compose services...
[+] Running 11/0
✔ Container docker-wxo-builder-1 Running 0.0s
✔ Container docker-wxo-server-redis-1 Running
Skipping already applied migration: 00_init_db.sql
Skipping already applied migration: 20250422.sql
[INFO] - Migration ran successfully.
[INFO] - Waiting for orchestrate server to be fully initialized and ready...
[INFO] - Orchestrate services initialized successfully
[INFO] - local tenant found
[INFO] - You can run `orchestrate env activate local` to set your environment or `orchestrate chat start` to start the UI service and begin chatting.
$ orchestrate env activate local
$ orchestrate tools import -k python -f my_tool.py -r requirements.txt
$ orchestrate agents import -f my-agent.yaml
$ orchestrate chat start
Running tests
Install dev dependencies:
pip install -e ".[dev]"
Run tests:
hatch run test
Run coverage report:
hatch run cov
Reporting issues
Customers of watsonx Orchestrate can raise issues with the ADK or the Developer Edition server to IBM Support.