Skip to main content
IronLabs AgentOpt uses Claude as a proposer to iteratively rewrite your agent’s system prompt, benchmark each variant in an isolated sandbox, and return the best-scoring version — all without manual prompt engineering.

Python SDK

pip install ironlabs

Node.js SDK

npm install ironlabs

When to use AgentOpt

  • Automated prompt engineering — replace manual trial-and-error with a data-driven optimization loop
  • Agent quality improvement — boost task accuracy without changing your agent’s code structure
  • Benchmark-driven development — optimize against your own evaluation function and dataset
  • Model-specific tuning — find the best system prompt for a specific target model

Prerequisites

Before you start, make sure you have:
  • An IronLabs API key from the Settings page
  • A ZIP bundle containing agent.py, eval.py, and dataset.json hosted at a publicly accessible URL
  • Minimum 10 rows in your dataset

Installation

Install the SDK for your language:

Initialize the client

Set your API key as an environment variable:
Then initialize the optimizer in your code:
The client automatically picks up IRONLABS_API_KEY from your environment — no need to pass it explicitly.

Running an Optimization

1

Prepare your ZIP bundle

AgentOpt requires three files packed into a single ZIP:

agent.py

The EDITABLE section is what AgentOpt rewrites each iteration. The FIXED section defines the interface contract and is never modified.

eval.py

Must define a score function that returns a float between 0.0 and 1.0:

dataset.json

A JSON array of input/answer pairs (minimum 10 rows):
Pack the three files into a ZIP and host it at a publicly accessible URL:
2

Submit the optimization job

Pass the ZIP URL, target model, and number of iterations to start the job.
Parameters:Response:
3

Monitor progress

Poll get_status() every 30 seconds. The response includes live per-iteration progress once the job starts running.
Status values:AgentOpt-specific status fields:
4

Get results

Retrieve the optimized prompt and performance metrics once the job completes.
Response:
Result fields:

Complete example


How AgentOpt works

AgentOpt runs a closed optimization loop:
  1. Baseline — runs your original agent.py on the dataset to establish a starting score
  2. Propose — Claude reads the current system prompt and proposes an improved version
  3. Benchmark — the proposed variant runs in an isolated sandbox against the dataset
  4. Accept or reject — improvements are kept; regressions are discarded
  5. Repeat — steps 2–4 repeat for n_iterations iterations
The best-scoring agent.py (with the winning system prompt embedded) is returned at the end.

Error handling