Skip to main content
Note: To use AI Builder in watsonx Orchestrate Developer Edition, enable the feature by adding the --with-ai-builder flag to the orchestrate server start command. For more information, see Installing watsonx Orchestrate Developer Edition: watsonx Orchestrate server.

​
Conversation Agent Refinement

Use Orchestrate AI Builder to take an existing agent and improve its instructions with your input.
BASH
orchestrate agents ai-builder prompt-tune
Command examples
Refine an existing agent and overwrite the input file
BASH
orchestrate agents ai-builder prompt-tune -f input.yaml
Orchestrate AI Builder interaction example The following example shows how you interact with Orchestrate AI Builder to refine an agent. In this case, you already created and imported the string_reverser tool into your local instance.
BASH

🤖 Builder: 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

🤖 Builder: 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. ai-builder-feedback-section.png After providing feedback, run the following command to refine an agent using feedback from chat sessions:
BASH
orchestrate agents ai-builder autotune
Command examples
Autotune and agent with interactive message selection
BASH
orchestrate agents ai-builder autotune -n <agent_name> -o <output_path>.yaml
Orchestrate AI Builder interation example The following example shows how you interact with watsonx Orchestrate AI Builder to refine an agent. Suppose you’ve already created and imported a healthcare management agent, chatted with it, and provided feedback.
BASH
                                                            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: <output_path>.yaml