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:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:) ⇒ Checkpoint

Returns a new instance of Checkpoint.

Parameters:

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


44
45
46
47
48
49
50
 
# File 'lib/phronomy/agent/checkpoint.rb', line 44

def initialize(thread_id:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:)
  @thread_id = thread_id
  @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



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

def messages
  @messages
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



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

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)



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

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



30
31
32
 
# File 'lib/phronomy/agent/checkpoint.rb', line 30

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