Optimize agent prompts

Preview - Agent evaluation on Gemini Enterprise Agent Platform

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms as well as the Generative AI Service Specific Terms. This feature allows customers to evaluate AI Agents, and so the "Agentic AI Services" Service Specific Terms apply. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Optimization is the final stage of the Quality Flywheel. The Quality Flywheel is a continuous cycle of evaluation, analysis, and optimization. You evaluate your agent's performance, analyze the results to identify clusters of failures, and then optimize your prompts or configuration to address those specific issues. Each iteration of this cycle incrementally improves the quality and reliability of your agent.

After you have identified systemic issues through evaluation and failure clustering, you can use the Optimizer service to programmatically refine your agent's system instructions or tool descriptions. This automated process identifies the exact points of failure and iteratively proposes targeted updates until it finds the optimal prompt for your evaluation dataset.

The optimization flywheel

Refining an agent typically follows a three-step loop:

1. Analyze Failures: Identify specific behavioral gaps, such as a cluster of failures where the agent fails to verify user identity.
2. Propose Improvements: The Optimizer generates a "patch" for the system instruction (for example, "Always ask for a frequent flyer number before confirming a booking").
3. Verify Gains: The system automatically runs a side-by-side comparison evaluation to ensure the new instruction improves scores without causing regressions.

Optimize programmatically with the SDK

You can trigger an optimization job directly using the Agent Platform SDK. The Optimizer uses advanced methods like GEPA or MIPRO to derive new rules from your test cases.

# Automatically refine the system prompt to fix identified issues
optimize_result = client.optimizer.optimize(
    targets=["system_prompt"],    # Specify which resource to optimize
    benchmark=eval_result,       # Use results from a previous evaluation run
    tests=eval_dataset,          # The test cases the agent should pass
    optimization_params={
        "method": "gepa",        # Use the GEPA optimization method
        "num_steps": 5           # Number of iterations to perform
    }
)

# Preview the optimized instruction
print("Optimized Instruction:", optimize_result.instruction)

Optimize using the CLI

For local development, you can use the adk optimize command to update your agent code directly from the terminal.

1. Run the optimization command, targeting your local agent module: sh adk optimize . --target instruction --eval_set my_test_suite
2. Review the proposed changes in the terminal.
3. Enter y to apply the optimized instructions to your agent.py file.

For general information see Optimize agents in the Agent Development Kit documentation.