CtrlK

Community Documentation Log in Get started

tessl/maven-com-embabel-agent--embabel-agent-starter

Base starter module for the Embabel Agent Framework providing core dependencies for building agentic flows on the JVM with Spring Boot integration and GOAP-based intelligent path finding.

Overview

Eval results

Files

Resilience Configuration Reference

Name: tessl/maven-com-embabel-agent--embabel-agent-starter
Author: tessl

Complete reference for retry policies, backoff strategies, and resilience patterns.

Retry Configuration Properties

Anthropic Provider

Property	Type	Default	Description
`embabel.agent.platform.models.anthropic.max-attempts`	int	`10`	Maximum retry attempts
`embabel.agent.platform.models.anthropic.backoff-millis`	long	`5000`	Initial backoff in milliseconds
`embabel.agent.platform.models.anthropic.backoff-multiplier`	double	`5.0`	Backoff multiplier
`embabel.agent.platform.models.anthropic.backoff-max-interval`	long	`180000`	Maximum backoff interval (ms)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 10
          backoff-millis: 5000
          backoff-multiplier: 5.0
          backoff-max-interval: 180000

Backoff calculation:

Delay = min(backoff-millis * (backoff-multiplier ^ attempt), backoff-max-interval)

Example retry sequence:

Attempt 1: 5000ms (5 seconds)
Attempt 2: 25000ms (25 seconds)
Attempt 3: 125000ms (125 seconds)
Attempt 4+: 180000ms (180 seconds, capped)

OpenAI Provider

Property	Type	Default	Description
`embabel.agent.platform.models.openai.max-attempts`	int	`10`	Maximum retry attempts
`embabel.agent.platform.models.openai.backoff-millis`	long	`5000`	Initial backoff in milliseconds
`embabel.agent.platform.models.openai.backoff-multiplier`	double	`5.0`	Backoff multiplier
`embabel.agent.platform.models.openai.backoff-max-interval`	long	`180000`	Maximum backoff interval (ms)

embabel:
  agent:
    platform:
      models:
        openai:
          max-attempts: 10
          backoff-millis: 5000
          backoff-multiplier: 5.0
          backoff-max-interval: 180000

Ranking Operations

Property	Type	Default	Description
`embabel.agent.platform.ranking.max-attempts`	int	`5`	Maximum ranking attempts
`embabel.agent.platform.ranking.backoff-millis`	long	`100`	Initial backoff in milliseconds
`embabel.agent.platform.ranking.backoff-multiplier`	double	`5.0`	Backoff multiplier
`embabel.agent.platform.ranking.backoff-max-interval`	long	`180000`	Maximum backoff interval (ms)

embabel:
  agent:
    platform:
      ranking:
        max-attempts: 5
        backoff-millis: 100
        backoff-multiplier: 5.0
        backoff-max-interval: 180000

Data Binding Operations

Property	Type	Default	Description
`embabel.agent.platform.llm-operations.data-binding.max-attempts`	int	`10`	Maximum data binding attempts
`embabel.agent.platform.llm-operations.data-binding.fixed-backoff-millis`	long	`30`	Fixed backoff in milliseconds

embabel:
  agent:
    platform:
      llm-operations:
        data-binding:
          max-attempts: 10
          fixed-backoff-millis: 30

Note: Data binding uses fixed backoff (not exponential).

Configuration Presets

Conservative (Production)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000
        openai:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000
      ranking:
        max-attempts: 10
        backoff-millis: 200
      llm-operations:
        data-binding:
          max-attempts: 15

Use case: Production environments requiring high reliability.

Retry sequence (Anthropic/OpenAI):

10s, 20s, 40s, 80s, 160s, 300s, 300s, ...

Aggressive (Development)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 3
          backoff-millis: 1000
          backoff-multiplier: 2.0
          backoff-max-interval: 30000
        openai:
          max-attempts: 3
          backoff-millis: 1000
          backoff-multiplier: 2.0
          backoff-max-interval: 30000
      ranking:
        max-attempts: 2
        backoff-millis: 50
      llm-operations:
        data-binding:
          max-attempts: 5

Use case: Development environments preferring fast failure feedback.

Retry sequence (Anthropic/OpenAI):

1s, 2s, 4s

No Retry (Testing)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 1
          backoff-millis: 0
          backoff-multiplier: 1.0
          backoff-max-interval: 0
        openai:
          max-attempts: 1
          backoff-millis: 0
          backoff-multiplier: 1.0
          backoff-max-interval: 0
      ranking:
        max-attempts: 1
      llm-operations:
        data-binding:
          max-attempts: 1

Use case: Testing environments requiring immediate failures.

Timeout Configuration

MCP Client Timeout

Property	Type	Default	Description
`spring.ai.mcp.client.request-timeout`	Duration	`30s`	Request timeout duration

spring:
  ai:
    mcp:
      client:
        request-timeout: 30s

Supported formats:

30s - 30 seconds
1m - 1 minute
5m30s - 5 minutes 30 seconds
PT30S - ISO-8601 duration

Backoff Strategies

Exponential Backoff

delay(attempt) = min(initial * (multiplier ^ attempt), maxInterval)

Configuration:

backoff-millis: 1000
backoff-multiplier: 2.0
backoff-max-interval: 60000

Sequence: 1s, 2s, 4s, 8s, 16s, 32s, 60s, 60s, ...

Advantages:

Reduces load on failing services
Increases success probability over time
Prevents thundering herd problem

Fixed Backoff

delay(attempt) = fixed-backoff-millis

Configuration:

fixed-backoff-millis: 30

Sequence: 30ms, 30ms, 30ms, ...

Advantages:

Predictable retry timing
Suitable for fast operations
Simple to reason about

Failure Classification

Transient Failures (Retryable)

Network timeouts
HTTP 429 (Rate Limit)
HTTP 500, 502, 503, 504 (Server Errors)
Connection refused
Read timeout

Permanent Failures (Not Retryable)

HTTP 400 (Bad Request)
HTTP 401 (Unauthorized)
HTTP 403 (Forbidden)
Invalid API key
Malformed request

Environment-Specific Configuration

Development (application-dev.yml)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 3
          backoff-millis: 1000
          backoff-multiplier: 2.0
          backoff-max-interval: 30000
        openai:
          max-attempts: 3
          backoff-millis: 1000
          backoff-multiplier: 2.0
          backoff-max-interval: 30000

spring:
  ai:
    mcp:
      client:
        request-timeout: 10s

Production (application-prod.yml)

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000
        openai:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000

spring:
  ai:
    mcp:
      client:
        request-timeout: 60s

Activate with:

export SPRING_PROFILES_ACTIVE=prod
# or
java -jar app.jar --spring.profiles.active=prod

Retry Property Types

RetryProperties Class

public class RetryProperties {
    private int maxAttempts;
    private long backoffMillis;
    private double backoffMultiplier;
    private long backoffMaxInterval;

    // Getters and setters
}

Property Validation

Property	Valid Range	Notes
`max-attempts`	1 - Integer.MAX_VALUE	1 = no retries
`backoff-millis`	0 - Long.MAX_VALUE	0 = no delay
`backoff-multiplier`	1.0 - Double.MAX_VALUE	1.0 = linear
`backoff-max-interval`	0 - Long.MAX_VALUE	0 = no cap

Monitoring Retry Behavior

Enable Debug Logging

logging:
  level:
    com.embabel.agent: DEBUG

Example output:

DEBUG: Attempt 1/10 failed for Anthropic API call, retrying in 5000ms
DEBUG: Attempt 2/10 failed for Anthropic API call, retrying in 25000ms
INFO: Anthropic API call succeeded on attempt 3/10

Custom Metrics Example

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;

@Component
public class RetryMetrics implements AgenticEventListener {
    private final Counter retryCounter;
    private final Counter failureCounter;

    public RetryMetrics(MeterRegistry registry) {
        this.retryCounter = Counter.builder("embabel.agent.retries")
            .description("Number of retry attempts")
            .register(registry);

        this.failureCounter = Counter.builder("embabel.agent.failures")
            .description("Number of permanent failures")
            .register(registry);
    }

    @Override
    public void onEvent(AgenticEvent event) {
        if (event instanceof RetryEvent) {
            retryCounter.increment();
        } else if (event instanceof FailureEvent) {
            failureCounter.increment();
        }
    }
}

Error Handling

Retry Exhaustion

try {
    Result result = aiService.generateResponse(prompt);
} catch (RetryExhaustedException e) {
    logger.error("All retry attempts exhausted", e);
    // Handle failure
}

Stream Error Recovery

@Action
public void streamWithErrorHandling(String prompt) {
    try {
        streaming.stream(token -> {
            try {
                processToken(token);
            } catch (Exception e) {
                logger.error("Error processing token: {}", token, e);
            }
        });
    } catch (StreamingException e) {
        logger.error("Streaming failed", e);
    }
}

Complete Configuration Example

# Production-ready resilience configuration
spring:
  ai:
    mcp:
      client:
        request-timeout: 60s

embabel:
  agent:
    platform:
      models:
        anthropic:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000
        openai:
          max-attempts: 15
          backoff-millis: 10000
          backoff-multiplier: 2.0
          backoff-max-interval: 300000
      ranking:
        max-attempts: 10
        backoff-millis: 200
        backoff-multiplier: 5.0
        backoff-max-interval: 180000
      llm-operations:
        data-binding:
          max-attempts: 15
          fixed-backoff-millis: 50

logging:
  level:
    com.embabel.agent: INFO

tessl i tessl/maven-com-embabel-agent--embabel-agent-starter@0.3.1