Importing and deploying agents - IBM watsonx Orchestrate ADK

Importing Agents

Importing an agent involves transferring it from your local system into your active environment, where it enters a draft (undeployed) state. There are two supported methods for importing agents:

Using an agent configuration file: Upload a pre-defined configuration that describes the agent’s components and behavior.
Using the ADK CLI: Create and register the agent directly via the Agent Development Kit (ADK) command-line interface.

Importing agents using an agent file

Use the orchestrate agents import command to import agents into the watsonx Orchestrate platform from a YAML, JSON, or Python file. You can import either natively built agents, external agents connected from other systemsm, or even custom agents.

Native and External Agents
Custom agents

To specify the agent file path, use the --file or -f flag:

BASH

orchestrate agents import -f <path to .yaml/.json/.py file>

Show command flags

--file / -f

string

Path to the agent file.

--app-id

string

The application connection name used by the agent.

--safe

Use --safe to add a confirmation step before updating or importing an agent that already exists.

Before running this command, make sure you have a valid agent configuration file. This file defines the parameters that describe the agent’s behavior and structure for watsonx Orchestrate. For details on how to author these configurations, see Authoring agents.

To specify the agent file path, use the flags:

BASH

orchestrate agents import --package-root <path to agent package root> --config-file <path to agent configuration file>

Show command flags

--package-root

string

(Custom agents) Path to the directory containing custom agent code. The directory will be automatically zipped and uploaded.

--config-file

string

(Custom agents) Path to a config.yaml file to include in the custom agent package. Only used with —package-root.

Note:Starting from version 2.11.0, when you declare connections in your agent.yaml file, the system automatically maps them to your agent during import. For information, see Associating connections to Custom agents.

Bulk import from ZIP

Import agents along with all their dependencies using a single ZIP file. You can import an agent and all its dependencies with the following command:

BASH

orchestrate agents import -f my_agent.zip

The structure of the imported ZIP file matches the structure produced by the agent export command:

BASH

orchestrate agents export -k native -n my_agent -o my_agent.zip

During the import process, tools require connections to be manually selected.

Creating agents directly from the CLI

The orchestrate agents create command can be used to quickly create and import an agent into the watsonx Orchestrate platform without first having a file to import.

Native Agent
External Agent
watsonx.ai External Agent
Custom agents

BASH

orchestrate agents create \
--name agent_name \
--kind native \
--description "Sample agent description" \
--llm watsonx/ibm/granite-3-8b-instruct \
--style default \
--collaborators agent_1
--collaborators agent_2
--tools tool_1
--output "agent_name.agent.yaml"

Show command flags

--name / -n

string

The name of the agent you want to create.

--kind / -k

string

The kind of agent you wish to create. For native agents, the value should be native.

--description

string

The description of the agent.

--llm

string

The large language model the agent will use, in the format of provider/developer/model_id, for example watsonx/ibm/granite-3-8b-instruct, or watsonx/meta-llama/llama-3-3-70b-instruct, where watsonx/ refers to the models supported by watsonx Orchestrate.

--style

string

values: default, react, react_intrinsic

The style of agent you want to create. Either default, react, or react_intrinsic. To learn more about agent styles, see Agent styles.

--collaborators

string

A list of agents that the agent should be able to call out to. Multiple collaborators can be specified (e.g., --collaborators agent_1 --collaborators agent_2).

--app-id

string

The application connection name used by the native agent.

--tools

string

A list of tools that the agent should be able to use. Multiple tools can be specified (e.g., --tools tool_1 --tools tool_2).

--output

string

Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

Allows you to call out to an external agent that is hosted on a different platform, such as Salesforce. For more information, see External Agent.

BASH

orchestrate agents create \
--name news_agent \
--title "News Agent" \
--description "Sample agent description" \
--api "http://some_url.com" \
--kind external \
--tags "test,other" \
--chat-params '{"stream": true}' \
--config '{"hidden": false, "enable_cot": false}' \
--nickname "news_agent" \
--app-id "my-basic-app"

Show command flags

--name / -n

string

The name of the agent you want to create.

--kind / -k

string

The kind of agent you wish to create. For external agents, the value should be external.

--title / -t

string

The title of the agent you wish to create.

--description

string

The description of the agent.

--api / -a

string

The external API URL your agent use.

--tags

string

The list of tags for the agent. Format: --tags tag1 --tags tag2 .... Only needed for external and assistant agents.

--chat-params

string

The chat parameters in JSON format (e.g., {"stream": true}). Only needed for external and assistant agents.

--config

string

The agent configuration in JSON format (e.g., {"hidden": false, "enable_cot": false}).

--nickname

string

The agent’s nickname.

--app-id

string

The application connection name used by the external agent.

--output

string

Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

To call out to agents on the watsonx.ai platform, set the provider to wx.ai.

BASH

orchestrate agents create \
    --name science_agent \
    --title "Science Agent" \
    --description "This external agent answers questions about Space" \
    --api "http://some_url.com" \
    --auth-config '{"token": "sometoken"}' \
    --auth-scheme 'API_KEY' \
    --kind external \
    --tags "wx.ai" \
    --chat-params '{"stream": true}' \
    --config '{"hidden": false, "enable_cot": false}' \
    --nickname "Science Agent" \
    --provider "wx.ai"
    --output "science_agent.agent.yaml"

Show command flags

--name / -n

string

The name of the agent you want to create.

--kind / -k

string

The kind of agent you wish to create. For external agents, the value should be external.

--title / -t

string

The title of the agent you wish to create.

--description

string

The description of the agent.

--api / -a

string

The external API URL your agent will use.

--auth-config

string

The external API auth config in JSON format (e.g., {"token": "sometoken"}).

--auth-scheme

string

The external API auth scheme (e.g., API_KEY for WX.AI).

--tags

string

The list of tags for the agent. Format: --tags tag1 --tags tag2 .... Only needed for external and assistant agents.

--chat-params

string

The chat parameters in JSON format (e.g., {"stream": true}). Only needed for external and assistant agents.

--config

string

The agent configuration in JSON format (e.g., {"hidden": false, "enable_cot": false}).

--nickname

string

The agent’s nickname.

--app-id

string

The application connection name used by the watsonx.ai external agent.

--provider

string

The external agent provider. It will be wx.ai for WX.AI agents.

--output

string

Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

To create a custom agent, use the flags:

BASH

orchestrate agents create --style custom --package-root <path to agent package root> --config-file <path to agent configuration file>

Show command flags

--package-root

string

(Custom agents) Path to the directory containing custom agent code. The directory will be automatically zipped and uploaded.

--config-file

string

(Custom agents) Path to a config.yaml file to include in the custom agent package. Only used with —package-root.

--style

string

values: default, react, planner, custom, experimental_customer_care, react_intrinsic

The style of agent you wish to create. For custom agents, use custom. [default: default]

Copy agents between workspaces

BASH

orchestrate agents copy --name <agent-name> --source <source-workspace-name> --destination <dest-workspace-name>

Show command flags

--name / -n

string

required

Name of the agent to copy.

--destination / -d

string

Destination workspace name where the agent will be copied to.

--source / -s

string

Source workspace name (defaults to active workspace if not specified).

Deploying Agents

Agents in watsonx Orchestrate operate in one of two states: draft or live.

A draft agent is actively being developed or modified by a builder. You can access draft agents from the Manage Agents page in the UI.
A live agent is available to end users through the Web chat UI on the Orchestrate landing page.

Note: In the watsonx Orchestrate Developer Edition, only the draft environment is available. This edition is designed for single-user, non-production use. As a result, the Web chat UI displays agents in their draft state instead of the live state. Attempting to run deploy commands in the Developer Edition will result in an error.

Deploying an agent

Deploying an agent is the act of taking an agent from a draft state into a live state.

BASH

orchestrate agents deploy --name agent_name

Note: By default the deploy agent command timesout after 5 minutes of checking the agent status. If you need to increase this you can use the WXO_AGENT_DEPLOYMENT_TIMEOUT environment variable. Default value is 300.

Undeploying an agent

Undeploying an agent is the act of reverting an agent from its current live state to the previous live state.

BASH

orchestrate agents undeploy --name agent_name

​Importing Agents

​Importing agents using an agent file

​Bulk import from ZIP

​Creating agents directly from the CLI

​Copy agents between workspaces

​Deploying Agents

​Deploying an agent

​Undeploying an agent

Importing Agents

Importing agents using an agent file

Bulk import from ZIP

Creating agents directly from the CLI

Copy agents between workspaces

Deploying Agents

Deploying an agent

Undeploying an agent