Skip to main content

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.

The Orchestrate AI Builder is a powerful tool that helps you create and refine agents. It simplifies agent creation by allowing you to describe the agent you want. The AI Builder leverages its internal AI to create a new agent from scratch. The AI Builder can also help with existing agents through conversational interaction where you specify changes, or by using past conversations and feedback to automatically adjust the agent’s behavior to align with expectations.
To use the AI Builder in the watsonx Orchestrate Developer Edition, add the --with-ai-builder flag to the orchestrate server start command. For more information, see Installing watsonx Orchestrate Developer Edition: watsonx Orchestrate server.

​
Creating agents

Use the Orchestrate AI Builder to guide the agent creation flow. Start from scratch and build the agent through natural conversation.
BASH
orchestrate agents ai-builder create
Command examples
Basic agent creation:
BASH
orchestrate agents ai-builder create -o output.yaml
Orchestrate AI Builder interaction example The following example shows how you interact with the Orchestrate AI Builder to create an agent. In this example, you have already created and imported the string_reverser tool into your local instance.
BASH
🤖 Builder: To create a configuration for your agent in the IBM watsonx Orchestrate platform, let's start by describing the functionality of your agent. What tasks do you want your agent to perform, and what kind of operations should it be able to handle? Please provide a detailed or high-level description of your agent's intended functionality.

👤 You: I want to create an agent that can reverse strings

🤖 Builder: Based on your agent description, I've sorted the available tools by their relevancy and suggest the following tools for your agent:

1. **string_reverser**: A tool that can reverse any provided string.

Please select the tools you want your agent to use by specifying their numbers or names. If you want to see the full list of available tools, I can provide that as well. 

Remember, you can choose one, multiple, or no tools for your agent.

👤 You: 1

🤖 Builder: You have selected the **string_reverser** tool for your agent.

🤖 Builder: Based on your task description, I'll create an initial prompt. 

**Role** - 
You are an agent that can reverse strings according to the user's input.

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

Here's my initial prompt. How would you like the output to be formatted? Would you like it to be in a specific format, such as uppercase or lowercase?

👤 You: No use that prompt its perfect

╔══════════════════════════════════════════════════════════════════╗
║  Your agent building session finished successfully!             ║
║  Agent YAML saved in file:                                      ║
║  /Users/user123/output.yaml                                     ║
╚══════════════════════════════════════════════════════════════════╝

​
Refining agents

Use the 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 the Orchestrate AI Builder to refine an agent. In this example, you have 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 columns. 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 that 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 an agent with interactive message selection:
BASH
orchestrate agents ai-builder autotune -n <agent_name> -o <output_path>.yaml
Orchestrate AI Builder interaction example The following example shows how you interact with the watsonx Orchestrate AI Builder to refine an agent. In this example, you have 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