Class: Phronomy::Agent::Checkpoint

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/agent/checkpoint.rb

Overview

Encapsulates the suspended state of an agent invocation.

A Checkpoint is returned as the +:checkpoint+ key of the result hash when an approval-required tool is encountered and no synchronous on_approval_required handler has been registered.

Pass the checkpoint to Agent::Base#resume to continue execution after obtaining an approval decision from the user or an external system.

Examples:

Suspend and resume

result = agent.invoke("Do task X")
if result[:suspended]
  approved = prompt_user(result[:checkpoint].pending_tool_name)
  result   = agent.resume(result[:checkpoint], approved: approved)
end
puts result[:output]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:) ⇒ Checkpoint

Returns a new instance of Checkpoint.

Parameters:

  • thread_id (String, nil)
  • original_input (String, Hash) —

    the input passed to the original #invoke call

  • messages (Array<RubyLLM::Message>)
  • pending_tool_name (String)
  • pending_tool_args (Hash)
  • pending_tool_call_id (String) 


51
52
53
54
55
56
57
58
 
# File 'lib/phronomy/agent/checkpoint.rb', line 51

def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:)
  @thread_id = thread_id
  @original_input = original_input
  @messages = messages.dup.freeze
  @pending_tool_name = pending_tool_name
  @pending_tool_args = pending_tool_args
  @pending_tool_call_id = pending_tool_call_id
end

Instance Attribute Details

#messages ⇒ Array<RubyLLM::Message> (readonly)

Returns conversation messages up to and including the assistant message that requested the pending tool call.

Returns:

  • (Array<RubyLLM::Message>) —

    conversation messages up to and including the assistant message that requested the pending tool call



32
33
34
 
# File 'lib/phronomy/agent/checkpoint.rb', line 32

def messages
  @messages
end

#original_input ⇒ String, Hash (readonly)

Returns the original input passed to #invoke; stored so that #resume can re-apply dynamic system instructions (e.g. Proc or PromptTemplate-based instructions that depend on the input value).

Returns:

  • (String, Hash) —

    the original input passed to #invoke; stored so that #resume can re-apply dynamic system instructions (e.g. Proc or PromptTemplate-based instructions that depend on the input value).



28
29
30
 
# File 'lib/phronomy/agent/checkpoint.rb', line 28

def original_input
  @original_input
end

#pending_tool_args ⇒ Hash (readonly)

Returns the arguments the LLM passed to the pending tool.

Returns:

  • (Hash) —

    the arguments the LLM passed to the pending tool



38
39
40
 
# File 'lib/phronomy/agent/checkpoint.rb', line 38

def pending_tool_args
  @pending_tool_args
end

#pending_tool_call_id ⇒ String (readonly)

Returns the tool_call_id from the LLM response (required to inject the tool result message on resume).

Returns:

  • (String) —

    the tool_call_id from the LLM response (required to inject the tool result message on resume)



42
43
44
 
# File 'lib/phronomy/agent/checkpoint.rb', line 42

def pending_tool_call_id
  @pending_tool_call_id
end

#pending_tool_name ⇒ String (readonly)

Returns the name of the tool awaiting approval.

Returns:

  • (String) —

    the name of the tool awaiting approval



35
36
37
 
# File 'lib/phronomy/agent/checkpoint.rb', line 35

def pending_tool_name
  @pending_tool_name
end

#thread_id ⇒ String? (readonly)

Returns the thread_id from the invocation config.

Returns:

  • (String, nil) —

    the thread_id from the invocation config



23
24
25
 
# File 'lib/phronomy/agent/checkpoint.rb', line 23

def thread_id
  @thread_id
end

Class Method Details

.from_h(h) ⇒ Checkpoint

Reconstructs a +Checkpoint+ from a plain Hash (e.g. produced by #to_h and deserialized from JSON or Marshal).

Hash keys may be either Symbols or Strings; both are accepted. +RubyLLM::ToolCall+ objects inside message +:tool_calls+ arrays are reconstructed from their hash representations.

Parameters:

  • h (Hash) —

    a hash previously produced by #to_h

Returns:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/phronomy/agent/checkpoint.rb', line 93

def self.from_h(h)
  h = h.transform_keys { |k|
    begin
      k.to_sym
    rescue
      k
    end
  }
  messages = Array(h[:messages]).map { |m| deserialize_message(m) }
  new(
    thread_id: h[:thread_id],
    original_input: h[:original_input],
    messages: messages,
    pending_tool_name: h[:pending_tool_name]&.to_s,
    pending_tool_args: h[:pending_tool_args] ? h[:pending_tool_args].transform_keys { |k|
      begin
        k.to_sym
      rescue
        k
      end
    } : {},
    pending_tool_call_id: h[:pending_tool_call_id]&.to_s
  )
end

Instance Method Details

#to_h ⇒ Hash

Converts this checkpoint to a plain Hash suitable for JSON / Marshal serialization.

All values are plain Ruby objects (String, Symbol, Hash, Array, Numeric, nil). +RubyLLM::Message+ objects in +:messages+ are deep-converted so that any embedded +RubyLLM::ToolCall+ objects are also serialized as plain hashes.

Examples:

Round-trip via JSON

json = JSON.generate(checkpoint.to_h)
checkpoint2 = Phronomy::Agent::Checkpoint.from_h(JSON.parse(json))

Returns:

  • (Hash) 


72
73
74
75
76
77
78
79
80
81
 
# File 'lib/phronomy/agent/checkpoint.rb', line 72

def to_h
  {
    thread_id: @thread_id,
    original_input: @original_input,
    messages: @messages.map { |m| serialize_message(m) },
    pending_tool_name: @pending_tool_name,
    pending_tool_args: @pending_tool_args,
    pending_tool_call_id: @pending_tool_call_id
  }
end