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

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) 


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

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