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

# 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 BASH theme={null}
orchestrate agents list -v
```

<Expandable title="command flags">
  <ResponseField name="--kind / -k" type="string">
    The kind of agent you wish to list. Valid options: `native`, `external`, `assistant`.
  </ResponseField>

  <ResponseField name="--verbose / -v" type="boolean">
    List full details of all agents in JSON format.
  </ResponseField>
</Expandable>

## 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 BASH theme={null}
orchestrate agents export -n <agent-name> -k <agent-type> -o <output-path>.zip
```

<Expandable title="command flags">
  <ResponseField name="--name / -n" type="string" required={true}>
    The name of the agent you want to export.
  </ResponseField>

  <ResponseField name="--kind / -k" type="string" required={true}>
    The type of the agent (`native` or `external`).
  </ResponseField>

  <ResponseField name="--output / -o" type="string" required={true}>
    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.
  </ResponseField>

  <ResponseField name="--agent-only" type="boolean">
    Exports only the agent configuration without its dependencies.
  </ResponseField>
</Expandable>

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

## Updating agents

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

```bash BASH theme={null}
orchestrate agents import -f <path to agent file that you want to update>
```

<Note>
  If you're updating an agent to use a different LLM (such as migrating from Llama to GPT-OSS-120B), see the [Migration guide](../llm/migrating_to_gpt_oss) for model-specific optimization instructions.
</Note>

## Removing agent

To remove an existing agent, run the following command:

```bash BASH theme={null}
orchestrate agents remove --name my-agent --kind native
```

<Expandable title="command flags">
  <ResponseField name="--name / -n" type="string" required={true}>
    Name of the agent you wish to remove.
  </ResponseField>

  <ResponseField name="--kind / -k" type="string" required={true}>
    The kind of agent you wish to remove. Valid options: `native`, `external`, `assistant`.
  </ResponseField>
</Expandable>

## Chatting with an agent in interactive mode through the CLI

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

```bash BASH theme={null}
orchestrate chat ask --agent-name <agent_name>
```

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

```bash BASH theme={null}
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 BASH theme={null}
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 BASH theme={null}
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 BASH theme={null}
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 BASH theme={null}
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 BASH theme={null}
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.

<Note>
  File prompts appear only when the agent workflow requires file interaction.
</Note>