AgentControlAgent optimization

OptimizationContext reference

This topic has a full field reference for the OptimizationContext object returned by all optimization methods.

OptimizationContext is the return value of optimize_from_config, optimize_from_options, and optimize_from_ground_truth_options. It represents the final state of the optimization run and includes scores, the winning configuration, token usage, and the full iteration history.

Example OptimizationContext object

Here is an example OptimizationContext object:

JSON
1{
2  "scores": {
3    "acceptance-statement-0": {
4      "score": 1.0,
5      "rationale": "The response cleanly routes to the lodging-agent...",
6      "duration_ms": 9795.46,
7      "usage": {
8        "total": 4050,
9        "input": 3088,
10        "output": 962
11      }
12    }
13  },
14  "completion_response": "Routing to **lodging-agent**.\n\nHandoff context:\n- User ID: user-125...",
15  "current_instructions": "You are a travel agent orchestrator...",
16  "current_parameters": {},
17  "current_variables": {
18    "trip_purpose": "business",
19    "user_id": "user-125"
20  },
21  "current_model": "claude-sonnet-4-5",
22  "user_input": "airbnbs near tahoe",
23  "iteration": 5,
24  "duration_ms": 2536.83,
25  "usage": {
26    "total": 1234,
27    "input": 1109,
28    "output": 125
29  },
30  "history": []
31}

Fields

This table describes the fields available in OptimizationContext:

FieldTypeDescription
scoresObjectA dictionary mapping each judge key to a JudgeResult. Keys are either the name you gave the judge in your options (for example, "acceptance") or an auto-generated key for inline acceptance statements (for example, "acceptance-statement-0").
completion_responseStringThe raw text output returned by the agent for this iteration.
current_instructionsStringThe system prompt or instructions used for this iteration, with all variables already interpolated.
current_parametersObjectThe full set of model parameters used for this iteration as returned by the AgentControl config.
current_variablesObjectThe variable set selected and interpolated into the instructions for this iteration.
current_modelStringThe model ID used for this iteration.
user_inputStringThe user input message sent to the agent for this iteration.
iterationIntegerThe iteration number for this context. 1-indexed.
duration_msNumberWall-clock time in milliseconds for the agent call in this iteration.
usageTokenUsageAggregate token usage for the agent call in this iteration. None if the handler did not report usage.
historyArrayA list of OptimizationContext objects representing all previous iterations in the run, in order. Each entry in history omits its own nested history to keep the structure flat. The final returned context contains the full history of the run.

JudgeResult

Each entry in scores is a JudgeResult with the following fields:

FieldTypeDescription
scoreNumberA float between 0.0 and 1.0 representing the judge’s pass/fail score for this iteration.
rationaleStringA human-readable explanation of the score produced by the judge LLM. None if not available.
duration_msNumberTime in milliseconds taken by the judge call. None if not tracked.
usageTokenUsageToken usage for this individual judge call. None if not reported.

TokenUsage

Used in both OptimizationContext.usage and JudgeResult.usage:

FieldTypeDescription
totalIntegerTotal tokens used. Calculated as input plus output.
inputIntegerNumber of input, or prompt, tokens.
outputIntegerNumber of output, or completion, tokens.