> ## 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](/environment/initiate_environment), where it enters 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](./build_agent), [external agents](./connect_agent) connected from other systemsm, or even custom agents.

<Tabs>
  <Tab title="Native and External Agents">
    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>
    ```

    <Expandable title="command flags">
      <ResponseField name="--file / -f" type="string">
        Path to the agent file.
      </ResponseField>

      <ResponseField name="--app-id" type="string">
        The application connection name used by the agent.
      </ResponseField>

      <ResponseField name="--safe">
        Use `--safe` to add a confirmation step before updating or importing an agent that already exists.
      </ResponseField>
    </Expandable>

    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](./build_agent).
  </Tab>

  <Tab title="Custom agents">
    To specify the agent file path, use the flags:

    ```bash BASH theme={null}
    orchestrate agents import --package-root <path to agent package root> --config-file <path to agent configuration file>
    ```

    <Expandable title="command flags">
      <ResponseField name="--package-root" type="string">
        (Custom agents) Path to the directory containing custom agent code. The directory will be automatically zipped and uploaded.
      </ResponseField>

      <ResponseField name="--config-file" type="string">
        (Custom agents) Path to a config.yaml file to include in the custom agent package. Only used with --package-root.
      </ResponseField>
    </Expandable>

    <Note>
      **Note:**

      Starting from version 2.11.0, when you declare connections in your `agent.yaml` file, the system automatically maps them to your agent during import. For information, see [Associating connections to Custom agents](../connections/connections_for_custom_agents).
    </Note>
  </Tab>
</Tabs>

### Bulk import from ZIP

Import agents along with all their dependencies using a single ZIP file.

You can import an agent and all its dependencies with the following command:

```bash BASH theme={null}
orchestrate agents import -f my_agent.zip
```

The structure of the imported ZIP file matches the structure produced by the agent export command:

```bash BASH theme={null}
orchestrate agents export -k native -n my_agent -o my_agent.zip
```

During the import process, tools require connections to be manually selected.

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

<Tabs>
  <Tab title="Native Agent">
    ```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 react_core \
    --collaborators agent_1
    --collaborators agent_2
    --tools tool_1
    --output "agent_name.agent.yaml"
    ```

    <Expandable title="command flags">
      <ResponseField name="--name / -n" type="string">
        The name of the agent you want to create.
      </ResponseField>

      <ResponseField name="--kind / -k" type="string">
        The kind of agent you wish to create. For native agents, the value should be `native`.
      </ResponseField>

      <ResponseField name="--description" type="string">
        The description of the agent.
      </ResponseField>

      <ResponseField name="--llm" type="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.
      </ResponseField>

      <ResponseField name="--style" type="string" post={['values: default, react, react_core']}>
        The style of agent you want to create. Either `default`, `react`, or `react_core`. To learn more about agent styles, see Agent styles.
      </ResponseField>

      <ResponseField name="--collaborators" type="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`).
      </ResponseField>

      <ResponseField name="--app-id" type="string">
        The application connection name used by the native agent.
      </ResponseField>

      <ResponseField name="--tools" type="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`).
      </ResponseField>

      <ResponseField name="--output" type="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.
      </ResponseField>
    </Expandable>
  </Tab>

  <Tab title="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).

    ```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"
    ```

    <Expandable title="command flags">
      <ResponseField name="--name / -n" type="string">
        The name of the agent you want to create.
      </ResponseField>

      <ResponseField name="--kind / -k" type="string">
        The kind of agent you wish to create. For external agents, the value should be `external`.
      </ResponseField>

      <ResponseField name="--title / -t" type="string">
        The title of the agent you wish to create.
      </ResponseField>

      <ResponseField name="--description" type="string">
        The description of the agent.
      </ResponseField>

      <ResponseField name="--api / -a" type="string">
        The external API URL your agent use.
      </ResponseField>

      <ResponseField name="--tags" type="string">
        The list of tags for the agent. Format: `--tags tag1 --tags tag2 ...`. Only needed for external and assistant agents.
      </ResponseField>

      <ResponseField name="--chat-params" type="string">
        The chat parameters in JSON format (e.g., `{"stream": true}`). Only needed for external and assistant agents.
      </ResponseField>

      <ResponseField name="--config" type="string">
        The agent configuration in JSON format (e.g., `{"hidden": false, "enable_cot": false}`).
      </ResponseField>

      <ResponseField name="--nickname" type="string">
        The agent's nickname.
      </ResponseField>

      <ResponseField name="--app-id" type="string">
        The application connection name used by the external agent.
      </ResponseField>

      <ResponseField name="--output" type="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.
      </ResponseField>
    </Expandable>
  </Tab>

  <Tab title="watsonx.ai External Agent">
    To call out to agents on the watsonx.ai platform, set the provider to `wx.ai`.

    ```bash BASH [expandable] theme={null}
    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"
    ```

    <Expandable title="command flags">
      <ResponseField name="--name / -n" type="string">
        The name of the agent you want to create.
      </ResponseField>

      <ResponseField name="--kind / -k" type="string">
        The kind of agent you wish to create. For external agents, the value should be `external`.
      </ResponseField>

      <ResponseField name="--title / -t" type="string">
        The title of the agent you wish to create.
      </ResponseField>

      <ResponseField name="--description" type="string">
        The description of the agent.
      </ResponseField>

      <ResponseField name="--api / -a" type="string">
        The external API URL your agent will use.
      </ResponseField>

      <ResponseField name="--auth-config" type="string">
        The external API auth config in JSON format (e.g., `{"token": "sometoken"}`).
      </ResponseField>

      <ResponseField name="--auth-scheme" type="string">
        The external API auth scheme (e.g., API\_KEY for WX.AI).
      </ResponseField>

      <ResponseField name="--tags" type="string">
        The list of tags for the agent. Format: `--tags tag1 --tags tag2 ...`. Only needed for external and assistant agents.
      </ResponseField>

      <ResponseField name="--chat-params" type="string">
        The chat parameters in JSON format (e.g., `{"stream": true}`). Only needed for external and assistant agents.
      </ResponseField>

      <ResponseField name="--config" type="string">
        The agent configuration in JSON format (e.g., `{"hidden": false, "enable_cot": false}`).
      </ResponseField>

      <ResponseField name="--nickname" type="string">
        The agent's nickname.
      </ResponseField>

      <ResponseField name="--app-id" type="string">
        The application connection name used by the watsonx.ai external agent.
      </ResponseField>

      <ResponseField name="--provider" type="string">
        The external agent provider. It will be `wx.ai` for WX.AI agents.
      </ResponseField>

      <ResponseField name="--output" type="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.
      </ResponseField>
    </Expandable>
  </Tab>

  <Tab title="Custom agents">
    To create a custom agent, use the flags:

    ```bash BASH theme={null}
    orchestrate agents create --style custom --package-root <path to agent package root> --config-file <path to agent configuration file>
    ```

    <Expandable title="command flags">
      <ResponseField name="--package-root" type="string">
        (Custom agents) Path to the directory containing custom agent code. The directory will be automatically zipped and uploaded.
      </ResponseField>

      <ResponseField name="--config-file" type="string">
        (Custom agents) Path to a config.yaml file to include in the custom agent package. Only used with --package-root.
      </ResponseField>

      <ResponseField name="--style" type="string" post={['values: default, react, planner, custom, experimental_customer_care, react_core']}>
        The style of agent you wish to create. For custom agents, use `custom`. \[default: default]
      </ResponseField>
    </Expandable>

    <Note>
      **Note:**

      Starting from version 2.11.0, when you declare connections in your `agent.yaml` file, the system automatically maps them to your agent during import. For information, see [Associating connections to Custom agents](../connections/connections_for_custom_agents).
    </Note>
  </Tab>
</Tabs>

## Copy agents between workspaces

```bash BASH theme={null}
orchestrate agents copy --name <agent-name> --source <source-workspace-name> --destination <dest-workspace-name>
```

<Expandable title="command flags">
  <ResponseField name="--name / -n" type="string" required>
    Name of the agent to copy.
  </ResponseField>

  <ResponseField name="--destination / -d" type="string">
    Destination workspace name where the agent will be copied to.
  </ResponseField>

  <ResponseField name="--source / -s" type="string">
    Source workspace name (defaults to active workspace if not specified).
  </ResponseField>
</Expandable>

## 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>
  **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.
</Note>

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

<Note>
  **Note:**
  By default the deploy agent command timesout after 5 minutes of checking the agent status.
  If you need to increase this you can use the `WXO_AGENT_DEPLOYMENT_TIMEOUT` environment variable. Default value is `300`.
</Note>

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