Managing agents

Listing agents

Use the orchestrate agents list command to list all agents in your environment. You can filter by agent type and get detailed information using the available flags.

BASH

orchestrate agents list -v

Show command flags

--kind / -k · string

The kind of agent you wish to list. Valid options: native, external, assistant.

--verbose / -v · boolean

List full details of all agents in JSON format.

Exporting agents

Use the orchestrate agents export command to export an agent configuration from your active environment.

You can export the full agent configuration with all its dependencies (default), or only the agent configuration by including the --agent-only flag.

BASH

orchestrate agents export -n <agent-name> -k <agent-type> -o <output-path>.zip

Show command flags

--name / -n · string · required

The name of the agent you want to export.

--kind / -k · string · required

The type of the agent (native or external).

--output / -o · string · required

The path where the exported agent file will be saved. When using --agent-only this will be the yaml spec of the agent. When not using --agent-only this will be a zip file containing the agent, its collaborators, its knowledge bases and Python tools.

--agent-only · boolean

Exports only the agent configuration without its dependencies.

Note: Agentic workflow tools are only exported when you use a local environment with watsonx Orchestrate Developer Edition.

Updating agents

To update an agent, run the import command again using the same agent name as the agent you want to update.

BASH

orchestrate agents import -f <path to agent file that you want to update>

If you’re updating an agent to use a different LLM (such as migrating from Llama to GPT-OSS-120B), see the Migration guide for model-specific optimization instructions.

Removing agent

To remove an existing agent, run the following command:

BASH

orchestrate agents remove --name my-agent --kind native

Show command flags

--name / -n · string · required

Name of the agent you wish to remove.

--kind / -k · string · required

The kind of agent you wish to remove. Valid options: native, external, assistant.

Chatting with an agent in interactive mode through the CLI

To start a chat session with an agent, run the following command:

BASH

orchestrate chat ask --agent-name <agent_name>

To start a chat session and ask an initial question, run the following command:

BASH

orchestrate chat ask --agent-name <agent_name> "What is the weather?"

To start a chat session and view the agent’s reasoning trace, run the following command:

BASH

orchestrate chat ask --agent-name <agent_name> "What is the weather?" --include-reasoning

Additional CLI chat options

You can interact with agents directly from the CLI by using the orchestrate chat ask command.

To see all available flags and options, run:

BASH

orchestrate chat ask --help

Capturing execution logs for custom agents

For custom agents, you can capture and display execution logs by using the --capture-logs flag. It is useful for debugging and understanding agent behavior during execution.

BASH

orchestrate chat ask "what is python" \
  --agent-name SimpleWxAIAgent \
  -r \
  --capture-logs

Continuing an existing conversation by using a thread ID

To continue an existing conversation, use the --thread-id flag. It allows the agent to maintain conversational context across multiple requests.

BASH

orchestrate chat ask \
  --agent-name customer_care_agent \
  --thread-id <thread-id> \
  "give me more information on claim CLM1234567"

Running flow agents from the CLI

The CLI now supports flow agents. From a user perspective, you can run flow agents the same way as other agents.

BASH

orchestrate chat ask \
  --agent-name various_outputs_agent \
  "flow" \
  -r

Uploading and downloading files during chat

Agents that require file input or output now support file upload and download capabilities through the CLI.

When an agent requests a file upload or download, the CLI prompts you to provide the local directory path for the file to upload or the destination directory for downloaded files.

File prompts appear only when the agent workflow requires file interaction.