Class: RubyPi::Agent::Result

Inherits:
Object
  • Object
show all
Defined in:
lib/ruby_pi/agent/result.rb

Overview

Value object returned by Agent::Core#run and Agent::Core#continue. Captures everything about the completed agent interaction in a single, inspectable object.

Examples:

Inspecting an agent result

result = agent.run("Hello")
if result.success?
  puts result.content
  puts "Used #{result.turns} turns"
  result.tool_calls_made.each { |tc| puts "  Called: #{tc[:tool_name]}" }
else
  puts "Error: #{result.error.message}"
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(content: nil, messages: [], tool_calls_made: [], usage: {}, turns: 0, error: nil) ⇒ Result

Creates a new Result instance.

Parameters:

  • content (String, nil) (defaults to: nil) —

    the final assistant text

  • messages (Array<Hash>) (defaults to: []) —

    full conversation history

  • tool_calls_made (Array<Hash>) (defaults to: []) —

    executed tool call records

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

    token usage statistics

  • turns (Integer) (defaults to: 0) —

    number of completed cycles

  • error (Exception, nil) (defaults to: nil) —

    error if the run failed



55
56
57
58
59
60
61
62
 
# File 'lib/ruby_pi/agent/result.rb', line 55

def initialize(content: nil, messages: [], tool_calls_made: [], usage: {}, turns: 0, error: nil)
  @content = content
  @messages = Array(messages).freeze
  @tool_calls_made = Array(tool_calls_made).freeze
  @usage = usage
  @turns = turns
  @error = error
end

Instance Attribute Details

#content ⇒ String? (readonly)

Returns the final text content from the assistant.

Returns:

  • (String, nil) —

    the final text content from the assistant



28
29
30
 
# File 'lib/ruby_pi/agent/result.rb', line 28

def content
  @content
end

#error ⇒ RubyPi::Error, ... (readonly)

Returns the error if the run failed.

Returns:

  • (RubyPi::Error, StandardError, nil) —

    the error if the run failed



45
46
47
 
# File 'lib/ruby_pi/agent/result.rb', line 45

def error
  @error
end

#messages ⇒ Array<Hash> (readonly)

Returns the full conversation history (all messages).

Returns:

  • (Array<Hash>) —

    the full conversation history (all messages)



31
32
33
 
# File 'lib/ruby_pi/agent/result.rb', line 31

def messages
  @messages
end

#tool_calls_made ⇒ Array<Hash> (readonly)

Returns tool calls that were executed, each with :tool_name, :arguments, and :result keys.

Returns:

  • (Array<Hash>) —

    tool calls that were executed, each with :tool_name, :arguments, and :result keys



35
36
37
 
# File 'lib/ruby_pi/agent/result.rb', line 35

def tool_calls_made
  @tool_calls_made
end

#turns ⇒ Integer (readonly)

Returns the number of think-act-observe cycles completed.

Returns:

  • (Integer) —

    the number of think-act-observe cycles completed



42
43
44
 
# File 'lib/ruby_pi/agent/result.rb', line 42

def turns
  @turns
end

#usage ⇒ Hash (readonly)

Returns aggregate token usage with :input_tokens and :output_tokens keys.

Returns:

  • (Hash) —

    aggregate token usage with :input_tokens and :output_tokens keys



39
40
41
 
# File 'lib/ruby_pi/agent/result.rb', line 39

def usage
  @usage
end

Instance Method Details

#success? ⇒ Boolean

Returns true if the agent run completed without error.

Returns:

  • (Boolean) —

    true unless an error is present



67
68
69
 
# File 'lib/ruby_pi/agent/result.rb', line 67

def success?
  @error.nil?
end

#to_h ⇒ Hash

Returns a hash representation of the result for serialization.

Returns:

  • (Hash) 


74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/ruby_pi/agent/result.rb', line 74

def to_h
  {
    content: @content,
    messages: @messages,
    tool_calls_made: @tool_calls_made,
    usage: @usage,
    turns: @turns,
    error: @error&.message,
    success: success?
  }
end

#to_s ⇒ String Also known as: inspect

Returns a human-readable string representation of the result.

Returns:

  • (String) 


89
90
91
92
93
94
95
96
 
# File 'lib/ruby_pi/agent/result.rb', line 89

def to_s
  status = success? ? "success" : "error"
  parts = ["status=#{status}", "turns=#{@turns}"]
  parts << "tools=#{@tool_calls_made.size}" unless @tool_calls_made.empty?
  parts << "content=#{@content&.slice(0, 80).inspect}" if @content
  parts << "error=#{@error.class}: #{@error.message}" if @error
  "#<RubyPi::Agent::Result #{parts.join(', ')}>"
end