Importing and deploying agents

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

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.

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.

(Public Preview) Custom agents

Important:

• This feature is currently in public preview. Functionality and behavior may change in future updates.
• This feature works only with watsonx Orchestrate Developer Edition.

To specify the agent file path, use the experimental flags:

BASH

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

Show command flags

--experimental-package-root · string

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

--experimental-config-file · string

Path to a config.yaml file to include in the custom agent package.

Connections for custom agents do not carry over during import. To configure a connection for a custom agent, use the experimental-connect command. For details, see Using connections in 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

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, planner

The style of agent you want to create. Either default, react, or planner. 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.

External Agent

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.

watsonx.ai External Agent

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.

(Public Preview) Custom agents

Important:

• This feature is currently in public preview. Functionality and behavior may change in future updates.
• This feature works only with watsonx Orchestrate Developer Edition.

To specify the agent file path, use the experimental flags:

BASH

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

Show command flags

--experimental-package-root · string

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

--experimental-config-file · string

Path to a config.yaml file to include in the custom agent package.

--kind / -k · string

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

Connections for custom agents do not carry over during import. To configure a connection for a custom agent, use the experimental-connect command. For details, see Using connections in Custom agents.

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