Agent Improver changes an AI Agent that already exists. Instead of opening the agent and editing its fields one by one, you describe the change you want in plain language. The assistant reads that agent's current configuration and answers with a list of concrete changes to approve: rewritten instructions, clearer tool descriptions, a new tool where the request needs one.
It is the counterpart to Building an AI Agent with AI, which creates an agent from a description. Agent Improver never creates one, and the Builder never changes one. What both panels need before they will run is on Agent Builder and Improver.
No test run is needed first. Improvements argued from an evaluated run instead are AI Agents Optimization.
Changes apply to the Draft version, and only after your approval.
What Agent Improver changes
Agent Improver rewrites and adds. It does not restructure.
| Area | What Agent Improver does |
|---|---|
| Instructions | Rewrites the agent's instructions. The previous wording is archived automatically before the new text is written. |
| Tool descriptions | Rewrites the description of an existing tool so the agent calls it at the right moment. |
| New tools | Adds a new tool definition: its name, description and parameters. |
| Existing tools | Never renamed and never deleted. |
| Architecture | Not changed. Agent Improver does not convert an agent into a supervisor, and does not add or remove sub-agents. |
| Agent name | Not changed. |
| Persona, Creativity, Response Detail | Not changed. |
A tool it adds arrives as a definition only: a name, a description and parameters, with nothing behind them. Open the new tool and build it, as a workflow, an API integration or a knowledge retrieval configuration, before the agent is expected to use it. See Tool Management.
Step 1: Open Agent Improver from the agent card
Open AI Agents in your project. Every existing agent card carries its own Improve with AI control, so an improvement session always starts from a specific agent rather than from a blank page.
1. Agent card: One card per agent in the project, with the agent's name, description and preparation state.
2. Improve with AI: The icon at the card's top right. It opens the Agent Improver panel for that agent and no other.
The running example in this article uses the BillingAssistant agent, which already has three tools.
Step 2: Describe the change you want
The panel opens beside the agent list and greets the agent by name, so it is always visible which agent the session is about.
1. Panel title: Reads Agent Improver, the assistant that changes an existing agent.
2. Subtitle: States the two rules of the session before anything is typed: changes apply to the Draft version, and only after your approval.
3. Greeting: Names the agent being improved.
4. Message box: Where you describe the change. The agent's current instructions and tools travel with your request, so the answer is about this agent rather than generic advice.
5. Attach files: Adds files to the message you are about to send. See Attaching files to a request below.
6. Microphone: Dictates the request instead of typing it. It is only shown when the project meets the conditions below.
7. Send: Sends the message. It stays disabled until the message box has text of its own.
For the running example, send:
Help customers understand unexpected charges on their invoices
💡 Tip: Describe the outcome you want in the customer's terms ("explain unexpected charges", "stop promising refunds we cannot make") rather than naming fields to edit. The assistant decides which field each change belongs in, and shows you before writing anything.
Attaching a file to the request, and dictating it instead of typing, work the same way in all three panels and are covered on Agent Builder and Improver.
Step 3: Review the proposals
The assistant answers with changes rather than advice. Each proposal names the agent it targets and the field it touches.
1. Your request: The message you sent, kept in the conversation timeline, with the names of any files you attached to it.
2. Proposal card: One proposed change. It names the target agent and the field it changes, for example a tool to add or instructions to rewrite.
3. Selection checkbox: Every proposal arrives already selected. Clear the ones you do not want.
4. Apply Selected: Opens the approval window. The button counts how many proposals are still selected, so the count follows your selection.
Proposals are generated for your agent and your request, so what you see will not match these screenshots.
Step 4: Approve the changes
Approval is its own step. The whole change is on screen before any part of it happens.
1. Change list: Every selected change, numbered, exactly as it will be applied.
2. Cancel: Closes the window without applying anything.
3. Confirming action: Applies every listed change. Approved changes are applied as a single batch, on the Draft version.
Nothing reaches the agent until this window is confirmed.
After the changes are applied, the panel asks you to complete the session and then summarises what changed, with a link to open the agent's detail page.
One session applies one batch. To improve the same agent again, or a different one, close the panel and open Improve with AI again.
What changes on the agent
1. Tools: The tool Agent Improver added now sits beside the ones the agent already had. In the running example, a fourth tool joins the original three.
2. Instructions History: The instruction versions saved for this agent, each with its timestamp and comment.
3. Archived entry: The instructions that were replaced, archived automatically on the way past and labelled Auto-archived before optimization. The previous wording stays readable, and can be compared against the current text from the same History window.
Archiving happens for the instructions Agent Improver replaces, while the tenant setting on the Agent Builder & Improver settings page is on. Saving instructions by hand still creates no version, so use Archive on the agent's page before a manual rewrite you may want back.
📝 Note: An improved agent is prepared again for you, which is an exception: every other change to an agent or its tools takes effect only after you prepare the agent yourself. If that automatic preparation fails, the panel says so and asks you to prepare the agent from its details page. See Creating an AI Agent for preparation states.
Supervisors and sub-agents
Improving a supervisor gives the assistant that supervisor and its sub-agents as context, so a proposal can target the supervisor or one of its sub-agents, and collaboration and transfer instructions can be updated in both directions. See Configuring Multi-Agent Systems.
Improving a single agent or a sub-agent on its own stays with that agent alone.
Limits and naming rules
Changes written by Agent Improver are subject to the same limits as changes you make by hand.
| Item | Value |
|---|---|
| Tools per agent | Maximum 20 |
| Tool names | Alphanumeric; underscores are accepted (e.g. get_invoice_details) |
| Tool parameter names | Must start with a letter or underscore, then letters, digits or underscores only. No spaces, no accented characters, and cannot start with a digit. Up to 200 characters |
| Tool parameter description | Up to 900 characters |
| Instructions Archive comment | Up to 200 characters |