Skip to main content
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 describes the API as public beta. The API reference 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.
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.
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. 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.
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:
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. 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.
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:
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.
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.