Module: ActiveAgent::Providers::ExceptionHandler

Extended by:
ActiveSupport::Concern
Included in:
BaseProvider
Defined in:
lib/active_agent/providers/concerns/exception_handler.rb

Overview

Provides exception handling for provider operations.

This concern implements basic exception handling that allows agents to define custom error handling logic via rescue_from callbacks. The actual retry logic is now handled by the underlying provider gems (ruby-openai, anthropic-rb, etc.) which provide their own retry mechanisms.

Examples:

Using exception handler

class MyProvider
  include ActiveAgent::Providers::ExceptionHandler

  def call
    with_exception_handling do
      # API call that may fail
    end
  end
end

Agent-level error handling

class MyAgent < ActiveAgent::Base
  rescue_from SomeError do |exception|
    # Handle the error
  end
end

Instance Method Summary collapse

Instance Method Details

#configure_exception_handler(exception_handler: nil) ⇒ void

This method returns an undefined value.

Configures instance-level exception handling.

Parameters:

  • exception_handler (Proc, nil) (defaults to: nil) —

    callback for handling exceptions



44
45
46
 
# File 'lib/active_agent/providers/concerns/exception_handler.rb', line 44

def configure_exception_handler(exception_handler: nil)
  self.exception_handler = exception_handler
end

#rescue_with_handler(exception) ⇒ Object?

Bubbles up exceptions to the Agent's rescue_from if a handler is defined.

This method delegates exception handling to the configured exception handler, allowing agents to define custom error handling logic.

Parameters:

  • exception (StandardError) —

    The exception to handle

Returns:

  • (Object, nil) —

    Result from the exception handler, or nil if no handler



79
80
81
 
# File 'lib/active_agent/providers/concerns/exception_handler.rb', line 79

def rescue_with_handler(exception)
  exception_handler&.call(exception)
end

#with_exception_handling { ... } ⇒ Object

Executes a block with exception handling.

Examples:

Basic usage

with_exception_handling { api_call }

Yields:

  • Block to execute with exception protection

Returns:

  • (Object) —

    The result of the block execution

Raises:

  • (StandardError) —

    Any unhandled exception from the block



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/active_agent/providers/concerns/exception_handler.rb', line 56

def with_exception_handling(&block)
  yield
rescue => exception
  # Vendor API failures are normalized into the framework taxonomy
  # (Errors::RateLimited, Errors::ContextLengthExceeded, ...) so
  # rescue_from policy is portable across providers; the original
  # exception is preserved as #cause. Anything unrecognizable —
  # including ordinary Ruby errors — passes through untouched.
  exception = Errors::Taxonomy.normalize(
    exception,
    provider_tag: (tag_name if respond_to?(:tag_name))
  )
  rescue_with_handler(exception) || raise(exception)
  nil # Discard handler return value to prevent polluting raw_response
end