Skip to main content

​
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:

​
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:
FlagDescription
--name / -nThe name of the agent you want to create.
--kind / -kThe kind of agent you wish to create. For native agents, the value should be native.
--descriptionThe description of the agent.
--llmThe 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.
--styleThe style of agent you want to create. Either default, react, or planner. To learn more about agent styles, see Agent styles.
--collaboratorsA 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-idThe application connection name used by the native agent.
--toolsA list of tools that the agent should be able to use. Multiple tools can be specified (e.g., --tools tool_1 --tools tool_2).
--outputAllows 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

​
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 an act of revering an agent from it’s current live state to the previous live state.
BASH
orchestrate agents undeploy --name agent_name