Python SDK
pip install ironlabsNode.js SDK
npm install ironlabsWhen 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, anddataset.jsonhosted 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:Running an Optimization
1
Prepare your ZIP bundle
AgentOpt requires three files packed into a single ZIP:Pack the three files into a ZIP and host it at a publicly accessible URL:
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 ascore function that returns a float between 0.0 and 1.0:dataset.json
A JSON array of input/answer pairs (minimum 10 rows):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 Status values:
get_status() every 30 seconds. The response includes live per-iteration progress once the job starts running.AgentOpt-specific status fields:
4
Get results
Retrieve the optimized prompt and performance metrics once the job completes.Response:Result fields:
Complete example
View full end-to-end example
View full end-to-end example
How AgentOpt works
AgentOpt runs a closed optimization loop:- Baseline — runs your original
agent.pyon the dataset to establish a starting score - Propose — Claude reads the current system prompt and proposes an improved version
- Benchmark — the proposed variant runs in an isolated sandbox against the dataset
- Accept or reject — improvements are kept; regressions are discarded
- Repeat — steps 2–4 repeat for
n_iterationsiterations
agent.py (with the winning system prompt embedded) is returned at the end.