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

# OpenAI Decisions

> Typed decisions over text and images using a dedicated judge extension.

OpenAI Decisions evaluates shared evidence and returns a probability, a fixed choice, or a rubric score. The extension uses the official OpenAI Java SDK and lives under `agentscope-extensions-judge`, alongside JEV, and exposes `OpenAIDecisionsClient` independently of the chat model APIs. Applications can use its results to classify requests or choose their next action.

The [official guide](https://developers.openai.com/api/docs/guides/decisions) describes the API as public beta. The [API reference](https://developers.openai.com/api/reference/resources/decisions/methods/create) lists `gpt-6-luna`; this is the client's default model. Service access depends on your OpenAI account.

## Dependency and first decision

This addition targets `2.1.0-SNAPSHOT`; use a build containing this extension. With the AgentScope BOM, omit the dependency version.

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-openai-decisions</artifactId>
    <version>2.1.0-SNAPSHOT</version>
</dependency>
```

Set `OPENAI_API_KEY` before running. An explicit builder key takes precedence over the environment. Calling the following example sends the text and question to OpenAI and may incur charges.

```java theme={null}
import io.agentscope.extensions.judge.openaidecisions.DecisionAnswer;
import io.agentscope.extensions.judge.openaidecisions.DecisionQuestion;
import io.agentscope.extensions.judge.openaidecisions.DecisionRequest;
import io.agentscope.extensions.judge.openaidecisions.DecisionResult;
import io.agentscope.extensions.judge.openaidecisions.OpenAIDecisionsClient;
import java.util.List;

OpenAIDecisionsClient client = OpenAIDecisionsClient.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .build();
DecisionRequest request = DecisionRequest.builder()
        .input("I was charged twice for my order.")
        .question("department", new DecisionQuestion.Choice(
                "Which team should handle this?",
                List.of(new DecisionQuestion.Option("billing", "Payments and refunds"),
                        new DecisionQuestion.Option("technical", "Product issues"))))
        .build();
DecisionResult result = client.decideBlocking(request);
DecisionAnswer answer = result.answers().get("department");
if (answer instanceof DecisionAnswer.Choice choice) {
    System.out.println(choice.choice());
    System.out.println(choice.confidence());
    System.out.println(choice.probabilities());
} else if (answer instanceof DecisionAnswer.Refusal) {
    System.out.println("Send to manual review");
}
```

`DecisionRequest` contains 1–400 uniquely named questions. The optional request model overrides the client model. Inputs and question collections are copied when constructed, so a request can be reused safely. The optional `promptCacheKey()` partitions cache reuse; this extension does not expose `prompt_cache_options` or explicit cache breakpoints, so OpenAI uses its default implicit caching. `decide()` returns a cold `Mono`: each subscription sends a request. Use it in reactive applications; `decideBlocking()` is a convenience for non-reactive threads.

## Questions and answers

All public types are in `io.agentscope.extensions.judge.openaidecisions`.

| Question | Definition | Successful answer |
| - | - | - |
| `DecisionQuestion.Predicate` | Instructions describing a condition | `DecisionAnswer.Predicate.probability()` in \[0, 1] |
| `DecisionQuestion.Choice` | Instructions and 2–255 distinct `Option` values | `DecisionAnswer.Choice` with the selected value, confidence, and per-option probabilities |
| `DecisionQuestion.Score` | Instructions and a nonempty ordered list of `Level` values | `DecisionAnswer.Score` with the probability-weighted zero-based level index, confidence, and per-level probabilities |

Choice values may be strings or booleans; `"true"` and `true` are distinct. An option's description and a level's description are optional. Confidence is preserved separately from the selected probability. Do not interpret either as an application-specific guarantee of correctness; choose thresholds using labeled examples.

Every question may instead return `DecisionAnswer.Refusal`. Check for this type before taking an action. Other valid answers and usage remain available in the same `DecisionResult`. Refusals are not converted into zero probabilities or guessed choices.

The client matches answers by name and distribution entries by value/index, so response ordering is not significant. Missing, duplicate, unknown, or mismatched answers are rejected. Every choice or level must appear exactly once, numeric fields must be present and finite, probabilities and confidence must be in \[0, 1], and probabilities must sum to one within `1e-6 × option count`. The chosen value must be one of the supplied options; the score must match the weighted indices within the same tolerance. Values are preserved without normalization. An invalid response fails the entire `Mono` with `OpenAIDecisionsException`.

`DecisionResult.usage()` contains input, output, and total token counts supplied by the provider. It also flattens the provider's token-detail fields into `cachedTokens`, `cacheWriteTokens`, and `reasoningTokens`. Missing usage is `null`; missing individual counts and detail fields remain `null`. A real zero remains zero. Usage on failed calls is not exposed.

## Images and mixed input

Pass image URLs to `DecisionInput.image(url)` for image-only input, or construct `DecisionInput(text, imageUrls)` to combine text and up to 128 images in one user message. `pngBytes` below represents PNG data loaded by your application.

```java theme={null}
import io.agentscope.extensions.judge.openaidecisions.DecisionInput;
import java.util.Base64;

String dataUrl = "data:image/png;base64," + Base64.getEncoder().encodeToString(pngBytes);
DecisionRequest imageRequest = DecisionRequest.builder()
        .input(new DecisionInput("Inspect the product.", List.of(dataUrl)))
        .question("damaged", new DecisionQuestion.Predicate("Is there visible damage?"))
        .build();
client.decide(imageRequest).subscribe(imageResult -> System.out.println(imageResult.answers()));
```

The client accepts image data URLs and publicly accessible HTTP(S) image URLs, matching the API reference and official guide. The Java client sends these values to the provider without fetching the images locally; repository tests do not verify compatibility with a live service. The request API supports text and a single user message with text/image parts. The middleware examples below project conversation text and tool-call evidence into a text input; they do not add native tool calling or expose prompt-cache options.

## Configuration and failures

The default API base is `https://api.openai.com/v1`. `baseUrl()` accepts a versioned API base, including any gateway path prefix, or a complete `/decisions` endpoint. Credentials, query strings, and fragments are rejected in the base URL. A custom base should retain the API version path.

The default timeout is 30 seconds and must be positive. Blocking SDK calls run on Reactor's `boundedElastic` scheduler. The timeout is also passed to the SDK. Timeout and cancellation interrupt the executing task; the SDK transport determines when an in-flight network call stops. Close clients created by the wrapper with `close()` or try-with-resources to release SDK connections. Spring closes the auto-configured client when its context shuts down.

HTTP failures expose a status code through `OpenAIDecisionsException.getStatusCode()`. HTTP 429, 5xx, client timeouts, SDK I/O failures, and errors explicitly marked retryable by the SDK carry a retry hint. Invalid responses and permanent HTTP errors are not retried. Provider bodies and raw SDK causes are omitted from client-generated exceptions.

Wrapper retries are disabled by default, preserving one attempt per subscription. To opt into the same retry count and initial backoff as JEV, configure:

```java theme={null}
import io.agentscope.extensions.judge.openaidecisions.OpenAIDecisionsRetryPolicy;

OpenAIDecisionsClient retryingClient = OpenAIDecisionsClient.builder()
        .retryPolicy(OpenAIDecisionsRetryPolicy.defaults())
        .build();
```

`defaults()` allows two additional attempts with an initial 500 ms exponential backoff and jitter. A custom `new OpenAIDecisionsRetryPolicy(maxRetries, initialBackoff)` controls the limit; `disabled()` allows none. The timeout applies separately to each attempt, so total latency also includes retries and backoff. Exhaustion emits the last sanitized failure. Refusal answers remain ordinary results and are not retried.

The wrapper disables SDK retries on clients it creates. `builder().client(openAIClient)` borrows an SDK client whose credentials, base URL, retry settings, and lifecycle remain controlled by its owner. Disable that SDK client's retries before enabling wrapper retries to avoid multiplying attempts. Cancellation stops the reactive retry sequence; termination of in-flight network I/O remains transport-dependent.

## Agent middleware examples

Three opt-in middleware implementations live in `io.agentscope.extensions.judge.openaidecisions.example`. They follow the JEV model-routing, tool-selection, and automatic-execution use cases without depending on the JEV extension. Each is disabled by default and requires `.enabled(true)`. They are application wiring examples rather than automatic Spring beans.

| Middleware | Behavior when enabled | Default fallback |
| - | - | - |
| `OpenAIDecisionsModelRouterMiddleware` | One choice per agent invocation; stores the route in `RuntimeContext` and applies it in `onModelCall` | Keeps the original model on refusal, confidence below 0.8, or request failure |
| `OpenAIDecisionsToolSelectionMiddleware` | Scores each optional tool with an independent predicate on every reasoning step; selects up to three tools at probability 0.8 or above | Keeps the original tool set on refusal, request failure, or any probability strictly between 0.2 and 0.8 |
| `OpenAIDecisionsAutoModeMiddleware` | Checks each configured guarded call before dispatch; requires P(safe) of at least 0.8 | Denies guarded calls on refusal, missing context, or request failure |

The router accepts 2–255 named model choices. By default it retains the original model for requests containing tools, and checks native structured-output support when a response format is present. Use `.compatible((input, choice) -> ...)` only after checking the candidate model against your tools, input modalities, and output requirements. Routing and selection use `failOpen(true)` by default; setting it to `false` propagates request failures. Guard `failOpen(true)` explicitly allows request failures and missing context, but never turns a refusal into permission to execute.

The selector preserves `load_skill_through_path`, `reset_tools`, and `generate_response` outside its optional-tool limit. Customize this set with `alwaysIncludeTools(Set.of(...))`. A tool named by the current request's `ToolChoice.Specific` is also preserved outside that limit if it exists in the input catalog; it is not scored or created by the selector. A confident rejection can remove every optional tool. Selection uses at most eight recent nonblank text messages and 8,000 text characters by default; `maxContextMessages` and `maxContextChars` configure the window. Text inside tool-result blocks is included in the same message and character budgets. The guard uses the same fixed window and includes the exact tool names and arguments as separate JSON evidence. Images in the conversation are not forwarded by these examples. The selector and guard split more than 400 questions into sequential requests.

```java theme={null}
import io.agentscope.extensions.judge.openaidecisions.example.OpenAIDecisionsModelRouterMiddleware;
import io.agentscope.extensions.judge.openaidecisions.example.OpenAIDecisionsToolSelectionMiddleware;
import io.agentscope.extensions.judge.openaidecisions.example.OpenAIDecisionsAutoModeMiddleware;

var router = OpenAIDecisionsModelRouterMiddleware.builder(client)
        .enabled(true)
        .choice("fast", fastModel, "Simple lookups")
        .choice("capable", capableModel, "Complex analysis")
        .build();
var selector = OpenAIDecisionsToolSelectionMiddleware.builder(client)
        .enabled(true).maxTools(3).build();
var guard = OpenAIDecisionsAutoModeMiddleware.builder(client)
        .enabled(true).guardedTool("execute").guardedTool("write_file").build();
// Add these with ReActAgent.builder().middleware(router).middleware(selector).middleware(guard).
```

The guard skips calls already marked `ALLOWED` by the permission workflow. Passing its assessment does not grant core permission: allowed and unguarded calls still go through the normal acting pipeline. Denied calls never reach the downstream dispatcher; they produce `DENIED` tool-result messages and start/text/end events so that the model can continue from the result. Cancellation during an assessment neither dispatches tools nor creates denial messages.

These examples do not implement JEV's broader execution modes, confirmation ledger, phase routing, RAG, compaction, or evaluation extensions. Tests use local fixtures and stub decisions; they establish neither live-provider quality nor production safety thresholds.

### Runnable scenarios

The `agentscope-examples/openai-decisions` module provides `io.agentscope.examples.decisions.OpenAIDecisionsMiddlewareExample` with three independent modes: `route`, `select`, and `guard`. It prints decision answers, the actual model and tool schemas, and tool-result states. All business tools are simulated, including file deletion. Running the main method makes real Decisions and Chat Completions requests.

From the repository root:

```shell theme={null}
mvn -B -T1C -pl agentscope-dependencies-bom,agentscope-distribution/agentscope-bom,agentscope-examples/openai-decisions -am install -DskipTests
mvn -B -T1C -pl agentscope-examples/openai-decisions org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=io.agentscope.examples.decisions.OpenAIDecisionsMiddlewareExample" "-Dexec.args=route"
```

Set `OPENAI_API_KEY`, `OPENAI_MODEL` (a Chat Completions model supporting tools), and `OPENAI_FAST_MODEL` (required only for `route`). Supply model names without the `openai:` prefix. Replace `route` with `select` or `guard`, or append a custom prompt using `"-Dexec.args=route Design a distributed task scheduler"`. The module README includes environment setup and offline verification commands. Real decision results and whether the chat model calls a tool depend on the models; the sample prompts do not guarantee a particular route or denial.

When either chat model is `gpt-6-luna`, the example sets that model's `reasoning_effort` to `none`, as required for function tools through Chat Completions. This applies to chat requests only; Decisions and other chat models retain their defaults.

If connections time out, configure the JVM's HTTP/HTTPS proxy properties for both clients as described in the example module's README. The main method reports sanitized Decisions failures before fallback and shuts down Reactor's shared schedulers on exit; this shutdown is specific to the standalone example.

## Spring Boot

Use the starter dependency instead of adding the extension directly, then inject `OpenAIDecisionsClient`.

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-openai-decisions-spring-boot-starter</artifactId>
    <version>2.1.0-SNAPSHOT</version>
</dependency>
```

```yaml theme={null}
agentscope:
  openai-decisions:
    api-key: ${OPENAI_API_KEY}
    model: gpt-6-luna
    base-url: https://api.openai.com/v1
    timeout: 30s
    retry:
      max-retries: 0
      initial-backoff: 500ms
```

The defaults above also apply to the starter. `agentscope.openai-decisions.enabled=false` disables client creation. A user-defined client bean takes precedence. Implement `OpenAIDecisionsClientBuilderCustomizer` to supply an official SDK client or override properties; Spring applies ordered customizers after binding properties.

Set `retry.max-retries` to `2` to enable wrapper retries. Counts must be nonnegative and the backoff must be positive. These properties configure the client, not the middleware; register the desired middleware explicitly on each agent.

A complete three-question example and image-input helper are available in `agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/judge/OpenAIDecisionsExample.java`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.