What's new - IBM watsonx Orchestrate ADK

Starting from version 2.0.0, watsonx Orchestrate ADK documentation is now versioned per ADK release. If you want to view a specific ADK documentation version, change the documentation version in the version dropdown located at the top left of the page.

2.16.x

2026-07-31

The watsonx Orchestrate ADK version 2.16.0 is now available!Upgrade to version 2.16.0 to control conversation threading in agentic workflows, configure JWT Bearer connections for service-to-service authentication, set up environments on HIPAA and MCSP V2 clusters, and benefit from expanded document processing capabilities.

⬆️ Upgrade now

To upgrade to version 2.16.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.16.0

🚀 New features

Thread-aware agent node

The AgentNode in agentic workflows now supports a thread_control_policy parameter to control conversation threading across invocations. For more information, see Agent node.

OAuth 2.0 JWT Bearer connections

A new oauth_auth_jwt_bearer_flow connection kind supports service-to-service authentication using signed JWT assertions. For more information, see OAuth 2.0 JWT Bearer connections.

HTML and Markdown output in document text extractor

The document text extractor node now supports html and markdown as output content types in addition to plain text. For more information, see Document text extractor node.

`--iam-url` parameter for environment setup

The orchestrate env add and orchestrate env activate commands now accept a --iam-url flag for HIPAA-regulated clusters and MCSP V2 instances. For more information, see Initiating the environment.

🔧 Enhancements

Error handling in document processing nodes: All document processing nodes now accept an error_handler_config parameter for retry logic and error callbacks
Document classifier and field extractor nodes out of public preview: These nodes are now generally available.
EKS environment support: The ADK CLI now accepts EKS as an environment type (k8s), with full CPD-equivalent functionality.
Workspace commands for CP4D deployments: Workspace management commands now work against CP4D deployments. .

🐛 Bug fixes

Agent import — skill bindings: Fixed a bug where importing a native agent YAML with a skills field stored raw name strings instead of resolving them to server UUIDs.

2.15.x

2026-08-17

The watsonx Orchestrate ADK version 2.15.0 is now available!Upgrade to version 2.15.0 to manage policy controls, use multiple knowledge bases per agent, fine-tune voice idle handler behavior, and export observability traces from external agents directly to the Analytics dashboard.

⬆️ Upgrade now

To upgrade to version 2.15.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.15.0

🚀 New features

Controls management

You can now manage policy controls directly from the CLI using the orchestrate controls command. Controls let you bind policy artifacts — such as PII filters and content guardrails — to agents, tools, and models at configurable execution hooks. Full CRUD operations are supported, including list, list-types, get-type, create, and delete. For more information, see Managing controls.

Multiple knowledge bases per agent

Agents can now reference more than one knowledge base. For more information, see Building an agent.

Voice idle handler new fields

The User Idle Handler and Agent Idle Handler expose new configuration fields for finer control over idle behavior. For more information, see Managing voice configuration.

Observability traces for external agents

Export execution traces from agents running outside watsonx Orchestrate to the Agent Analytics dashboard. Two instrumentation approaches are available:

OpenTelemetry export: Use the standard OpenTelemetry Python SDK with any agentic framework. For more information, see Exporting observability traces with OpenTelemetry.
Observability SDK: Use decorator-based instrumentation from the ibm-watsonx-orchestrate-sdk to instrument LangGraph agents. For more information, see Exporting observability traces with Observability SDK.

🔧 Enhancements

Uninterruptible welcome message for voice agents: Added is_user_barge_in_disabled to the welcome_content schema. When set to true, the user cannot interrupt the agent’s opening voice message. For more information, see Building an agent.
Custom API key header name: The orchestrate connections configure command now accepts a --name flag when the connection kind is api_key, allowing you to override the default api_key header with a custom name such as x-api-key or X-Auth-Token. For more information, see Adding and configuring connections.
Multi-skill agent tutorial: Added an end-to-end tutorial for a multi-skill agent setup under Agent Skills. For more information, see Agent skills.
Welcome message character limit: Updated the recommended character cap from 100 to 1000 characters in the agent build guide and the updateWelcomeScreen Webchat API reference.
On-premises compatibility matrix: Updated the IBM Software Hub compatibility table with the latest supported ADK versions. For more information, see On-premises compatibility.

🐛 Bug fixes

Deepgram Flux STT model false warning: Fixed an issue where using Deepgram flux-general-en or flux-general-multi STT models incorrectly triggered a validation warning. These models are now recognized as valid.

⚠️ Known limitations

Excel file support in Document Extractor (Developer Edition)

The Document Extractor node supports Microsoft Excel (.xlsx) files as input, but this capability is disabled by default in watsonx Orchestrate Developer Edition 2.15.0 and must be enabled manually.To enable Excel file support, add the following line to your .env file and restart the Developer Edition server:

BASH

GLOBAL_WORKER_DOCLING_PIPELINE=true

Limitation: When GLOBAL_WORKER_DOCLING_PIPELINE=true, only one document can be processed at a time. Uploading or ingesting multiple documents concurrently — through Document Processing tools or Knowledge ingestion — may result in failures. This limitation will be addressed in a future release.

2.14.x

2026-08-04

The watsonx Orchestrate ADK version 2.14.0 is now available!Upgrade to version 2.14.0 to enable observability for external agents, configure language support for document processing, add Google TTS voice configurations, and benefit from enhanced flow lifecycle events and connection validation.

⬆️ Upgrade now

To upgrade to version 2.14.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.14.0

🚀 New features

Observability for external agents

External agents can now export traces to any OTEL-compatible backend such as Jaeger or Instana. The SDK includes automatic token refresh, root span creation, tool attributes, and PII decorator support for enhanced observability. For more information, see Traces.

Document processing language support

All document processing nodes (Classifier, Extractor, Text Extractor, Unstructured) now accept an optional language parameter, enabling you to specify the document language for improved processing accuracy. For more information, see:

Google TTS voice configuration

Configure Google Text-to-Speech (TTS) as a voice provider with support for both simple and advanced YAML templates. Advanced configurations allow you to customize pitch, rate, gender, and voice name. For more information, see Managing voice configuration.

Deepgram TTS volume normalization

The Deepgram advanced voice configuration now includes a normalize_volume field to automatically adjust audio output levels for consistent playback. For more information, see Managing voice configuration.

Extended flow lifecycle events

Agentic workflows now support two additional lifecycle event types: on_flow_abort and on_flow_delete. These events enable more comprehensive monitoring and handling of workflow states. For more information, see Configuring callbacks.

Knowledge base credential validation

Credentials are now validated during knowledge base creation and updates before indexing begins. The url field in index_config is now optional, simplifying configuration. For more information, see Building knowledge bases.

Red Hat AI model support

The red_hat_ai provider is now recognized in the CLI, enabling you to register and use Red Hat AI models with watsonx Orchestrate. For more information, see Managing custom LLMs.

Microsoft Copilot Studio agent provider

microsoft_copilot_studio is now a valid external agent provider type, expanding integration options for external agents. For more information, see Connecting to external agents.

Document classifier class limit

A hard upper limit is now enforced on the number of classes in a Document Classifier node at authoring time, preventing configuration errors. For more information, see Document classifier node.

Langflow updated to v1.10.0

Langflow has been updated to version 1.10.0, bringing the latest features and improvements to Langflow tool integration. For more information, see Langflow tools.

🐛 Bug fixes

Flow import crash on empty OpenAPI request schema: Fixed an issue where importing flows with empty OpenAPI request schemas caused the import process to crash.
Custom agent import overwrites existing connections: Fixed an issue where importing custom agents would overwrite existing connections instead of preserving them.
Custom agent hardcoded default LLM removed: Removed the silent fallback to a hardcoded default model in custom agents, ensuring explicit model configuration.
Flow callback tool validation: Fixed an issue where invalid callback shapes were not properly rejected at import time, now providing clear validation errors.
Voice server missing environment variable: Fixed a startup failure for voice-enabled agents caused by a missing environment variable.
get_city_founding_date 403 error: Fixed HTTP 403 errors when querying Wikidata SPARQL by adding the required User-Agent header to requests.

Tool calling: fix for optional parameter handling. Expand the following accordion for more information about the fix:

Tool calling fix

Fixed an issue where optional Python tool parameters explicitly set to null were incorrectly treated as omitted, causing the tool’s default value to be applied instead.With this fix, explicitly passing null for an optional parameter preserves the null value.This change affects Python tools with Optional[T] parameters that have a non-None default value. If your tool relied on null being replaced by the default, it will now receive None instead.Review your tools and add an explicit None check wherever your logic depends on the default value:

Python

from typing import Optional
from ibm_watsonx_orchestrate.agent_builder.tools import tool

@tool
def get_city(city: Optional[str] = "San Francisco") -> str:
    """Returns the city name.

    Args:
        city (Optional[str]): The city name. Defaults to San Francisco.

    Returns:
        str: The city name.
    """
    if city is None:
        return "No city provided"
    return city

Expected results:

get_city(city=None)           # → "No city provided"   (null preserved, default not applied)
get_city(city="London")       # → "London"
get_city()                    # → "San Francisco"       (default applied, argument omitted)

If None is never a valid value for a parameter, use a plain type with a default value instead of Optional[T]:

Python

from ibm_watsonx_orchestrate.agent_builder.tools import tool

@tool
def get_city(city: str = "San Francisco") -> str:
    """Returns the city name.

    Args:
        city (str): The city name. Defaults to San Francisco.

    Returns:
        str: The city name.
    """
    return city

Expected results:

get_city(city="London")  # → "London"
get_city()               # → "San Francisco"  (default applied, argument omitted)
# null cannot be passed — city is a plain str, not Optional

2.13.x

2026-07-22

The watsonx Orchestrate ADK version 2.13.0 is now available!Upgrade to version 2.13.0 to surface observations in traces, suppress agent summarization, extract documents by page range, work with agent skills, benefit from extended callback events, and new model support.

⬆️ Upgrade now

To upgrade to version 2.13.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.13.0

🚀 New features

Traces update

Traces now surface observations instead of spans, with a simplified search model that filters by time range, user ID, and session ID. The CLI also gains a new --last flag for relative time windows as a shorthand alternative to --start-time / --end-time. For more information, see Traces.

Suppress agent summarization

A new suppress_agent_summarization configuration option allows builders to suppress agent reasoning output when an agentic workflow ends, preventing duplicate information from being presented in chat after a flow completes. For more information, see Building a flow.

Page range support for document field and text extractor nodes

The docext() and docproc() nodes in agentic workflows now support a page_range parameter, letting you limit extraction to a specific range of pages. For more information, see Document field extractor node and Document text extractor node.

Extended event support and payload schema for agentic workflow callbacks

Agentic workflow callbacks now support two additional lifecycle events — ON_FLOW_ABORT and ON_FLOW_DELETE — bringing the total to eight configurable event kinds. Callback tools now receive a structured FlowCallbackEventsPayload that includes elicitation details when a task is waiting for user input, enabling external systems and MCP clients to respond without polling. For more information, see Configuring callbacks.

Agent skills

Work with agent skills using the ADK. Agent skills are portable, version-controlled packages that equip your agents with specialized knowledge and workflows. For more information, see Agent skills.

Premier models

Enable premier models, including GPT-5.4, to use on watsonx Orchestrate. For more information, see Enabling premier models.

Deprecated agent styles

The agent styles default, react, and planner are now deprecated in watsonx Orchestrate. For more information, see Migrating to ReAct Core agent style.

🔧 Enhancements

Python 3.14 support: The ADK now supports Python 3.14.

🐛 Bug fixes

Lima template not found on fresh installation: Fixed an issue where a fresh installation of the Developer Edition failed with a template "_images/ubuntu-lts.yaml" not found error. The limactl binary now correctly locates its bundled templates when installed for the first time.

2.12.x

2026-06-26

The watsonx Orchestrate ADK version 2.12.0 is now available!Upgrade to version 2.12.0 to configure multi-language support for agentic workflows, leverage enhanced decision tables and parallel branches, and benefit from context variable support in LangGraph agents.

⬆️ Upgrade now

To upgrade to version 2.12.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.12.0

🚀 New features

Multi-language support for agentic workflows

Configure multi-language support for user interactions in agentic workflows within ADK. This enables your workflows to communicate with users in their preferred language. For more information, see Multi-language support.

Enhanced decision tables for agentic workflows

Use the updated decision table functionality in agentic workflows to create more sophisticated conditional logic and routing. For more information, see Decision node.

Parallel branch support in agentic workflows

Add parallel branches to your agentic workflows, allowing multiple operations to execute simultaneously for improved efficiency. For more information, see Parallel branch node.

Anti-pattern documentation

Access comprehensive documentation on anti-patterns to help you avoid common pitfalls in agent design and implementation. For more information, see Foundational architecture considerations.

🔧 Enhancements

Context variables in LangGraph agents: Added support for context variables in LangGraph agents, enabling better state management and data flow.
Dutch language support: Dutch (nl-NL) language support is now available for Agentic Orchestrate, expanding language coverage for international deployments.

2.11.x

2026-06-12

The watsonx Orchestrate ADK version 2.11.0 is now available!Upgrade to version 2.11.0 to use custom agent commands, schedule agentic workflows and agents, mask sensitive data, configure callbacks, and benefit from updated LangChain/LangGraph ecosystem.

⬆️ Upgrade now

To upgrade to version 2.11.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.11.0

🚀 New features

Schedule agentic workflows and agents

Schedule agentic workflows and agents to run at specific times or intervals. For more information, see:

Configure callbacks for agentic workflows

Set up callbacks to receive notifications about workflow execution events. For more information, see Callback.

Conversation compaction for agents

Compress agent conversations to prevent overflow and optimize memory usage. For more information, see Conversation compaction settings.

Mask sensitive text in agentic workflows

Protect sensitive information by masking text in agentic workflows. For more information, see Masking sensitive data.

Map connections during agent import

Map connections while importing custom agents from ZIP files, streamlining the import process. For more information, see Associating connections to Custom agents.

Flux model support for Deepgram

Enable the Flux model for the Deepgram provider in voice configurations. For more information, see Managing voice configuration.

Custom agent command

Previously released in public preview, custom agent commands are now available. Import agents using agent files, create agents directly from the CLI, and configure manual connections for custom agents. For more information, see:

🔧 Enhancements

Updated LangChain/LangGraph ecosystem: The LangChain and LangGraph ecosystem updated to their latest major versions:

Show Updated versions

langchain to version 1.2.17
langchain-core to version 1.3.3
langchain-openai to version 1.1.14
langchain-text-splitters to version 1.1.2
langchain-community to version 0.4.1
langchain-mistralai to version 1.1.4
langchain-ibm to version 1.0.9
llama-index-embeddings-langchain to version 0.5.0
langgraph to version 1.1.10
langgraph-checkpoint to version 4.0.3
langgraph-checkpoint-postgres to version 3.0.5
langchain-classic (new library) to version 1.0.7

2.10.x

2026-05-20

The watsonx Orchestrate ADK version 2.10.0 is now available!Upgrade to version 2.10.0 to create dynamic schemas for knowledge bases, use Python toolkits in agentic workflows, and benefit from enhanced workspace messaging.

⬆️ Upgrade now

To upgrade to version 2.10.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.10.0

🚀 New features

Dynamic input and output schemas for knowledge bases

Create dynamic input and output schemas for your knowledge bases. For more information, see Configuring dynamic input and output for external knowledge bases.

🔧 Enhancements

Python toolkits in agentic workflows: You can now use Python toolkits in agentic workflows just as you use any other toolkits.
Enhanced workspace messaging: Improved copy messages for unhelpful assistant responses and external agent workspaces.

2.9.x

2026-04-30

The watsonx Orchestrate ADK version 2.9.0 is now available!Upgrade to version 2.9.0 to configure multi‑user activities, enable direct OAuth access flows, configure checkpointing for LangGraph agents, and extend model support and safety controls.

⬆️ Upgrade now

To upgrade to version 2.9.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.9.0

🚀 New features

Multi‑user activities

Configure multi‑user activities by assigning a user activity node to a single user or multiple users registered in the tenant. For more information, see Configuring multi-user activities.

Import external agents from a URL

Import external agents by using a URL that hosts an agent card through the discovery command. For more information, see Import external agents from a URL.

OAuth direct access flow

Use an OAuth direct access flow connection to configure direct access for a team member in the draft environment. For more information, see Oauth auth direct access flow.

Checkpointer configuration

Enable state persistence for external agents by configuring checkpointers in the agent YAML file. For more information, see Configuring checkpointers.

🔧 Enhancements

OpenAI OAuth model support: Added support for OpenAI models using OAuth client credentials.
Model denylist support: Added support for restricting which LLMs can be selected by using a model denylist.
Safe update confirmation: Added the --safe flag for agents, knowledge bases, and tools commands to prompt for confirmation before updating existing resources.

2.8.x

2026-04-14

The watsonx Orchestrate ADK version 2.8.0 is now available!Upgrade to version 2.8.0 to create Python toolkits, configure error handling in agentic workflows, use updated voice configurations, define custom connection properties, and benefit from enhanced security and interoperability improvements.

⬆️ Upgrade now

To upgrade to version 2.8.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.8.0

🚀 New features

Python toolkits

Create toolkits that bundle multiple Python tools and import them into watsonx Orchestrate. For more information, see Importing Python toolkits.

Error handling in agentic workflows

Configure error handling directly in agentic workflow flows. This allows workflows to respond more predictably when errors occur. For more information, see Handling errors.

Upgraded voice configurations

Use the updated voice configurations. For more information, see Managing voice configuration.

Custom properties in connections

Create custom properties in connections to extend connection configuration. For more information, see Creating a form tool.

Form tools

Display watsonx Orchestrate native form widgets from tools. For more information, see Creating a form tool.

🔧 Enhancements

OAuth client credentials authentication: Added support for OAuth Client Credentials authentication for virtual models through the AI Gateway.
Improved file transfer security: File upload and download now uses authenticated access instead of pre‑signed URLs.
Flow builder compatibility: Added support for opening flows created with the ADK directly in the flow builder.
Python package validation: Added validation for Python packages defined in requirements.txt against the Python package allowlist.

2.7.x

2026-03-27

The watsonx Orchestrate ADK version 2.7.0 is now available!Upgrade to version 2.7.0 to manage Workspaces through the CLI, develop agents using Skill specifications, use updated OpenSearch schemas, connect to Genesys platforms, enhance agentic workflows, view custom code tool logs, and import agents from ZIP files.

⬆️ Upgrade now

To upgrade to version 2.7.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.7.0

🚀 New features

Workspaces

Use the new Workspaces commands to manage Workspaces with the watsonx Orchestrate ADK CLI. For more information, see Workspaces.

Agent development with Skills specifications (Public Preview)

Use the MCP servers and agent‑agnostic Skill specifications provided by IBM watsonx Orchestrate to help coding agents build solutions more reliably while reducing large context overhead. For more information, see Agent development with Skills specifications.

Updated schema for OpenSearch

Use the updated schemas for OpenSearch. For more information, see OpenSearch.

Genesys Cloud platform connections

Use the orchestrate customer‑care commands to configure connections for your Genesys Cloud platforms. For more information, see Managing connections to Customer Care platforms

Agentic workflow updates

Use the updated user activity node for agentic workflows. Configure dynamic forms and use date and time fields in your user activity node. For more information, see:

Logs for custom code tools

View logs generated by your custom code tools in watsonx Orchestrate Developer Edition. For more information, see Logging behavior for Python tools in watsonx Orchestrate.

Import agents from ZIP files

Import agents from ZIP files exported by the watsonx Orchestrate ADK CLI. For more information, see Bulk import from ZIP.

🐛 Bug fixes

Voice-configs import failure: Fixed an issue where importing voice configurations failed in on‑premises environments.
Display name mapping: Fixed an issue where display names were not mapped correctly into the flow model for some node types.

2.6.x

2026-03-13

The watsonx Orchestrate ADK version 2.6.0 is now available!Upgrade to version 2.6.0 to use the new unified connection model, pass metadata to MCP tools, configure external service credentials, upload multiple files through Python tools, and search traces using relative time windows.

⬆️ Upgrade now

To upgrade to version 2.6.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.6.0

🚀 New features

Credential configuration for services on watsonx Orchestrate Developer Edition

Configure custom service credentials for watsonx Orchestrate Developer Edition. For more information, see Configure services credentials for watsonx Orchestrate Developer Edition in the .env file and Initializing watsonx Orchestrate Developer Edition server.

Updates to the `orchestrate chat ask` command

Use the expanded capabilities of the orchestrate chat ask command for richer interaction. For more information, see Chatting with an agent in interactive mode through the CLI.

Multiple file upload for Python tools

Create Python tools that upload multiple files. For more information, see Creating tools that accept files.

Relative time window for trace search

Use the --last flag with the orchestrate observability traces search command to search traces from the last minutes, hours, or days. For more information, see Searching traces.

Contextual metadata for MCP toolkits

Pass contextual metadata to tools that come from MCP toolkits. For more information, see Tracing, tenant and agent context.

Unified connection experience for knowledge bases

Use the updated connection experience for knowledge bases. Connections now support optional categorization, allowing you to define the connection type and the application that uses it. For more information, see Adding and configuring connections.

User activity node updates

Use the updated field types in the form() object for the user activity node. For more information, see Forms.

🐛 Bug fixes

Corrected instructions text wrapping: Fixed the wrapping issue for the orchestrate agents ai-builder prompt-tune command.
Updated CPD instance validation: CPD instances no longer need to start with https://cpd.

2.5.x

2026-02-27

The watsonx Orchestrate ADK version 2.5.0 is now available!Upgrade to version 2.5.0 to search traces, manage Langfuse configuration, create citation‑enabled Python tools, and benefit from improved tool listing behavior.

⬆️ Upgrade now

To upgrade to version 2.5.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.5.0

🚀 New features

Traces with ADK

Search and export traces through the ADK CLI or Python scripts. For more information, see Traces.

Remove configuration settings for Langfuse

Use the new command to delete Langfuse configuration settings from your environment. For more information, see Removing configuration settings.

Citations for Python tools

Create Python tools that trigger citations. For more information, see Creating tools that can trigger citations.

Connection types for local MCP servers

Use different connection types to authenticate with your local MCP servers. For more information, see Supported connection types for local MCP servers.

🔧 Enhancements

Improved tool listing: The orchestrate tools list command now shows both the name and display_name when they differ, making it easier to identify tools in the output.

2.4.x

2026-02-13

The watsonx Orchestrate ADK version 2.4.0 is now available!Upgrade to version 2.4.0 to import custom agents, define your own certificate bundles, and use new public preview Customer Care styles that expand how you build and run agents.

⬆️ Upgrade now

To upgrade to version 2.4.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.4.0

🚀 New features

Custom agents

Use the --experimental-package_root and --experimental-config-file flags to import your custom LangGraph agents into watsonx Orchestrate through the ADK. For more information, see:

Custom certificate bundle path

Use the new --cert-bundle-path flag with the orchestrate server start command to inject a custom certificate bundle through Docker volumes into the required microservices. For more information, see Initializing watsonx Orchestrate Developer Edition server.

(Public preview) Customer Care style support

Use the new experimental_customer_care style. For more information, see:

(Public preview) Customer Care style
Getting Started with Customer Care

Note:
This public preview has officially ended. The experimental Customer Care style is no longer supported.

🔧 Enhancements

Localized welcome experience: The welcome message and quick‑start prompts automatically translate to the language you choose. Translation quality depends on the LLM.
Improved KB import and update messages: Knowledge base import and update operations now show progress messages until completion.
Bedrock gpt‑oss model availability: The bedrock/openai.gpt-oss-120b-1:0 model is now available as one of the models for your agents.

🐛 Bug fixes

Resolved agent response failure: Fixed an issue where an agent did not respond when running a flow tool through orchestrate chat ask.

📘 Guides

Migration guidance from Llama to GPT-OSS-120b

A migration guide is now available to help you switch from Llama to the GPT-OSS-120b model. For more information, see Migrating to GPT-OSS-120B.

2.3.x

2026-01-30

The watsonx Orchestrate ADK version 2.3.0 is now available!You can now upgrade to version 2.3.0 to access new ways of interacting with your agents, export your models, and control context variables with Python tools.

⬆️ Upgrade now

To upgrade to version 2.3.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.3.0

🚀 New features

Chatting with agents through CLI

Chat with agents in your active environment directly from the ADK CLI by using the orchestrate chat ask command. For more information, see Chatting with an agent in interactive mode through the CLI.

Export models and model policies

Use the ADK CLI to export models and model policies from watsonx Orchestrate. For more information, see Exporting custom LLM and Exporting model policy.

Modifying context variables with Python tools

Modify context variables inside Python tools, including values such as the user identity. For more information, see Using Context Variables.

🔧 Enhancements

Improved invalid docstring warnings: You now receive clearer and more accurate messages when a Python tool import fails because of incorrect docstrings.

🐛 Bug fixes

OpenAPI import problem: Fixed an issue where OpenAPI specs containing circular jsonref objects could not be imported into the ADK.
Inaccurate error reporting: Fixed an issue where certain failures incorrectly displayed str object has no attribute .decode instead of the actual error message.

2.2.x

2026-01-15

The watsonx Orchestrate ADK version 2.2.0 is now available!This release expands agent deployment options, enhances extensibility, and simplifies tool and connection configuration. You can now deploy agents across new digital channels, create custom agents, work with dynamic schemas, and take advantage of major MCP and tooling improvements.

⬆️ Upgrade now

To upgrade to version 2.2.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.2.0

🚀 New features

Deploy agents on digital channels

Deploy your agents directly to Microsoft Teams and Facebook Messenger channels. This allows you to reach users across multiple communication platforms. For more information, see Establishing Channels.

Dynamic input and output schemas in Python tools

Configure custom schemas for Python tools using the new enable_dynamic_schema field. For more information, see Dynamic input and output schemas.

Auto-discover for Python tools

Use the new --auto-discover flag with orchestrate tools import to automatically discover and import all Python functions in the module specified by the -f flag. For more information, see Auto-discover.

Enhanced Langflow commands

Use the Langflow flow name to import Langflow flows directly into watsonx Orchestrate. When you provide the Langflow flow name, the ADK retrieves the latest JSON with credentials, so you do not need to export the flow before adding it to watsonx Orchestrate. For more information, see Importing langflow flow using langflow flow name.

🔧 Enhancements

LangChain core upgrade: Updated langchain-core to version ~1.2.4.
Langflow Builder UI: Updated to version 1.7.1.
Python tool parameter parsing: The ADK now parses input parameter descriptions for Python tools directly from docstrings.
Genesys audio connector credentials: Automatic generation of API key and secret is now supported, matching UI behavior. You can still provide credentials manually or leave them blank to auto-generate.

🐛 Bug fixes

Webchat embed deployment: Fixed an issue where the webchat embed command failed for deployed agents.

2.1.x

2025-12-11

The watsonx Orchestrate ADK version 2.1.0 is now available!

⬆️ Upgrade now

To upgrade to version 2.1.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.1.0

🚀 New features

Support for new phone and chat channels

ADK now supports more channels to connect to:

Twilio WhatsApp
Slack
Twilio SMS
Genesys Bot Connector

For phone channels, the only supported provider for now is Genesys Audio Connector.ADK Voice configurations now support the following providers:

Deepgram Speech-To-Text and Text-To-Speech
ElevenLabs Text-To-Speech

To learn more about channels, see Establishing channels. To learn about phone support, see Adding phone configurations.

Support for plug-ins

Plug-ins inspect and modify the input or output of an agent run. A plug-in is a tool that is automatically started either before the agent begins generating a response (pre-invoke) or after the agent completes its response (post-invoke).To learn more about plug-ins, see Plug-ins.

watsonx Orchestrate copilot is now watsonx Orchestrate AI Builder

watsonx Orchestrate copilot has been renamed to watsonx Orchestrate AI Builder. The new VS Code extension can now be found as watsonx Orchestrate ADK Extension in the VS Code Extensions store.The extension now also includes access to an embedded web chat. You can learn more about it on watsonx Orchestrate AI Agent Builder and Orchestrate ADK Extension.

Evaluation framework: Langfuse support

The evaluation framework now supports evaluation with Langfuse. You can learn more about it in Agentops evaluation.

Document processing custom output format

The “docproc” (text extraction) node now includes an output_format parameter that gives you explicit control over how document processing results are returned. When set to docref, docproc returns a URL reference to the stored extraction results. This is the current and default behaviour. When set to object, docproc returns the actual JSON object.For more information, see Document processing with output format.

🐛 Bug fixes

Channels: Fixed an issue where channel names were not saved after adding them.
Lima VM: Fixed issues related to the installation of the Lima VM when installing the watsonx Orchestrate Developer Edition.
Stop server: The command orchestrate server stop now correctly stops the virtual machine that runs the watsonx Orchestrate Developer Edition server. You can opt to keep the VM running with the --keep-vm flag.
Flows: Uploaded files now support non-ASCII characters in the file name.

2.0.x

2025-11-25

The watsonx Orchestrate ADK version 2.0.0 is now available!

⬆️ Upgrade now

To upgrade to version 2.0.0, run:

BASH

pip install --upgrade ibm-watsonx-orchestrate==2.0.0

🚀 New features

Installing watsonx Orchestrate Developer Edition

The installation process for watsonx Orchestrate Developer Edition is updated. You no longer need Docker installed; the installation configures everything automatically. You still need the .env file. New commands are available to manage your watsonx Orchestrate Developer Edition. For more information, see watsonx Orchestrate Developer Edition.

Channels

Channels allow watsonx Orchestrate agents to connect with users across multiple platforms and communication tools. A new set of channels commands has been added to the ADK. For more information, see Channels.

Forms support for user activity node

Previously released in public preview, forms support for user activity nodes is now generally available. You can configure forms in a user activity node. For more information, see Forms.

Data mapping

Large data in flows is automatically summarized to improve auto-mapping reliability. You can customize the summarization by providing instructions specific to your use case. For more information, see Data mapping

Breaking change: Import MCP toolkits

The former orchestrate toolkits import command has been renamed to orchestrate toolkits add. Additionally, a new orchestrate toolkits import command has been added, which works on files in a way that is the inverse of the orchestrate toolkits export command. You can learn more in Importing local MCP toolkits and Importing remote MCP toolkits.

Export MCP toolkits

You can now use the ADK CLI to export MCP toolkits. For more information, see Exporting remote MCP toolkits using ADK CLI.

AI gateway models in Document Processing

You can now use AI gateway models for KVP extraction in Document Processing nodes. For more information, see Document text extractor node.Important update for existing users
If you previously used this feature, you must update your model name to include the provider prefix. For example:

Before: mistralai/mistral-small-3-1-24b-instruct-2503 (deployed on watsonx.ai)
Now: watsonx/mistralai/mistral-small-3-1-24b-instruct-2503

Groq GPT-OSS Models

watsonx Orchestrate now supports Groq GPT-OSS models. For more information, see Large Language Models.

Note:
This model is a non-IBM product governed by a third-party license that may impose use restrictions and other obligations. By using this model you agree to the terms. Read the terms

🐛 Bug fixes

Deleting agents: Fixed an issue where deleting an agent also deleted the modular knowledge attached to it.
Importing complex agentic workflows: Fixed an issue where agentic workflows with complex schemas could be imported by ADK but not executed by watsonx Orchestrate.

​⬆️ Upgrade now

​🚀 New features

​Thread-aware agent node

​OAuth 2.0 JWT Bearer connections

​HTML and Markdown output in document text extractor

​--iam-url parameter for environment setup

​🔧 Enhancements

​🐛 Bug fixes

​⬆️ Upgrade now

​🚀 New features

​Controls management

​Multiple knowledge bases per agent

​Voice idle handler new fields

​Observability traces for external agents

​🔧 Enhancements

​🐛 Bug fixes

​⚠️ Known limitations

​Excel file support in Document Extractor (Developer Edition)

​⬆️ Upgrade now

​🚀 New features

​Observability for external agents

​Document processing language support

​Google TTS voice configuration

​Deepgram TTS volume normalization

​Extended flow lifecycle events

​Knowledge base credential validation

​Red Hat AI model support

​Microsoft Copilot Studio agent provider

​Document classifier class limit

​Langflow updated to v1.10.0

​🐛 Bug fixes

​⬆️ Upgrade now

​🚀 New features

​Traces update

​Suppress agent summarization

​Page range support for document field and text extractor nodes

​Extended event support and payload schema for agentic workflow callbacks

​Agent skills

​Premier models

​Deprecated agent styles

​🔧 Enhancements

​🐛 Bug fixes

​⬆️ Upgrade now

​🚀 New features

​Multi-language support for agentic workflows

​Enhanced decision tables for agentic workflows

​Parallel branch support in agentic workflows

​Anti-pattern documentation

​🔧 Enhancements

​⬆️ Upgrade now

​🚀 New features

​Schedule agentic workflows and agents

​Configure callbacks for agentic workflows

​Conversation compaction for agents

​Mask sensitive text in agentic workflows

​Map connections during agent import

​Flux model support for Deepgram

​Custom agent command

​🔧 Enhancements

​⬆️ Upgrade now

​🚀 New features

​Dynamic input and output schemas for knowledge bases

​🔧 Enhancements

​⬆️ Upgrade now

​🚀 New features

​Multi‑user activities

​Import external agents from a URL

​OAuth direct access flow

​Checkpointer configuration

​🔧 Enhancements

​⬆️ Upgrade now

​🚀 New features

​Python toolkits

​Error handling in agentic workflows

​Upgraded voice configurations

​Custom properties in connections

​Form tools

​🔧 Enhancements

​⬆️ Upgrade now

​🚀 New features

⬆️ Upgrade now

🚀 New features

Thread-aware agent node

OAuth 2.0 JWT Bearer connections

HTML and Markdown output in document text extractor

`--iam-url` parameter for environment setup

🔧 Enhancements

🐛 Bug fixes

⬆️ Upgrade now

🚀 New features

Controls management

Multiple knowledge bases per agent

Voice idle handler new fields

Observability traces for external agents

🔧 Enhancements

🐛 Bug fixes

⚠️ Known limitations

Excel file support in Document Extractor (Developer Edition)

⬆️ Upgrade now

🚀 New features

Observability for external agents

Document processing language support

Google TTS voice configuration

Deepgram TTS volume normalization

Extended flow lifecycle events

Knowledge base credential validation

Red Hat AI model support

Microsoft Copilot Studio agent provider

Document classifier class limit

Langflow updated to v1.10.0

🐛 Bug fixes

⬆️ Upgrade now

🚀 New features

Traces update

Suppress agent summarization

Page range support for document field and text extractor nodes

Extended event support and payload schema for agentic workflow callbacks

Agent skills

Premier models

Deprecated agent styles

🔧 Enhancements

🐛 Bug fixes

⬆️ Upgrade now

🚀 New features

Multi-language support for agentic workflows

Enhanced decision tables for agentic workflows

Parallel branch support in agentic workflows

Anti-pattern documentation

🔧 Enhancements

⬆️ Upgrade now

🚀 New features

Schedule agentic workflows and agents

Configure callbacks for agentic workflows

Conversation compaction for agents

Mask sensitive text in agentic workflows

Map connections during agent import

Flux model support for Deepgram

Custom agent command

🔧 Enhancements

⬆️ Upgrade now

🚀 New features

Dynamic input and output schemas for knowledge bases

🔧 Enhancements

⬆️ Upgrade now

🚀 New features

Multi‑user activities

Import external agents from a URL

OAuth direct access flow

Checkpointer configuration

🔧 Enhancements

⬆️ Upgrade now

🚀 New features

Python toolkits

Error handling in agentic workflows

Upgraded voice configurations

Custom properties in connections

Form tools

🔧 Enhancements

⬆️ Upgrade now

🚀 New features