> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing and deploying agents

## Importing Agents

Importing an agent involves transferring it from your local system into your [active environment](https://developer.watson-orchestrate.ibm.com/environment/initiate_environment.md), where it enters in a **draft (undeployed)** state.
There are two supported methods for importing agents:

* **[Using an agent configuration file](#importing-agents-using-an-agent-file)**: Upload a pre-defined configuration that describes the agent's components and behavior.
* **[Using the ADK CLI](#creating-agents-directly-from-the-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](https://developer.watson-orchestrate.ibm.com/_releases/1.15.0/agents/build_agent.md) or [external agents](https://developer.watson-orchestrate.ibm.com/_releases/1.15.0/agents/connect_agent.md) connected from other systems.

To specify the agent file path, use the `--file` or `-f` flag:

```bash BASH theme={null}
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](https://developer.watson-orchestrate.ibm.com/_releases/1.15.0/agents/build_agent.md).

### 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.

> [tab] Native 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](https://developer.watson-orchestrate.ibm.com/_releases/1.15.0/agents/build_agent.md#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 BASH [expandable] theme={null}
> 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
> ```

> [tab] 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](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/external_agent/examples).
>
> **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 BASH [expandable] theme={null}
> 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"
> ```

> [tab] watsonx.ai External Agent
>
> 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 BASH [expandable] theme={null}
> 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]
>
> **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 BASH theme={null}
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 BASH theme={null}
orchestrate agents undeploy --name agent_name
```
