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](https://rancherdesktop.io/) or [Colima](https://github.com/abiosoft/colima). Please make sure your instance of Rancher or Colima is configured with the following settings: * [Rancher](./_docs/recommended-docker-settings/rancher-settings.md) * [Colima](./_docs/recommended-docker-settings/coilma-settings.md) ------------------------------------------ ## Getting started In order to install the watonx Orchestrate Agent Developer Kit simply run: ```bash 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](https://developer.watson-orchestrate.ibm.com/) to get started building today! ```bash $ 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 │ │ skills Interact with the skills 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 │ │ controls Configure controls to protect and manage your AI assets │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` ## watsonx Orchestrate Developer Edition The Developer Edition of Watsonx Orchestrate can be installed following the instructions [here](https://developer.watson-orchestrate.ibm.com/developer_edition/wxOde_setup). After which you will be able to start, activate, import into and rapidly reset a local server of watsonx Orchestrate. ### Starting the Developer Edition ```bash 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: ```bash $ 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: ```bash pip install -e packages/core \ -e packages/clients \ -e packages/agentic-sdk \ -e packages/mcp-server \ -e ".[dev]" ``` Run tests: ```bash hatch run test ``` Run coverage report: ```bash hatch run cov ``` ## Reporting issues Customers of watsonx Orchestrate can raise issues with the ADK or the Developer Edition server to [IBM Support](https://www.ibm.com/mysupport/s/topic/0TO3p000000A6YLGA0/watsonx-orchestrate?productId=01t3p00000SsRnhAAF&language=en_US).