> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OptimizationContext reference

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

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:

<CodeGroup>
  ```json title="JSON" expandable lines wrap theme={null}
  {
    "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": []
  }
  ```
</CodeGroup>

## Fields

This table describes the fields available in `OptimizationContext`:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`scores`</td>
      <td>Object</td>
      <td>A dictionary mapping each judge key to a [`JudgeResult`](#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"`).</td>
    </tr>

    <tr>
      <td>`completion_response`</td>
      <td>String</td>
      <td>The raw text output returned by the agent for this iteration.</td>
    </tr>

    <tr>
      <td>`current_instructions`</td>
      <td>String</td>
      <td>The system prompt or instructions used for this iteration, with all variables already interpolated.</td>
    </tr>

    <tr>
      <td>`current_parameters`</td>
      <td>Object</td>
      <td>The full set of model parameters used for this iteration as returned by the AgentControl config.</td>
    </tr>

    <tr>
      <td>`current_variables`</td>
      <td>Object</td>
      <td>The variable set selected and interpolated into the instructions for this iteration.</td>
    </tr>

    <tr>
      <td>`current_model`</td>
      <td>String</td>
      <td>The model ID used for this iteration.</td>
    </tr>

    <tr>
      <td>`user_input`</td>
      <td>String</td>
      <td>The user input message sent to the agent for this iteration.</td>
    </tr>

    <tr>
      <td>`iteration`</td>
      <td>Integer</td>
      <td>The iteration number for this context. 1-indexed.</td>
    </tr>

    <tr>
      <td>`duration_ms`</td>
      <td>Number</td>
      <td>Wall-clock time in milliseconds for the agent call in this iteration.</td>
    </tr>

    <tr>
      <td>`usage`</td>
      <td>[`TokenUsage`](#tokenusage)</td>
      <td>Aggregate token usage for the agent call in this iteration. `None` if the handler did not report usage.</td>
    </tr>

    <tr>
      <td>`history`</td>
      <td>Array</td>
      <td>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.</td>
    </tr>
  </tbody>
</table>

### JudgeResult

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

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`score`</td>
      <td>Number</td>
      <td>A float between `0.0` and `1.0` representing the judge's pass/fail score for this iteration.</td>
    </tr>

    <tr>
      <td>`rationale`</td>
      <td>String</td>
      <td>A human-readable explanation of the score produced by the judge LLM. `None` if not available.</td>
    </tr>

    <tr>
      <td>`duration_ms`</td>
      <td>Number</td>
      <td>Time in milliseconds taken by the judge call. `None` if not tracked.</td>
    </tr>

    <tr>
      <td>`usage`</td>
      <td>[`TokenUsage`](#tokenusage)</td>
      <td>Token usage for this individual judge call. `None` if not reported.</td>
    </tr>
  </tbody>
</table>

### TokenUsage

Used in both `OptimizationContext.usage` and `JudgeResult.usage`:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`total`</td>
      <td>Integer</td>
      <td>Total tokens used. Calculated as input plus output.</td>
    </tr>

    <tr>
      <td>`input`</td>
      <td>Integer</td>
      <td>Number of input, or prompt, tokens.</td>
    </tr>

    <tr>
      <td>`output`</td>
      <td>Integer</td>
      <td>Number of output, or completion, tokens.</td>
    </tr>
  </tbody>
</table>