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
(Public Preview) 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.

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.

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.

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
(Public Preview) 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, 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.

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.

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.

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

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

Release Notes

Get Started

Build

Deploy

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate ADK MCP Server

Reference

Legal notices

Importing Agents

Importing agents using an agent file

Creating agents directly from the CLI

Deploying Agents

Deploying an agent

Undeploying an agent

Release Notes

Get Started

Build

Deploy

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate ADK MCP Server

Reference

Legal notices

​Importing Agents

​Importing agents using an agent file

​Creating agents directly from the CLI

​Deploying Agents

​Deploying an agent

​Undeploying an agent

Importing Agents

Importing agents using an agent file

Creating agents directly from the CLI

Deploying Agents

Deploying an agent

Undeploying an agent