# How to Configure Confidence Thresholds for Embabel Agents: A Complete Guide

> Learn to configure confidence thresholds for Embabel agents using YAML, JVM properties, or environment variables. Master this key Embabel setting for optimal agent performance.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Embabel agents use the `embabel.ranking.confidence_cutoff` property to filter ranking results, which you can set via YAML configuration, JVM system properties, or environment variables.**

Configuring confidence thresholds for Embabel agents ensures that only high-quality ranking results trigger actions within your system. In the `embabel/embabel-agent` repository, this threshold is controlled through a centralized configuration key defined in the observability module. Understanding how to adjust this value allows you to balance precision and recall based on your specific domain requirements.

## Understanding the Confidence Cutoff Configuration

The **confidence cutoff** acts as a gatekeeper for ranking decisions. When an Embabel agent generates a ranking result, it calculates a confidence score between 0.0 and 1.0. If this score falls below the configured threshold, the result is discarded or triggers a fallback mechanism.

At the core of this system is the `EMBABEL_RANKING_CONFIDENCE_CUTOFF` constant. This string holds the configuration key `embabel.ranking.confidence_cutoff` and is used both for property lookup and as a trace attribute key in the observability stack.

## Configuration Methods

You can specify the confidence threshold through three mechanisms, listed in order of precedence:

### Application Configuration File (YAML/Properties)

The most common approach is setting the value in your [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) or `application.properties` file:

```yaml
embabel:
  ranking:
    confidence_cutoff: 0.75

```

### JVM System Properties

Override the configuration at startup using the `-D` flag:

```bash
java -Dembabel.ranking.confidence_cutoff=0.8 -jar embabel-agent.jar

```

### Environment Variables

For containerized deployments, use the Spring Boot-style environment variable:

```bash
export EMBABEL_RANKING_CONFIDENCE_CUTOFF=0.65

```

## Implementation Details in Source Code

The configuration key is defined as a constant in the observability module. In [`embabel-agent-observability/src/main/java/com/embabel/agent/observability/SpanAttributes.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-observability/src/main/java/com/embabel/agent/observability/SpanAttributes.java), you will find:

```java
public static final String EMBABEL_RANKING_CONFIDENCE_CUTOFF = "embabel.ranking.confidence_cutoff";

```

This constant serves dual purposes. First, it identifies the property key used during configuration loading. Second, when a ranking is produced, the confidence value is attached to the trace span under this attribute name, enabling filtering and alerting in observability tools according to the `embabel/embabel-agent` source code.

## Practical Code Examples

### Validating Confidence in Java

When implementing threshold checks in your agent logic, reference the constant directly from `SpanAttributes`:

```java
double confidence = rankingResult.getConfidence();
double cutoff = Double.parseDouble(
    env.getProperty(SpanAttributes.EMBABEL_RANKING_CONFIDENCE_CUTOFF, "0.7")
);

if (confidence < cutoff) {
    throw new LowConfidenceException("Confidence " + confidence + " below threshold " + cutoff);
}

```

### Kotlin Implementation with Logging

For Kotlin-based agents, the configuration follows the same pattern:

```kotlin
val cutoff = env.getProperty("embabel.ranking.confidence_cutoff", "0.7").toDouble()
if (ranking.confidence < cutoff) {
    logger.warn("Low confidence (${ranking.confidence}) – dropping result")
    // Implement fallback logic here
}

```

### Docker Compose Configuration

Deploy agents with specific thresholds using environment variables:

```yaml
services:
  embabel-agent:
    image: embabel/embabel-agent:latest
    environment:
      EMBABEL_RANKING_CONFIDENCE_CUTOFF: "0.85"

```

## Summary

- The confidence threshold is controlled by the `embabel.ranking.confidence_cutoff` property
- Configuration can be provided via YAML files, JVM system properties, or environment variables
- The constant `EMBABEL_RANKING_CONFIDENCE_CUTOFF` in [`SpanAttributes.java`](https://github.com/embabel/embabel-agent/blob/main/SpanAttributes.java) defines the key used for both configuration and tracing
- Values below the threshold result in discarded rankings or fallback behavior
- The threshold value is recorded in observability traces for monitoring and debugging

## Frequently Asked Questions

### What is the default value for the confidence threshold?

If not explicitly configured, the agent typically defaults to 0.7 (70%), though you should verify this in your specific version by checking the fallback value in the configuration loader or the test specifications in [`embabel-agent-observability/src/test/java/com/embabel/agent/observability/tracing/EmbabelSpanEventListenerTest.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-observability/src/test/java/com/embabel/agent/observability/tracing/EmbabelSpanEventListenerTest.java).

### How does the confidence cutoff affect agent behavior?

When a ranking result's confidence score falls below the threshold, the agent either discards the result entirely or executes a predefined fallback strategy. This prevents low-quality recommendations from propagating through your system while maintaining observability through tagged traces.

### Can I configure different thresholds for different agent instances?

Yes, since the configuration is resolved per instance at runtime, you can deploy multiple agent instances with distinct `EMBABEL_RANKING_CONFIDENCE_CUTOFF` environment variables or separate configuration profiles. This allows fine-grained control over precision requirements across different deployment contexts.

### Where is the confidence threshold stored in observability traces?

According to the source code in [`SpanAttributes.java`](https://github.com/embabel/embabel-agent/blob/main/SpanAttributes.java), the confidence values are attached to trace spans using the attribute key `embabel.ranking.confidence_cutoff`. This enables you to filter spans and set up alerts for low-confidence events in your observability platform.