Skip to main content
The watsonx Orchestrate ADK introduces environments (env), which represent instances of watsonx Orchestrate you can access. Environments can be:
  • Local: Running on your laptop using the Developer Edition of watsonx Orchestrate.
  • Remote: Hosted on IBM Cloud, AWS, or on-premises using Cloud Pak for Data.
When you activate an environment, all commands, except orchestrate server and orchestrate chat, target that environment. This includes importing, listing, and removing agents, tools, and connections.

​
Environment commands

​
Adding an environment

Use the orchestrate env add command to add a remote environment to your local CLI. To learn where to find your service instance url and api key see Getting credentials for your environments.
BASH
Note:You can set any name you prefer for the environment.
HIPAA-regulated clusters and MCSP V2 instances require --iam-url.When registering an environment on a HIPAA-regulated cluster or an MCSP V2 instance, you must supply the --iam-url flag with the IAM token endpoint for that cluster. Without it, every subsequent orchestrate env activate call fails with an Error getting MCSP_V2 Token error.The value is a URL in the form https://<iam-host>, for example:
Example command:
BASH
For MCSP V2 and HIPAA clusters, see the MCSP V2 and HIPAA cluster example. For on-premises environments, you can ignore invalid SSL certificates, if your environment uses a self-signed certificate:
BASH

​
MCSP V2 and HIPAA cluster example

The following example shows how to register and activate a HIPAA-regulated or MCSP V2 environment.
BASH
​
string
A name you choose for this environment. Example: my-hipaa-env
​
string
Your watsonx Orchestrate service instance URL. Example: https://api.example.watson-orchestrate.ibm.com
​
string
IAM token endpoint for the cluster. Example: https://iam.platform.saas.ibm.com
​
string
Your watsonx Orchestrate API key.

​
Activating an environment

Use the orchestrate env activate command to authenticate against a given environment and target all commands other than orchestrate server and orchestrate chat to that environment.
Note: Authentication against a remote environment expires every two hours. After expiration, you need to run orchestrate env activate again. This behavior does not exist in the local environment.
To interactively activate an environment:
BASH
To non-interactively log in for scripting, use the following:
BASH
For on-premises environments:
BASH
You can also use an api-key in the on-premises environment:
BASH

​
Listing all environments

Use the orchestrate env list command to list all environments currently available to your CLI. By default, you have one known as local. Your local environment refers to the watsonx Orchestrate Development Edition server. Others can be added by using the orchestrate env add command. The currently active environment will be indicated by an indicator saying (active) at the end of the line.
BASH

​
Removing an environment

Use the orchestrate env remove command to remove an environment from your environment list.
BASH

​
Important configuration files

The watsonx Orchestrate CLI maintains two configuration files which are manipulated by the above env commands.
  • The first is ~/.config/orchestrate/config.yaml. This configuration file records each of your environments as well as which environment is currently active.
  • The second is ~/.cache/orchestrate/credentials.yaml. This file contains the JWT token from your last env activation used to authenticate with your environment.

​
Post-installation verification for on-premises deployments

After you add and activate an on-premises environment, complete the following verification step before creating agents.
Configure a default LLM model before creating agentsOn a fresh on-premises (CPD) installation, no default LLM model is configured. Attempting to create an agent before a default model is imported results in a “Creating the agent failed. Please try again.” error with no diagnostic information.
  1. Create a model YAML file that includes the default tag:
    default-model.yaml
  2. Import the model while your on-premises environment is active:
This is a one-time step. After a default model is registered, agents can be created normally. For more detail, including how to update an existing model to add the default tag, see Managing virtual models.