Class: SwarmSDK::Patterns::AgentObserver

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/patterns/agent_observer.rb

Overview

Observes another agent's actions with optional real-time processing

Examples:

Basic observation

observer = AgentObserver.new(target: :backend)
observer.start
swarm.execute("task")
observer.stop
puts observer.observations

Real-time analysis

observer = AgentObserver.new(
  target: :backend,
  on_event: ->(e) { analyze_security(e) }
)

Filter specific event types

observer = AgentObserver.new(
  target: :backend,
  event_types: ["tool_call", "tool_result"]
)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target:, event_types: nil, on_event: nil) ⇒ AgentObserver

Initialize observer

Parameters:

  • target (Symbol) —

    Agent to observe

  • event_types (Array<String>) (defaults to: nil) —

    Event types to capture (default: all)

  • on_event (Proc) (defaults to: nil) —

    Optional callback for real-time processing



33
34
35
36
37
38
39
40
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 33

def initialize(target:, event_types: nil, on_event: nil)
  @target_agent = target
  @event_types = event_types
  @on_event = on_event
  @observations = []
  @subscription_id = nil
  @started_at = nil
end

Instance Attribute Details

#observations ⇒ Object (readonly)

Returns the value of attribute observations.



26
27
28
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 26

def observations
  @observations
end

#target_agent ⇒ Object (readonly)

Returns the value of attribute target_agent.



26
27
28
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 26

def target_agent
  @target_agent
end

Instance Method Details

#clear_observations ⇒ void

This method returns an undefined value.

Clear collected observations



117
118
119
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 117

def clear_observations
  @observations.clear
end

#observe { ... } ⇒ Object

Execute block while observing

Automatically starts and stops observation around the block

Examples:

observer = AgentObserver.new(target: :backend)
observer.observe do
  swarm.execute("Build API")
end
puts observer.summary

Yields:

  • Block to execute while observing

Returns:

  • (Object) —

    Result from the block



134
135
136
137
138
139
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 134

def observe
  start
  yield
ensure
  stop
end

#observing? ⇒ Boolean

Check if currently observing

Returns:

  • (Boolean) —

    true if actively observing



73
74
75
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 73

def observing?
  !@subscription_id.nil?
end

#start ⇒ void

This method returns an undefined value.

Start observing



45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 45

def start
  return if @subscription_id

  @started_at = Time.now
  @observations.clear

  filter = { agent: @target_agent }
  filter[:type] = @event_types if @event_types

  @subscription_id = LogCollector.subscribe(filter: filter) do |event|
    @observations << event.merge(observed_at: Time.now)
    @on_event&.call(event)
  end
end

#stop ⇒ void

This method returns an undefined value.

Stop observing



63
64
65
66
67
68
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 63

def stop
  return unless @subscription_id

  LogCollector.unsubscribe(@subscription_id)
  @subscription_id = nil
end

#summary ⇒ Hash

Get summary of observations

Returns:

  • (Hash) —

    Summary statistics



80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 80

def summary
  {
    target: @target_agent,
    started_at: @started_at,
    duration_seconds: @started_at ? (Time.now - @started_at).round(2) : 0,
    total_events: @observations.size,
    event_breakdown: @observations.group_by { |e| e[:type] }.transform_values(&:count),
    tool_calls: @observations.select { |e| e[:type] == "tool_call" }.map { |e| e[:tool_name] },
    errors: @observations.select { |e| e[:type] == "internal_error" },
  }
end

#to_llm_context ⇒ String

Format observations for LLM consumption

Useful for providing observation data to another agent for analysis

Returns:

  • (String) —

    Formatted observation log



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/swarm_sdk/patterns/agent_observer.rb', line 97

def to_llm_context
  @observations.map do |event|
    case event[:type]
    when "tool_call"
      "- Called #{event[:tool_name]} with: #{truncate_json(event[:arguments])}"
    when "tool_result"
      "- #{event[:tool_name]} returned: #{truncate(event[:result])}"
    when "agent_step"
      "- Thinking: #{truncate(event[:content])}"
    when "agent_stop"
      "- Final response: #{truncate(event[:content])}"
    else
      "- [#{event[:type]}] #{event.except(:type, :timestamp, :observed_at).to_json}"
    end
  end.join("\n")
end