Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt

Use this file to discover all available pages before exploring further.

Using the ADK in an air-gapped environment introduces additional challenges that you need to address:
  • The ADK Python package is hosted on PyPI, which is inaccessible in an air-gapped environment.
  • By default, watsonx Orchestrate pulls packages from PyPI when installing Python tools.
Python tool dependencies are installed server-side at deployment time, not during tool import. This means your internal registry must be accessible from watsonx Orchestrate when tools are deployed. For comprehensive information on dependency management, see Python dependency management.

​
Prerequisites

As a site administrator, you need:
  • Access to a jumpbox that connects to both the internet and your Cloud Pak for Data cluster
  • A locally hosted Python package registry accessible from your internal network (common PyPI registry providers include Artifactory and Sonatype Nexus)

​
Uploading the ADK to your local PyPI registry

1

Get the dependencies list

On your jumpbox, run the following commands to get the full list of dependencies and generate wheel files for each ADK dependency:
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a UV Virtual environment
uv venv adk --seed --python=3.12
source adk/bin/activate

pip install ibm-watsonx-orchestrate==<supported_version>
pip freeze > requirements.txt
mkdir dependencies
cd dependencies
pip wheel -r ../requirements.txt
2

Upload wheel files

Upload all generated wheel files from the dependencies directory to your local PyPI registry provider.

​
Configuring Python tool imports

To import Python tools successfully, configure watsonx Orchestrate to pull the ADK from your local registry. All Python tools must be imported with a requirements.txt file that contains at least the following: 
--index-url https://my-pypi-registry
ibm-watsonx-orchestrate==<supported_version>
# Optional: Add other dependencies
my-dependency==dependency-version
Important: Use --index-url (not --extra-index-url) to ensure packages are pulled only from your internal registry, preventing any fallback to public PyPI. This is critical for security compliance in air-gapped environments.
Any dependencies other than the ADK that you want to use in your tools must also be uploaded to your PyPI registry by the site administrator. Remember that dependencies are installed server-side when tools are deployed, so your registry must remain accessible from watsonx Orchestrate.

​
Best practices for air-gapped deployments

  1. Pin all dependency versions to ensure reproducible builds: 
    ibm-watsonx-orchestrate==2.4.0
requests==2.32.3
pydantic==2.8.2
  2. Use hash verification for maximum security: 
    pip-compile --generate-hashes requirements.in -o requirements.txt
  3. Lock your internal registry to prevent package changes between environments
For detailed guidance on enterprise dependency patterns, see Python dependency management.