Class: Observ::AgentExecutorService

Inherits:
Object
  • Object
show all
Defined in:
app/services/observ/agent_executor_service.rb

Overview

Generic service for executing any agent against an input

This service encapsulates the RubyLLM chat configuration and execution pattern, providing a unified way to run agents for dataset evaluations or other purposes.

The service:

  • Creates a RubyLLM chat with the agent's model
  • Applies system prompt, schema, and model parameters
  • Optionally instruments the chat for observability
  • Handles both simple text input and structured context hashes

Usage:

# Basic usage
executor = Observ::AgentExecutorService.new(LanguageDetectionAgent)
result = executor.call("Hello, how are you?")

# With observability
session = Observ::Session.create!(user_id: "user_123")
executor = Observ::AgentExecutorService.new(
LanguageDetectionAgent,
observability_session: session
)
result = executor.call("Bonjour!")

# With context hash (for agents that implement build_user_prompt)
executor = Observ::AgentExecutorService.new(CharacterGeneratorAgent)
result = executor.call(genre: "fantasy", title: "Dragon Quest")

Defined Under Namespace

Classes: ExecutionError, RubyLLMNotAvailableError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(agent_class, observability_session: nil, context: {}) ⇒ AgentExecutorService

Initialize the executor

Parameters:

  • agent_class (Class) —

    The agent class to execute (must respond to model, system_prompt)

  • observability_session (Observ::Session, nil) (defaults to: nil) —

    Optional session for tracing

  • context (Hash) (defaults to: {}) —

    Additional context metadata for tracing



43
44
45
46
47
48
49
50
 
# File 'app/services/observ/agent_executor_service.rb', line 43

def initialize(agent_class, observability_session: nil, context: {})
  @agent_class = agent_class
  @observability_session = observability_session
  @context = context

  validate_ruby_llm_available!
  validate_agent_class!
end

Instance Attribute Details

#agent_class ⇒ Object (readonly)

Returns the value of attribute agent_class.



36
37
38
 
# File 'app/services/observ/agent_executor_service.rb', line 36

def agent_class
  @agent_class
end

#observability_session ⇒ Object (readonly)

Returns the value of attribute observability_session.



36
37
38
 
# File 'app/services/observ/agent_executor_service.rb', line 36

def observability_session
  @observability_session
end

Instance Method Details

#call(input) ⇒ Hash, String

Execute the agent with the given input

Parameters:

  • input (String, Hash) —

    The input text or context hash

Returns:

  • (Hash, String) —

    The agent's response (structured if schema defined, string otherwise)

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'app/services/observ/agent_executor_service.rb', line 57

def call(input)
  chat = build_chat
  configure_chat(chat)
  instrument_chat(chat) if observability_session

  user_prompt = build_user_prompt(input)
  response = chat.ask(user_prompt)

  normalize_response(response.content)
rescue StandardError => e
  raise ExecutionError, "Agent execution failed: #{e.message}"
end