Class: RubyLLM::Agents::Result

Inherits:
Object
  • Object
show all
Extended by:
ActiveSupport::Delegation
Defined in:
lib/ruby_llm/agents/results/base.rb

Overview

Wrapper for agent execution results with full metadata

Provides access to the response content along with execution details like token usage, cost, timing, and model information.

Examples:

Basic usage

result = MyAgent.call(query: "test")
result.content        # => processed response
result.input_tokens   # => 150
result.total_cost     # => 0.00025

Backward compatible hash access

result[:key]          # delegates to result.content[:key]
result.dig(:nested, :key)

Direct Known Subclasses

RubyLLM::Agents::Routing::RoutingResult

Token Usage collapse

Cost collapse

Model Info collapse

Timing collapse

Status collapse

Error Info collapse

Reliability collapse

Tool Calls collapse

Thinking collapse

Execution Record collapse

Tracking collapse

Cancellation collapse

Debug collapse

Instance Attribute Summary collapse

Debug collapse

Deprecated Hash Delegation collapse

Instance Method Summary collapse

Constructor Details

#initialize(content:, **options) ⇒ Result

Creates a new Result instance

Parameters:

  • content (Hash, String) —

    The processed response content

  • options (Hash) —

    Execution metadata



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/ruby_llm/agents/results/base.rb', line 129

def initialize(content:, **options)
  @content = content

  # Token usage
  @input_tokens = options[:input_tokens]
  @output_tokens = options[:output_tokens]
  @cached_tokens = options[:cached_tokens] || 0
  @cache_creation_tokens = options[:cache_creation_tokens] || 0

  # Cost
  @input_cost = options[:input_cost]
  @output_cost = options[:output_cost]
  @total_cost = options[:total_cost]

  # Model info
  @model_id = options[:model_id]
  @chosen_model_id = options[:chosen_model_id] || options[:model_id]
  @temperature = options[:temperature]

  # Timing
  @started_at = options[:started_at]
  @completed_at = options[:completed_at]
  @duration_ms = options[:duration_ms]
  @time_to_first_token_ms = options[:time_to_first_token_ms]

  # Status
  @finish_reason = options[:finish_reason]
  @streaming = options[:streaming] || false

  # Error
  @error_class = options[:error_class]
  @error_message = options[:error_message]

  # Reliability
  @attempts = options[:attempts] || []
  @attempts_count = options[:attempts_count] || 1

  # Tool calls
  @tool_calls = options[:tool_calls] || []
  @tool_calls_count = options[:tool_calls_count] || 0

  # Thinking
  @thinking_text = options[:thinking_text]
  @thinking_signature = options[:thinking_signature]
  @thinking_tokens = options[:thinking_tokens]

  # Execution record
  @execution_id = options[:execution_id]

  # Tracking
  @agent_class_name = options[:agent_class_name]

  # Cancellation
  @cancelled = options[:cancelled] || false

  # Debug trace
  @trace = options[:trace]

  # Register with active tracker
  tracker = Thread.current[:ruby_llm_agents_tracker]
  tracker << self if tracker
end

Instance Attribute Details

#agent_class_name ⇒ Object (readonly) 



113
114
115
 
# File 'lib/ruby_llm/agents/results/base.rb', line 113

def agent_class_name
  @agent_class_name
end

#attempts ⇒ Array<Hash> (readonly)

Returns Details of each attempt (for retries/fallbacks).

Returns:

  • (Array<Hash>) —

    Details of each attempt (for retries/fallbacks)



87
88
89
 
# File 'lib/ruby_llm/agents/results/base.rb', line 87

def attempts
  @attempts
end

#attempts_count ⇒ Object (readonly) 



87
 
# File 'lib/ruby_llm/agents/results/base.rb', line 87

attr_reader :attempts, :attempts_count

#cache_creation_tokens ⇒ Object (readonly) 



37
 
# File 'lib/ruby_llm/agents/results/base.rb', line 37

attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_creation_tokens

#cached_tokens ⇒ Integer (readonly)

Returns Number of tokens served from cache.

Returns:

  • (Integer) —

    Number of tokens served from cache



37
 
# File 'lib/ruby_llm/agents/results/base.rb', line 37

attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_creation_tokens

#cancelled ⇒ Object (readonly) 



118
119
120
 
# File 'lib/ruby_llm/agents/results/base.rb', line 118

def cancelled
  @cancelled
end

#chosen_model_id ⇒ String? (readonly)

Returns The model that actually responded (may differ if fallback used).

Returns:

  • (String, nil) —

    The model that actually responded (may differ if fallback used)



55
 
# File 'lib/ruby_llm/agents/results/base.rb', line 55

attr_reader :model_id, :chosen_model_id, :temperature

#completed_at ⇒ Time? (readonly)

Returns When execution completed.

Returns:

  • (Time, nil) —

    When execution completed



66
 
# File 'lib/ruby_llm/agents/results/base.rb', line 66

attr_reader :started_at, :completed_at, :duration_ms, :time_to_first_token_ms

#content ⇒ Object (readonly) 



26
27
28
 
# File 'lib/ruby_llm/agents/results/base.rb', line 26

def content
  @content
end

#duration_ms ⇒ Integer? (readonly)

Returns Execution duration in milliseconds.

Returns:

  • (Integer, nil) —

    Execution duration in milliseconds



66
 
# File 'lib/ruby_llm/agents/results/base.rb', line 66

attr_reader :started_at, :completed_at, :duration_ms, :time_to_first_token_ms

#error_class ⇒ String? (readonly)

Returns Exception class name if failed.

Returns:

  • (String, nil) —

    Exception class name if failed



80
81
82
 
# File 'lib/ruby_llm/agents/results/base.rb', line 80

def error_class
  @error_class
end

#error_message ⇒ Object (readonly) 



80
 
# File 'lib/ruby_llm/agents/results/base.rb', line 80

attr_reader :error_class, :error_message

#execution_id ⇒ Object (readonly) 



108
109
110
 
# File 'lib/ruby_llm/agents/results/base.rb', line 108

def execution_id
  @execution_id
end

#finish_reason ⇒ String? (readonly)

Returns Why generation stopped (stop, length, tool_calls, etc.).

Returns:

  • (String, nil) —

    Why generation stopped (stop, length, tool_calls, etc.)



73
74
75
 
# File 'lib/ruby_llm/agents/results/base.rb', line 73

def finish_reason
  @finish_reason
end

#input_cost ⇒ Float? (readonly)

Returns Cost of input tokens in USD.

Returns:

  • (Float, nil) —

    Cost of input tokens in USD



46
47
48
 
# File 'lib/ruby_llm/agents/results/base.rb', line 46

def input_cost
  @input_cost
end

#input_tokens ⇒ Integer? (readonly)

Returns Number of input tokens consumed.

Returns:

  • (Integer, nil) —

    Number of input tokens consumed



37
38
39
 
# File 'lib/ruby_llm/agents/results/base.rb', line 37

def input_tokens
  @input_tokens
end

#model_id ⇒ String? (readonly)

Returns The model that was requested.

Returns:

  • (String, nil) —

    The model that was requested



55
56
57
 
# File 'lib/ruby_llm/agents/results/base.rb', line 55

def model_id
  @model_id
end

#output_cost ⇒ Float? (readonly)

Returns Cost of output tokens in USD.

Returns:

  • (Float, nil) —

    Cost of output tokens in USD



46
 
# File 'lib/ruby_llm/agents/results/base.rb', line 46

attr_reader :input_cost, :output_cost, :total_cost

#output_tokens ⇒ Integer? (readonly)

Returns Number of output tokens generated.

Returns:

  • (Integer, nil) —

    Number of output tokens generated



37
 
# File 'lib/ruby_llm/agents/results/base.rb', line 37

attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_creation_tokens

#started_at ⇒ Time? (readonly)

Returns When execution started.

Returns:

  • (Time, nil) —

    When execution started



66
67
68
 
# File 'lib/ruby_llm/agents/results/base.rb', line 66

def started_at
  @started_at
end

#streaming ⇒ Object (readonly) 



73
 
# File 'lib/ruby_llm/agents/results/base.rb', line 73

attr_reader :finish_reason, :streaming

#temperature ⇒ Object (readonly) 



55
 
# File 'lib/ruby_llm/agents/results/base.rb', line 55

attr_reader :model_id, :chosen_model_id, :temperature

#thinking_signature ⇒ String? (readonly)

Returns Signature for multi-turn thinking continuity (Claude).

Returns:

  • (String, nil) —

    Signature for multi-turn thinking continuity (Claude)



103
 
# File 'lib/ruby_llm/agents/results/base.rb', line 103

attr_reader :thinking_text, :thinking_signature, :thinking_tokens

#thinking_text ⇒ String? (readonly)

Returns The reasoning/thinking content from the model.

Returns:

  • (String, nil) —

    The reasoning/thinking content from the model



103
104
105
 
# File 'lib/ruby_llm/agents/results/base.rb', line 103

def thinking_text
  @thinking_text
end

#thinking_tokens ⇒ Object (readonly) 



103
 
# File 'lib/ruby_llm/agents/results/base.rb', line 103

attr_reader :thinking_text, :thinking_signature, :thinking_tokens

#time_to_first_token_ms ⇒ Object (readonly) 



66
 
# File 'lib/ruby_llm/agents/results/base.rb', line 66

attr_reader :started_at, :completed_at, :duration_ms, :time_to_first_token_ms

#tool_calls ⇒ Array<Hash> (readonly)

Returns Tool calls made during execution.

Returns:

  • (Array<Hash>) —

    Tool calls made during execution



94
95
96
 
# File 'lib/ruby_llm/agents/results/base.rb', line 94

def tool_calls
  @tool_calls
end

#tool_calls_count ⇒ Object (readonly) 



94
 
# File 'lib/ruby_llm/agents/results/base.rb', line 94

attr_reader :tool_calls, :tool_calls_count

#total_cost ⇒ Object (readonly) 



46
 
# File 'lib/ruby_llm/agents/results/base.rb', line 46

attr_reader :input_cost, :output_cost, :total_cost

#trace ⇒ Object (readonly) 



123
124
125
 
# File 'lib/ruby_llm/agents/results/base.rb', line 123

def trace
  @trace
end

Instance Method Details

#[](key) ⇒ Object

Deprecated.

Use result.content instead



326
327
328
329
330
331
332
 
# File 'lib/ruby_llm/agents/results/base.rb', line 326

def [](key)
  RubyLLM::Agents::Deprecations.warn(
    "Result#[] is deprecated. Use result.content[:key] instead.",
    caller
  )
  content&.[](key)
end

#cancelled? ⇒ Boolean

Returns whether the execution was cancelled

Returns:

  • (Boolean) —

    true if cancelled



236
237
238
 
# File 'lib/ruby_llm/agents/results/base.rb', line 236

def cancelled?
  cancelled == true
end

#dig(*keys) ⇒ Object

Deprecated.

Use result.content.dig(…) instead



335
336
337
338
339
340
341
 
# File 'lib/ruby_llm/agents/results/base.rb', line 335

def dig(*keys)
  RubyLLM::Agents::Deprecations.warn(
    "Result#dig is deprecated. Use result.content.dig(...) instead.",
    caller
  )
  content&.dig(*keys)
end

#each(&block) ⇒ Object

Deprecated.

Use result.content.each instead



362
363
364
365
366
367
368
 
# File 'lib/ruby_llm/agents/results/base.rb', line 362

def each(&block)
  RubyLLM::Agents::Deprecations.warn(
    "Result#each is deprecated. Use result.content.each instead.",
    caller
  )
  content&.each(&block)
end

#error? ⇒ Boolean

Returns whether the execution failed

Returns:

  • (Boolean) —

    true if an error occurred



229
230
231
 
# File 'lib/ruby_llm/agents/results/base.rb', line 229

def error?
  !success?
end

#execution ⇒ RubyLLM::Agents::Execution?

Loads the associated Execution record from the database

Useful for debugging in the Rails console to inspect the full execution record after an agent call.

Examples:

result = MyAgent.call(query: "test")
result.execution  # => #<RubyLLM::Agents::Execution id: 42, ...>

Returns:



201
202
203
 
# File 'lib/ruby_llm/agents/results/base.rb', line 201

def execution
  @execution ||= Execution.find_by(id: execution_id) if execution_id
end

#keys ⇒ Object

Deprecated.

Use result.content.keys instead



344
345
346
347
348
349
350
 
# File 'lib/ruby_llm/agents/results/base.rb', line 344

def keys
  RubyLLM::Agents::Deprecations.warn(
    "Result#keys is deprecated. Use result.content.keys instead.",
    caller
  )
  content&.keys
end

#map(&block) ⇒ Object

Deprecated.

Use result.content.map instead



371
372
373
374
375
376
377
 
# File 'lib/ruby_llm/agents/results/base.rb', line 371

def map(&block)
  RubyLLM::Agents::Deprecations.warn(
    "Result#map is deprecated. Use result.content.map instead.",
    caller
  )
  content&.map(&block)
end

#streaming? ⇒ Boolean

Returns whether streaming was enabled

Returns:

  • (Boolean) —

    true if streaming was used



215
216
217
 
# File 'lib/ruby_llm/agents/results/base.rb', line 215

def streaming?
  streaming == true
end

#success? ⇒ Boolean

Returns whether the execution succeeded

Returns:

  • (Boolean) —

    true if no error occurred



222
223
224
 
# File 'lib/ruby_llm/agents/results/base.rb', line 222

def success?
  error_class.nil?
end

#thinking? ⇒ Boolean Also known as: has_thinking?

Returns whether thinking data is present in the result

Returns:

  • (Boolean) —

    true if thinking_text is present



265
266
267
 
# File 'lib/ruby_llm/agents/results/base.rb', line 265

def thinking?
  thinking_text.present?
end

#to_h ⇒ Hash

Converts the result to a hash

Returns:

  • (Hash) —

    All result data as a hash



273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/ruby_llm/agents/results/base.rb', line 273

def to_h
  {
    content: content,
    input_tokens: input_tokens,
    output_tokens: output_tokens,
    total_tokens: total_tokens,
    cached_tokens: cached_tokens,
    cache_creation_tokens: cache_creation_tokens,
    input_cost: input_cost,
    output_cost: output_cost,
    total_cost: total_cost,
    model_id: model_id,
    chosen_model_id: chosen_model_id,
    temperature: temperature,
    started_at: started_at,
    completed_at: completed_at,
    duration_ms: duration_ms,
    time_to_first_token_ms: time_to_first_token_ms,
    finish_reason: finish_reason,
    streaming: streaming,
    error_class: error_class,
    error_message: error_message,
    attempts_count: attempts_count,
    attempts: attempts,
    tool_calls: tool_calls,
    tool_calls_count: tool_calls_count,
    thinking_text: thinking_text,
    thinking_signature: thinking_signature,
    thinking_tokens: thinking_tokens,
    execution_id: execution_id,
    agent_class_name: agent_class_name,
    trace: trace
  }.compact
end

#to_json(*args) ⇒ String

Custom to_json that returns content as JSON for backward compatibility

Parameters:

  • args (Array) —

    Arguments passed to to_json

Returns:

  • (String) —

    JSON representation



385
386
387
 
# File 'lib/ruby_llm/agents/results/base.rb', line 385

def to_json(*args)
  content.to_json(*args)
end

#tool_calls? ⇒ Boolean Also known as: has_tool_calls?

Returns whether tool calls were made during execution

Returns:

  • (Boolean) —

    true if tool_calls_count > 0



257
258
259
 
# File 'lib/ruby_llm/agents/results/base.rb', line 257

def tool_calls?
  tool_calls_count.to_i > 0
end

#total_tokens ⇒ Integer

Returns total tokens (input + output)

Returns:

  • (Integer) —

    Total token count



208
209
210
 
# File 'lib/ruby_llm/agents/results/base.rb', line 208

def total_tokens
  (input_tokens || 0) + (output_tokens || 0)
end

#truncated? ⇒ Boolean

Returns whether the response was truncated due to max tokens

Returns:

  • (Boolean) —

    true if finish_reason is “length”



250
251
252
 
# File 'lib/ruby_llm/agents/results/base.rb', line 250

def truncated?
  finish_reason == "length"
end

#used_fallback? ⇒ Boolean

Returns whether a fallback model was used

Returns:

  • (Boolean) —

    true if chosen_model_id differs from model_id



243
244
245
 
# File 'lib/ruby_llm/agents/results/base.rb', line 243

def used_fallback?
  chosen_model_id.present? && chosen_model_id != model_id
end

#values ⇒ Object

Deprecated.

Use result.content.values instead



353
354
355
356
357
358
359
 
# File 'lib/ruby_llm/agents/results/base.rb', line 353

def values
  RubyLLM::Agents::Deprecations.warn(
    "Result#values is deprecated. Use result.content.values instead.",
    caller
  )
  content&.values
end