Skip to main content
This cookbook provides a step-by-step walkthrough for optimizing a prompt using the agent-opt Python library. We will use the RandomSearchOptimizer to demonstrate the core workflow of generating prompt variations and selecting the best one based on performance.

​
1. Installation and Setup

First, install the library and set up your environment variables. You can get your API keys from the Future AGI dashboard. 
pip install agent-opt

import os

os.environ["FI_API_KEY"] = "YOUR_API_KEY"
os.environ["FI_SECRET_KEY"] = "YOUR_SECRET_KEY"

​
2. Prepare Your Dataset

Optimization requires a dataset to evaluate prompt performance. A dataset is a simple list of Python dictionaries. For this example, we’ll create a small dataset for a summarization task. 
dataset = [
    {
        "article": "The James Webb Space Telescope has captured stunning new images of the Pillars of Creation, revealing intricate details of gas and dust clouds where new stars are forming.",
        "target_summary": "The JWST has taken new, detailed pictures of the Pillars of Creation."
    },
    {
        "article": "Researchers have discovered a new enzyme that can break down plastics at record speed, offering a potential solution to the global plastic pollution crisis.",
        "target_summary": "A new enzyme that rapidly breaks down plastics has been found."
    },
]

​
3. Configure and Run the Optimization

Next, we’ll set up the necessary components:
  • Evaluator: To score our prompts based on a metric.
  • DataMapper: To map our dataset fields to the optimizer’s expected inputs.
  • RandomSearchOptimizer: To generate and test prompt variations.
from fi.opt.optimizers import RandomSearchOptimizer
from fi.opt.generators import LiteLLMGenerator
from fi.opt.datamappers import BasicDataMapper
from fi.opt.base.evaluator import Evaluator

# a. Define the generator with the initial prompt to be optimized
initial_prompt = "Summarize this: {article}"
initial_generator = LiteLLMGenerator(
    model="gpt-4o-mini",
    prompt_template=initial_prompt
)

# b. Setup the evaluator to score prompt performance
evaluator = Evaluator(
    eval_template="summary_quality",  # A built-in template for summarization
    eval_model_name="turing_flash"    # The model to perform the evaluation
)

# c. Setup the data mapper to link dataset fields
data_mapper = BasicDataMapper(
    key_map={"input": "article", "output": "generated_output"}
)

# d. Initialize the Random Search optimizer
optimizer = RandomSearchOptimizer(
    generator=initial_generator,
    teacher_model="gpt-4o",  # A powerful model to generate prompt ideas
    num_variations=5         # Generate 5 different versions of our prompt
)

# e. Run the optimization
result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=dataset
)

​
4. Analyze the Results

The result object contains the best prompt found and its final score. You can also inspect the history of all variations that were tried. 
# Print the best prompt and its score
print(f"--- Optimization Complete ---")
print(f"Final Score: {result.final_score:.4f}")
print(f"Best Prompt Found:\n{result.best_generator.get_prompt_template()}")

# Review the history of all tried variations
for i, iteration in enumerate(result.history):
    print(f"\n--- Variation {i+1} ---")
    print(f"Score: {iteration.average_score:.4f}")
    print(f"Prompt: {iteration.prompt}")
This basic workflow is the foundation for all other optimization tasks. You can now explore more advanced optimizers and evaluation techniques.