> ## 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.
# Authoring agents with the Orchestrate AI Builder
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](../developer_edition/wxOde_overview), add the `--with-ai-builder` flag to the `orchestrate server start` command. For more information, see [Installing watsonx Orchestrate Developer Edition: watsonx Orchestrate server](../developer_edition/wxOde_setup#installing-watsonx-orchestrate-developer-edition%3A-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 BASH theme={null}
orchestrate agents ai-builder create
```
The path to a YAML file where the Orchestrate AI Builder saves the new agent specification. Do not set this flag if you use the `--dry-run` flag.
Determines which model the underlying Orchestrate AI Builder server uses. Currently, the model name must end with `llama-3-3-70b-instruct` or `gpt-oss-120b`, but it can originate from any supported model provider.
The LLM to be used by the created agent. The default is `groq/openai/gpt-oss-120b`.
A flag that prevents saving the results to a file. Prints the new agent specification to the console instead.
A description of what you want the newly created agent to do. If not set, the Orchestrate AI Builder prompts you to enter the description in the interactive CLI session.
**Command examples**
Basic agent creation:
```bash BASH theme={null}
orchestrate agents ai-builder create -o output.yaml
```
Agent creation with selected LLM:
```bash BASH theme={null}
orchestrate agents ai-builder create -o output.yaml --llm groq/openai/gpt-oss-120b
```
Agent creation with specified description:
```bash BASH theme={null}
orchestrate agents ai-builder create -o output.yaml -d "I want an agent that can perform basic calculations"
```
Agent creation dry run:
```bash BASH theme={null}
orchestrate agents ai-builder create --dry-run
```
**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.
```text BASH [expandable] theme={null}
๐ค 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 BASH theme={null}
orchestrate agents ai-builder prompt-tune
```
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 agents](#creating-agents).
The path to a YAML file where the Orchestrate AI Builder saves the new agent specification. If not set, the Orchestrate AI Builder 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.
A flag that prevents saving the results to a file. Prints the new agent specification to the console instead.
Determines which model the underlying Orchestrate AI Builder server uses. Currently, the model name must end with `llama-3-3-70b-instruct` or `gpt-oss-120b`, but it can originate from any supported model provider.
The LLM to be used by the refined agent. The default is to leave it unchanged.
**Command examples**
Refine an existing agent and overwrite the input file:
```bash BASH theme={null}
orchestrate agents ai-builder prompt-tune -f input.yaml
```
Refine an agent and write the output to a new file:
```bash BASH theme={null}
orchestrate agents ai-builder prompt-tune -f input.yaml -o output.yaml
```
Refine an agent and print the output to the console instead of creating an output file:
```bash BASH theme={null}
orchestrate agents ai-builder prompt-tune -f input.yaml --dry-run
```
**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.
```text BASH [expandable] theme={null}
๐ค 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.
After providing feedback, run the following command to refine an agent using feedback from chat sessions:
```bash BASH theme={null}
orchestrate agents ai-builder autotune
```
The name of the agent to refine.
The path to a YAML file where the Orchestrate AI Builder saves the new agent specification. Do not set this flag if you use the `--dry-run` flag.
A flag that prevents saving the results to a file. Prints the new agent specification to the console instead.
Use the last chat message instead of interactively selecting the messages to refine from.
Determines which model the underlying Orchestrate AI Builder server uses. Currently, the model name must end with `llama-3-3-70b-instruct` or `gpt-oss-120b`, but it can originate from any supported model provider.
**Command examples**
Autotune an agent with interactive message selection:
```bash BASH theme={null}
orchestrate agents ai-builder autotune -n -o .yaml
```
Autotune an agent with interactive message selection. Output to console instead of creating an output file:
```bash BASH theme={null}
orchestrate agents ai-builder autotune -n --dry-run
```
Autotune the agent using the most recent chat message instead of interactively selecting messages to refine from:
```bash BASH theme={null}
orchestrate agents ai-builder autotune -n -o .yaml -l
```
**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.
```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
```