Package com.tnsai.agents.resilience

Class AgentResilienceManager

java.lang.Object
com.tnsai.agents.resilience.AgentResilienceManager
public class AgentResilienceManager extends Object
Facade for agent resilience operations.

The AgentResilienceManager provides a unified interface for all resilience concerns including:

  • Retry policies with exponential backoff
  • Circuit breaker pattern for failure isolation
  • Dead letter queue for failed operations
  • Health state tracking
  • Recovery decisions (degrade, restart, fallback)
  • State snapshots for crash recovery

Note for harness auditors (see tnsai-core/agent_docs/harness-audit.md): this facade is intentionally not tagged with @modelAssumption. The patterns it implements (exponential backoff, circuit-breaker with half-open state, dead-letter queue, fail-fast on budget exhaustion) are timeless network-engineering primitives, not LLM-version workarounds. Provider-specific tuning (e.g. retry-on-503 thresholds for a particular LLM API) lives in the RetryPolicy instances passed in, which are where any model-version annotations belong.

Usage


 AgentResilienceManager resilience = AgentResilienceManager.builder()
     .agentId("agent-1")
     .retryPolicy(RetryPolicy.defaultPolicy())
     .restartPolicy(AgentRestartPolicy.defaultPolicy())
     .build();

 // Execute with resilience
 String result = resilience.execute("search", () -> {
     return searchService.search(query);
 });

 // Check health
 if (resilience.getHealthState() == AgentHealthState.DEGRADED) {
     // Handle degraded mode
 }
Author:
TnsAI Team
See Also:

  • Method Details

    • builder

      public static AgentResilienceManager.Builder builder()
      Creates a new builder for AgentResilienceManager.
      Returns:
      new builder instance

    • execute

      public <T> T execute(String operationId, Callable<T> operation) throws Exception
      Executes an operation with full resilience (retry + circuit breaker + fallback).
      Type Parameters:
      T - return type
      Parameters:
      operationId - unique identifier for the operation
      operation - the operation to execute
      Returns:
      operation result
      Throws:
      Exception - if operation fails after retries and no fallback

    • execute

      public <T> T execute(String operationId, Callable<T> operation, RetryPolicy retryPolicy) throws Exception
      Executes an operation with custom retry policy.
      Type Parameters:
      T - return type
      Parameters:
      operationId - unique identifier for the operation
      operation - the operation to execute
      retryPolicy - custom retry policy
      Returns:
      operation result
      Throws:
      Exception - if operation fails after retries

    • execute

      public <T> T execute(String operationId, Callable<T> operation, RetryPolicy retryPolicy, FallbackStrategy<T> fallback) throws Exception
      Executes an operation with full resilience configuration.
      Type Parameters:
      T - return type
      Parameters:
      operationId - unique identifier for the operation
      operation - the operation to execute
      retryPolicy - retry policy to use
      fallback - fallback strategy if operation fails
      Returns:
      operation result
      Throws:
      Exception - if operation fails after retries and fallback

    • getHealthState

      public AgentHealthState getHealthState()
      Returns the current health state.
      Returns:
      current health state

    • setHealthState

      public void setHealthState(AgentHealthState state)
      Sets the health state.
      Parameters:
      state - new health state

    • isHealthy

      public boolean isHealthy()
      Checks if the agent is healthy.
      Returns:
      true if healthy

    • isDegraded

      public boolean isDegraded()
      Checks if the agent is in degraded mode.
      Returns:
      true if degraded

    • onSuccess

      public void onSuccess()
      Handles a successful operation.

    • handleFailure

      public RecoveryDecision handleFailure(String actionName, Exception exception)
      Handles a failed operation and determines recovery action.
      Parameters:
      actionName - name of the failed action
      exception - the exception that occurred
      Returns:
      recovery decision

    • isInCooldown

      public boolean isInCooldown()
      Checks if the agent is in cooldown period after failures.
      Returns:
      true if in cooldown

    • captureSnapshot

      public void captureSnapshot(MemoryStore memoryStore)
      Captures a state snapshot from the memory store.
      Parameters:
      memoryStore - the memory store to snapshot

    • restoreLatestSnapshot

      public void restoreLatestSnapshot(MemoryStore memoryStore)
      Restores the latest snapshot to the memory store.
      Parameters:
      memoryStore - the memory store to restore to

    • clearSnapshots

      public void clearSnapshots()
      Clears all snapshots.

    • getDeadLetterQueue

      public DeadLetterQueue getDeadLetterQueue()
      Returns the dead letter queue for failed operations.
      Returns:
      dead letter queue

    • getFailedOperationCount

      public int getFailedOperationCount()
      Returns the count of failed operations in DLQ.
      Returns:
      failed operation count

    • getDefaultRetryPolicy

      public RetryPolicy getDefaultRetryPolicy()
      Returns the default retry policy.
      Returns:
      default retry policy

    • getResilienceExecutor

      public ResilienceExecutor getResilienceExecutor()
      Returns the resilience executor.
      Returns:
      resilience executor

    • getRecoveryManager

      public AgentRecoveryManager getRecoveryManager()
      Returns the recovery manager.
      Returns:
      recovery manager

    • getStateRecoveryManager

      public AgentStateRecoveryManager getStateRecoveryManager()
      Returns the state recovery manager.
      Returns:
      state recovery manager