> ## 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.

# Create a client and request typed decisions

Use `JevClient` for structured decisions returning probabilities, choices or scores. The generation model you configure still writes the user's answer.

## Add the dependency

```xml theme={null}
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-extensions-jev</artifactId>
  <version>${agentscope.version}</version>
</dependency>
```

Harness middleware, compaction and Agent examples also require a matching `agentscope-harness` version. The extension's Harness dependency is optional.

## Example: is the claim “refund completed” supported?

The business record says no refund was initiated, but the Agent claims it finished. Put the answer and record in one state and ask whether the latter supports the former. The client sends and validates a typed request. A higher-level component decides whether to publish, revise or escalate.

## Request a decision and read the probability

```java theme={null}
import io.agentscope.extensions.judge.jev.*;
import java.time.Duration;
import java.util.Map;

var client = JevClient.builder()
    .apiKey(System.getenv("TYPESAFE_API_KEY"))
    .model("jev-latest")
    .timeout(Duration.ofSeconds(5))
    .retryPolicy(new JevRetryPolicy(2, Duration.ofMillis(500)))
    .build();
var request = SystemOneRequest.builder()
    .state(Map.of("answer", "Refund completed", "record", "No refund initiated"))
    .question("supported", new NoulQuestion(
        "Does the business record support the answer?", null))
    .build();
var pending = client.systemOne(request); // Mono<SystemOneResult>
var result = pending.block();            // Blocking is appropriate in a standalone CLI.
var answer = (NoulAnswer) result.answers().get("supported");
System.out.println("Probability the record supports the answer: " + answer.noul());
```

The returned number is not refund status and does not change business records. For PASS/FAIL/INCONCLUSIVE and threshold handling, use [conditional reviews](https://java.agentscope.io/dev/en/docs/harness/jev/guides/judge-api.md) rather than reimplementing the branches.

In reactive services return or compose the `Mono`; do not subscribe twice just to log the result. Keep shared state unchanged until completion. Add multiple `.question(...)` calls with distinct IDs to the same builder for multiple judgments.

## Configuration and errors

The default endpoint is `https://api.typesafe.ai`, model `jev-latest`, and per-request timeout five seconds. Without an explicit key the client tries `TYPESAFE_API_KEY`, then `JEV_API_KEY`. Setting a key does not enable middleware.

The client posts to `/v1/systemone` and retries HTTP 429, 529 and 5xx with configured backoff. Nonretryable errors, exhausted retries and invalid responses throw `JevException`. Validation covers the question set, answer types, distributions and score grades. Never invent success for a missing answer.

An HTTP timeout differs from the total budget for a logical decision. [JevExecution](https://java.agentscope.io/dev/en/docs/harness/jev/guides/harness-runtime.md), the Judge or the component bounds batches, retries and backoff together. Cancellation stops the local subscription; transport behavior determines whether the remote request is interrupted.

## Spring Boot configuration

```xml theme={null}
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-jev-spring-boot-starter</artifactId>
  <version>${agentscope.version}</version>
</dependency>
```

```yaml theme={null}
agentscope:
  jev:
    api-key: ${TYPESAFE_API_KEY:}
    model: jev-latest
    timeout: 5s
    retry:
      max-retries: 2
      initial-backoff: 500ms
```

Customize the builder with a `JevClientBuilderCustomizer` bean. The starter configures the client; register each Harness capability and select its mode explicitly.

## Compare a text model on the same questions

`JevTextBackend(model, transport)` converts a `SystemOneRequest` to a Chat Completions compatible request. Supply a `Function<String, Mono<String>>` transport that owns the endpoint, authentication, timeout and cancellation.

The adapter strictly validates JSON, questions and distributions. It does not invent missing answers or normalize invalid probabilities. Calibrate self-reported text-model probabilities separately. See the [evaluation guide](https://java.agentscope.io/dev/en/docs/harness/jev/evaluation.md) for runnable HTTP comparisons.

## Try the offline example first

The `judge` scenario in [JevApplicationScenarios](https://java.agentscope.io/examples/jev/source/JevApplicationScenarios.java.txt) demonstrates three outcomes for a similar refund evidence check. Set `JEV_CP` using the [build instructions](https://java.agentscope.io/dev/en/docs/harness/jev/guides/agent-integration-example.md#build-once-and-run-multiple-examples), then run:

```bash theme={null}
java -cp "$JEV_CP" io.agentscope.examples.jev.JevApplicationScenarios judge
```

The example injects preset probabilities and makes no HTTP calls; it does not measure model quality. The client code above does call a real endpoint and needs credentials. Handle API failures as errors; never substitute offline results for a real decision.


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