Importing and deploying agents

Importing Agents

Importing an agent involves transferring it from your local system into your active environment, where it enters in 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 or external agents connected from other systems. To specify the agent file path, use the --file or -f flag:

BASH

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

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.

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

Flags:

Flag	Description
`--name` / `-n`	The name of the agent you want to create.
`--kind` / `-k`	The kind of agent you wish to create. For native agents, the value should be `native`.
`--description`	The description of the agent.
`--llm`	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`	The style of agent you want to create. Either `default`, `react`, or `planner`. To learn more about agent styles, see Agent styles.
`--collaborators`	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`	The application connection name used by the native agent.
`--tools`	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`	Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

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

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.Flags:

Flag	Description
`--name` / `-n`	The name of the agent you want to create.
`--kind` / `-k`	The kind of agent you wish to create. For external agents, the value should be `external`.
`--title` / `-t`	The title of the agent you wish to create.
`--description`	The description of the agent.
`--api` / `-a`	The external API URL your agent use.
`--tags`	The list of tags for the agent. Format: `--tags tag1 --tags tag2 ...`. Only needed for external and assistant agents.
`--chat-params`	The chat parameters in JSON format (e.g., `{"stream": true}`). Only needed for external and assistant agents.
`--config`	The agent configuration in JSON format (e.g., `{"hidden": false, "enable_cot": false}`).
`--nickname`	The agent’s nickname.
`--app-id`	The application connection name used by the external agent.
`--output`	Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

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"

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

Flag	Description
`--name` / `-n`	The name of the agent you want to create.
`--kind` / `-k`	The kind of agent you wish to create. For external agents, the value should be `external`.
`--title` / `-t`	The title of the agent you wish to create.
`--description`	The description of the agent.
`--api` / `-a`	The external API URL your agent will use.
`--auth-config`	The external API auth config in JSON format (e.g., `{"token": "sometoken"}`).
`--auth-scheme`	The external API auth scheme (e.g., API_KEY for WX.AI).
`--tags`	The list of tags for the agent. Format: `--tags tag1 --tags tag2 ...`. Only needed for external and assistant agents.
`--chat-params`	The chat parameters in JSON format (e.g., `{"stream": true}`). Only needed for external and assistant agents.
`--config`	The agent configuration in JSON format (e.g., `{"hidden": false, "enable_cot": false}`).
`—nickname	The agent’s nickname.
`--app-id`	The application connection name used by the watsonx.ai external agent.
`--provider`	The external agent provider. It will be `wx.ai` for WX.AI agents.
`--output`	Allows you to specify an output file to write the agent definition to (either .yaml or .json are supported) for future modification post import.

BASH

orchestrate agents create \
    --name science_agent \
    --title "Sciene 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

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 Webchat 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 Webchat 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

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

Importing Agents

Importing agents using an agent file

Creating agents directly from the CLI

Deploying Agents

Deploying an agent

Undeploying an agent