> ## 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.
# Refining agent with Orchestrate copilot
## Conversation Agent Refinement
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file` (`-f`) | string | yes | The path to an existing agent specification. This specification starts the prompt refinement flow. Without this flag, the agent creation flow starts instead. For more information, see [Creating agent with Orchestrate copilot](./creating_agent). |
| `--output-file` (`-o`) | string | Yes | The path to a YAML or JSON file where Orchestrate copilot saves the new agent specification. If not set, Orchestrate copilot uses the same path as the file used to start the prompt refinement flow, which overwrites the original agent specification.
Do not set this flag if you use the `--dry-run` flag. |
| `--dry-run` | string | No | A flag that prevents saving the results to a file. Orchestrate copilot prints the new agent specification to the console instead. |
| `--samples` (`-s`) | string | No | The path to a CSV or TXT file with sample utterances the agent should handle. If not set, Orchestrate copilot prompts you to enter three examples in the interactive CLI session. |
**Note:**
If you use the `--help` flag with this command, you see that it also includes the `--llm` flag. This flag applies only to the agent creation flow. If you set it to start the refinement flow, Orchestrate copilot ignores it. For more information, see [Creating agent with Orchestrate copilot](./creating_agent).
**Command examples**
Refine an existing agent and overwrite the input file
```bash BASH theme={null}
orchestrate copilot prompt-tune -f input.yaml
```
Refine an agent and write the output to a new file
```bash BASH theme={null}
orchestrate copilot prompt-tune -f input.yaml -o output.yaml
```
Refine an agent with provided samples file to avoid interactivly providing them
```bash BASH theme={null}
orchestrate copilot prompt-tune -f input.yaml -s samples.csv
```
Refine an agent and print the output to the console instead of creating an output file
```bash BASH theme={null}
orchestrate copilot prompt-tune -f input.yaml --dry-run
```
**Orchestrate copilot interation example**
The following example shows how you interact with Orchestrate copilot to refine an agent. In this case, you already created and imported the `string_reverser` tool into your local instance.
```text BASH [expandable] theme={null}
[INFO] - Please provide 3 sample utterances you expect your agent to handle:
>: reverse "xyz"
>: flip "abc"
>: invert "123"
[INFO] - You provided the following samples:
1. reverse "xyz"
2. flip "abc"
3. invert "123"
๐ค Copilot: Based on your task description, I'll create an initial prompt.
**Role** -
You are an agent that can reverse strings according to the given command.
**Tool Usage Guidelines** -
1. Before you call a tool, make sure you have all the required tool parameters.
2. Do NOT assume any tool parameters
3. Do NOT pass parameters to the tool that are not explicitly defined
4. Do NOT call the same tool multiple times with the same parameters
**How To Use Tools**
- When the user wants to reverse a string, call the string_reverser tool with the string as a parameter.
How would you like the output to be formatted? Should it be a simple reversed string, or would you like any additional information included?
๐ค You: I want the result formatted as a github markdown table with 2 coulmns. The left column should be the input and the right should be the output. Please include headers on the table
๐ค Copilot: Based on your requirements, I'll refine the prompt.
**Role** -
You are an agent that can reverse strings according to the given command.
**Tool Usage Guidelines** -
1. Before you call a tool, make sure you have all the required tool parameters.
2. Do NOT assume any tool parameters
3. Do NOT pass parameters to the tool that are not explicitly defined
4. Do NOT call the same tool multiple times with the same parameters
**How To Use Tools**
- When the user wants to reverse a string, call the string_reverser tool with the string as a parameter.
- Format the output of the string_reverser tool as a GitHub markdown table with two columns, "Input" and "Output", where the input string is in the "Input" column and the reversed string is
in the "Output" column.
Here's an example of what the output table might look like:
| Input | Output |
| --- | --- |
| xyz | zyx |
Are you interested in continuing to refine the prompt, or is this sufficient for your needs?
๐ค You: That is sufficient
```
## Automatic Agent Refinement (Autotune)
You can automatically refine an agent using feedback from chat sessions.
To do this, start by creating an agent and chatting with it. You will see two icons below each agent response which allow you to provide either positive or negative feedback.
After providing feedback, run the following command to refine an agent using feedback from chat sessions:
```bash BASH theme={null}
orchestrate copilot autotune
```
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent-name` (`-n`) | string | yes | The name of the agent to refine. |
| `--output-file` (`-o`) | string | No | The path to a YAML or JSON file where Orchestrate copilot saves the new agent specification.
Do not set this flag if you use the `--dry-run` flag. |
| `--dry-run` | bool | No | A flag that prevents saving the results to a file. Orchestrate copilot prints the new agent specification to the console instead. |
| `--use-last-chat` (`-l`) | bool | No | Use the last chat message instead of interactivly selecting the messages to refine from. |
**Command examples**
Autotune and agent with interactive message selection
```bash BASH theme={null}
orchestrate copilot autotune -n -o .yaml
```
Autotune and agent with interactive message selection. Output to console instead of creating an output file
```bash BASH theme={null}
orchestrate copilot autotune -n --dry-run
```
Autotune the agent using the most recent chat message instead of interactivly selecting messages to refine from.
```bash BASH theme={null}
orchestrate copilot autotune -n -o .yaml -l
```
**Orchestrate copilot interation example**
The following example shows how you interact with watsonx Orchestrate Copilot to refine an agent. Suppose youโve already created and imported a healthcare management agent, chatted with it, and provided feedback.
```text BASH [expandable] theme={null}
10 Most Recent Chats
โโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Number โ Chat Date โ Title โ Last User Message โ Last User Feedback โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ 1 โ October 01, 2025 at 12:49 PM โ Show me healthcare providers โ Show me healthcare providers โ ๐ This would be better as a table โ
โ โ โ โ โ โ
โโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Please enter up to 5 indices of chats you'd like to select, separated by commas (e.g. 1): 1
[INFO] - Your agent refinement session finished successfully!
[INFO] - Agent YAML with the updated instruction saved in file: .yaml
```