Managing agent and tool versions

Edit online

When you work with agents and tools in watsonx Orchestrate, it is important to understand how versions functions across both. Version history enables you to review prior releases, compare changes, select specific versions for use in builders, and create new objects from earlier configurations. Managing versions effectively ensures consistency, reliability, and control over how agents and tools operate within your environment.

How version history works

Across all agents and tools, watsonx Orchestrate provides consistent version management experience:

  • You can view up to five of the most recent versions, when available.

  • The latest version displays a Latest badge (for agents), and the version you select displays a Viewing badge.

  • When you switch versions, you remain in view‑only mode unless you explicitly select a version for a builder action.

  • The displayed release date updates based on the version you select.

  • All versions appear in a collapsed state, and you can expand or collapse all entries.

  • If the agent has only one version, you see only that version.

  • You can view version history even before you purchase agents or tools.

Viewing and selecting versions

You may want to review the available versions to understand their behavior, verify change history, compare updates, or confirm whether a specific version meets your requirements.

To view and select a specific version:

  1. From the main menu, select Discover to view the catalog.

  2. Select the agent or tool that you want to review.

  3. When you open an agent or a tool from the catalog, the page displays the latest version by default.

  4. On the right‑hand panel, select Version > View recent versions.

  5. From the Recent versions panel, locate the version you want to work with.

  6. Browse the versions and expand any entry to view its Summary and Change Logs.

  7. Click Select version that you want to work with.

  8. The page reloads with the chosen version.

The Viewing badge and displayed release date update based on the version you select.

Navigating between versions

Version-aware navigation ensures that you maintain context as you move between agents and tools.

  • Viewing older versions: When you switch to an older version, the page updates to reflect that version's content.

  • Opening tools from older agent versions: When you navigate to a tool referenced by an older agent version, a banner indicates that the tool belongs to an older agent version.

  • Return path: When you use Back or breadcrumbs, you return to the exact version you accessed earlier.

  • Persistence: When you leave an agent or tool page and return later, the system loads the latest version, not the last version you viewed.

Versioning behavior for catalog publishing

Agent versions are created, incremented, and managed during publishing and republishing using semantic versioning (MAJOR.MINOR.PATCH), where each segment communicates the scope and impact of a change:

  • Major: Breaking or incompatible changes
  • Minor: Backward-compatible enhancements
  • Patch: Backward-compatible fixes or minor adjustments

Version increment rules

  • Patch update: Increments patch by 1 (e.g., 1.2.3 → 1.2.4) for non-breaking fixes, refinements, or metadata-only changes
  • Minor update: Increments minor by 1 and resets patch to 0 (e.g., 1.2.3 → 1.3.0) for backward-compatible enhancements
  • Major update: Increments major by 1 and resets minor and patch to 0 (e.g., 1.2.3 → 2.0.0) for breaking changes or incompatible behavior

Decision table for selecting version type

Use the table below to determine the appropriate version increment during publishing or republishing.

Change scenario Breaks existing behavior Adds new functionality Metadata-only change Version to use
Bug fix or small internal improvement No No No Patch
Metadata update (name, description, category, icon) No No Yes Patch
New backward-compatible capability No Yes No Minor
Enhancement that changes behavior but remains compatible No Yes No Minor
Change that breaks compatibility or requires updates Yes Yes/No No Major
Removal or redesign of existing functionality Yes Yes/No No Major

Versioning on first publish

When an agent is published for the first time:

  • The orchestrator agent is assigned version 1.0.0
  • All dependent collaborator agents and tools are also assigned version 1.0.0

This establishes a consistent baseline for future updates.

Republishing and versioning behavior

Republishing creates a new version while retaining existing ones. Metadata updates (name, description, category, icon) are allowed and result in a new version. Republishing might be restricted if unsupported artifacts are included.

Version selection during republishing

During republishing, the administrator selects major, minor, or patch based on the decision table above, and the resulting version number is displayed before publishing.