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:

{
  "scores": {
    "acceptance-statement-0": {
      "score": 1.0,
      "rationale": "The response cleanly routes to the lodging-agent...",
      "duration_ms": 9795.46,
      "usage": {
        "total": 4050,
        "input": 3088,
        "output": 962
      }
    }
  },
  "completion_response": "Routing to **lodging-agent**.\n\nHandoff context:\n- User ID: user-125...",
  "current_instructions": "You are a travel agent orchestrator...",
  "current_parameters": {},
  "current_variables": {
    "trip_purpose": "business",
    "user_id": "user-125"
  },
  "current_model": "claude-sonnet-4-5",
  "user_input": "airbnbs near tahoe",
  "iteration": 5,
  "duration_ms": 2536.83,
  "usage": {
    "total": 1234,
    "input": 1109,
    "output": 125
  },
  "history": []
}

Fields

This table describes the fields available in OptimizationContext:

Field	Type	Description
`scores`	Object	A 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_response`	String	The raw text output returned by the agent for this iteration.
`current_instructions`	String	The system prompt or instructions used for this iteration, with all variables already interpolated.
`current_parameters`	Object	The full set of model parameters used for this iteration as returned by the AgentControl config.
`current_variables`	Object	The variable set selected and interpolated into the instructions for this iteration.
`current_model`	String	The model ID used for this iteration.
`user_input`	String	The user input message sent to the agent for this iteration.
`iteration`	Integer	The iteration number for this context. 1-indexed.
`duration_ms`	Number	Wall-clock time in milliseconds for the agent call in this iteration.
`usage`	`TokenUsage`	Aggregate token usage for the agent call in this iteration. `None` if the handler did not report usage.
`history`	Array	A 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:

Field	Type	Description
`score`	Number	A float between `0.0` and `1.0` representing the judge’s pass/fail score for this iteration.
`rationale`	String	A human-readable explanation of the score produced by the judge LLM. `None` if not available.
`duration_ms`	Number	Time in milliseconds taken by the judge call. `None` if not tracked.
`usage`	`TokenUsage`	Token usage for this individual judge call. `None` if not reported.

TokenUsage

Used in both OptimizationContext.usage and JudgeResult.usage:

Field	Type	Description
`total`	Integer	Total tokens used. Calculated as input plus output.
`input`	Integer	Number of input, or prompt, tokens.
`output`	Integer	Number of output, or completion, tokens.

Get started

AgentControl

Feature flags

Releases

Observability

Experimentation

Metrics and events

Warehouse native

Infrastructure

Your account

OptimizationContext reference

Example OptimizationContext object

Fields

JudgeResult

TokenUsage

​Example OptimizationContext object

​Fields

​JudgeResult

​TokenUsage

Example OptimizationContext object

Fields

JudgeResult

TokenUsage