Class: SwarmSDK::Hooks::Result

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/hooks/result.rb

Overview

Result object returned by hooks to control execution flow

Hooks can return a Result to:

  • Continue normal execution (default)
  • Halt execution and return an error/message
  • Replace a value (e.g., tool result, delegation result)
  • Reprompt the agent with a new prompt
  • Finish the current agent's execution (agent scope)
  • Finish the entire swarm execution (swarm scope)

Examples:

Continue normal execution (default)

SwarmSDK::Hooks::Result.continue

Halt execution with error message

SwarmSDK::Hooks::Result.halt("Validation failed: invalid input")

Replace tool result

SwarmSDK::Hooks::Result.replace("Custom tool result")

Reprompt agent with modified prompt

SwarmSDK::Hooks::Result.reprompt("Modified task: #{original_task}")

Finish current agent with message

SwarmSDK::Hooks::Result.finish_agent("Agent task completed")

Finish entire swarm with message

SwarmSDK::Hooks::Result.finish_swarm("All tasks complete!")

Constant Summary collapse

VALID_ACTIONS =

Valid actions that control execution flow

[:continue, :halt, :replace, :reprompt, :finish_agent, :finish_swarm].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action:, value: nil) ⇒ Result

Returns a new instance of Result.

Parameters:

  • action (Symbol) —

    Action to take (:continue, :halt, :replace, :reprompt)

  • value (Object, nil) (defaults to: nil) —

    Associated value (context for :continue, message for :halt, etc.)



40
41
42
43
44
45
46
47
 
# File 'lib/swarm_sdk/hooks/result.rb', line 40

def initialize(action:, value: nil)
  unless VALID_ACTIONS.include?(action)
    raise ArgumentError, "Invalid action: #{action}. Valid actions: #{VALID_ACTIONS.join(", ")}"
  end

  @action = action
  @value = value
end

Instance Attribute Details

#action ⇒ Object (readonly)

Returns the value of attribute action.



33
34
35
 
# File 'lib/swarm_sdk/hooks/result.rb', line 33

def action
  @action
end

#value ⇒ Object (readonly)

Returns the value of attribute value.



33
34
35
 
# File 'lib/swarm_sdk/hooks/result.rb', line 33

def value
  @value
end

Class Method Details

.continue(context = nil) ⇒ Result

Create a result that continues normal execution

Parameters:

  • context (Context, nil) (defaults to: nil) —

    Updated context (optional)

Returns:

  • (Result) —

    Result with continue action



96
97
98
 
# File 'lib/swarm_sdk/hooks/result.rb', line 96

def continue(context = nil)
  new(action: :continue, value: context)
end

.finish_agent(message) ⇒ Result

Create a result that finishes the current agent

Exits the agent's chat loop and returns the message as the agent's final response. If this agent was delegated to, control returns to the calling agent. The swarm continues if there's more work.

Parameters:

  • message (String) —

    Final message from the agent

Returns:

  • (Result) —

    Result with finish_agent action



132
133
134
 
# File 'lib/swarm_sdk/hooks/result.rb', line 132

def finish_agent(message)
  new(action: :finish_agent, value: message)
end

.finish_swarm(message) ⇒ Result

Create a result that finishes the entire swarm

Immediately exits the Swarm.execute() loop and returns the message as the final Result#output. All agent execution stops and the user receives this message.

Parameters:

  • message (String) —

    Final message from the swarm

Returns:

  • (Result) —

    Result with finish_swarm action



144
145
146
 
# File 'lib/swarm_sdk/hooks/result.rb', line 144

def finish_swarm(message)
  new(action: :finish_swarm, value: message)
end

.halt(message) ⇒ Result

Create a result that halts execution

Parameters:

  • message (String) —

    Error or halt message

Returns:

  • (Result) —

    Result with halt action



104
105
106
 
# File 'lib/swarm_sdk/hooks/result.rb', line 104

def halt(message)
  new(action: :halt, value: message)
end

.replace(value) ⇒ Result

Create a result that replaces a value

Parameters:

  • value (Object) —

    Replacement value

Returns:

  • (Result) —

    Result with replace action



112
113
114
 
# File 'lib/swarm_sdk/hooks/result.rb', line 112

def replace(value)
  new(action: :replace, value: value)
end

.reprompt(prompt) ⇒ Result

Create a result that reprompts the agent

Parameters:

  • prompt (String) —

    New prompt to send to agent

Returns:

  • (Result) —

    Result with reprompt action



120
121
122
 
# File 'lib/swarm_sdk/hooks/result.rb', line 120

def reprompt(prompt)
  new(action: :reprompt, value: prompt)
end

Instance Method Details

#continue? ⇒ Boolean

Check if this result continues normal execution

Returns:

  • (Boolean) —

    true if action is :continue



73
74
75
 
# File 'lib/swarm_sdk/hooks/result.rb', line 73

def continue?
  @action == :continue
end

#finish_agent? ⇒ Boolean

Check if this result finishes the current agent

Returns:

  • (Boolean) —

    true if action is :finish_agent



80
81
82
 
# File 'lib/swarm_sdk/hooks/result.rb', line 80

def finish_agent?
  @action == :finish_agent
end

#finish_swarm? ⇒ Boolean

Check if this result finishes the entire swarm

Returns:

  • (Boolean) —

    true if action is :finish_swarm



87
88
89
 
# File 'lib/swarm_sdk/hooks/result.rb', line 87

def finish_swarm?
  @action == :finish_swarm
end

#halt? ⇒ Boolean

Check if this result indicates halting execution

Returns:

  • (Boolean) —

    true if action is :halt



52
53
54
 
# File 'lib/swarm_sdk/hooks/result.rb', line 52

def halt?
  @action == :halt
end

#replace? ⇒ Boolean

Check if this result provides a replacement value

Returns:

  • (Boolean) —

    true if action is :replace



59
60
61
 
# File 'lib/swarm_sdk/hooks/result.rb', line 59

def replace?
  @action == :replace
end

#reprompt? ⇒ Boolean

Check if this result requests reprompting

Returns:

  • (Boolean) —

    true if action is :reprompt



66
67
68
 
# File 'lib/swarm_sdk/hooks/result.rb', line 66

def reprompt?
  @action == :reprompt
end