Class: SwarmSDK::Agent::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/agent/context.rb

Overview

AgentContext encapsulates per-agent state and metadata

Each agent has its own context that tracks:

  • Agent identity (name)
  • Delegation relationships (which tool calls are delegations)
  • Context window warnings (which thresholds have been hit)
  • Optional metadata

This class replaces the per-agent hash maps that were previously stored in UnifiedLogger.

Examples:

context = Agent::Context.new(
  name: :backend,
  delegation_tools: ["DelegateToDatabase", "DelegateToAuth"],
  metadata: { role: "backend" }
)

# Track a delegation
context.track_delegation(call_id: "call_123", target: "DelegateToDatabase")

# Check if a tool call is a delegation
context.delegation?(call_id: "call_123") # => true

Constant Summary collapse

CONTEXT_WARNING_THRESHOLDS =

Thresholds for context limit warnings (in percentage) 60% triggers automatic compression, 80%/90% are informational warnings

[60, 80, 90].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, swarm_id:, parent_swarm_id: nil, delegation_tools: [], metadata: {}) ⇒ Context

Initialize a new agent context

Parameters:

  • name (Symbol, String) —

    Agent name

  • swarm_id (String) —

    Swarm ID for event tracking

  • parent_swarm_id (String, nil) (defaults to: nil) —

    Parent swarm ID (nil for root swarms)

  • delegation_tools (Array<String>) (defaults to: []) —

    Names of tools that are delegations

  • metadata (Hash) (defaults to: {}) —

    Optional metadata about the agent



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/swarm_sdk/agent/context.rb', line 44

def initialize(name:, swarm_id:, parent_swarm_id: nil, delegation_tools: [], metadata: {})
  @name = name.to_sym
  @swarm_id = swarm_id
  @parent_swarm_id = parent_swarm_id
  @delegation_tools = Set.new(delegation_tools.map(&:to_s))
  @metadata = metadata
  @delegation_call_ids = Set.new
  @delegation_targets = {}
  @warning_thresholds_hit = Set.new
end

Instance Attribute Details

#delegation_tools ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def delegation_tools
  @delegation_tools
end

#metadata ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def metadata
  @metadata
end

#name ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def name
  @name
end

#parent_swarm_id ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def parent_swarm_id
  @parent_swarm_id
end

#swarm_id ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def swarm_id
  @swarm_id
end

#warning_thresholds_hit ⇒ Object (readonly)

NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold



35
36
37
 
# File 'lib/swarm_sdk/agent/context.rb', line 35

def warning_thresholds_hit
  @warning_thresholds_hit
end

Instance Method Details

#clear_delegation(call_id:) ⇒ void

This method returns an undefined value.

Remove a delegation from tracking (after it completes)

Parameters:

  • call_id (String) —

    Tool call ID



85
86
87
88
 
# File 'lib/swarm_sdk/agent/context.rb', line 85

def clear_delegation(call_id:)
  @delegation_targets.delete(call_id)
  @delegation_call_ids.delete(call_id)
end

#delegation?(call_id:) ⇒ Boolean

Check if a tool call is a delegation

Parameters:

  • call_id (String) —

    Tool call ID

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/swarm_sdk/agent/context.rb', line 69

def delegation?(call_id:)
  @delegation_call_ids.include?(call_id)
end

#delegation_target(call_id:) ⇒ String?

Get the delegation target for a tool call

Parameters:

  • call_id (String) —

    Tool call ID

Returns:

  • (String, nil) —

    Target agent/tool name, or nil if not a delegation



77
78
79
 
# File 'lib/swarm_sdk/agent/context.rb', line 77

def delegation_target(call_id:)
  @delegation_targets[call_id]
end

#delegation_tool?(tool_name) ⇒ Boolean

Check if a tool name is a delegation tool

Parameters:

  • tool_name (String) —

    Tool name

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/swarm_sdk/agent/context.rb', line 94

def delegation_tool?(tool_name)
  @delegation_tools.include?(tool_name.to_s)
end

#hit_warning_threshold?(threshold) ⇒ Boolean

Record that a context warning threshold has been hit

Parameters:

  • threshold (Integer) —

    Threshold percentage (80, 90, etc)

Returns:

  • (Boolean) —

    true if this is the first time hitting this threshold



102
103
104
 
# File 'lib/swarm_sdk/agent/context.rb', line 102

def hit_warning_threshold?(threshold)
  !@warning_thresholds_hit.add?(threshold).nil?
end

#track_delegation(call_id:, target:) ⇒ void

This method returns an undefined value.

Track a delegation tool call

Parameters:

  • call_id (String) —

    Tool call ID

  • target (String) —

    Target agent/tool name



60
61
62
63
 
# File 'lib/swarm_sdk/agent/context.rb', line 60

def track_delegation(call_id:, target:)
  @delegation_call_ids.add(call_id)
  @delegation_targets[call_id] = target
end

#warning_threshold_hit?(threshold) ⇒ Boolean

Check if a warning threshold has been hit

Parameters:

  • threshold (Integer) —

    Threshold percentage

Returns:

  • (Boolean) 


110
111
112
 
# File 'lib/swarm_sdk/agent/context.rb', line 110

def warning_threshold_hit?(threshold)
  @warning_thresholds_hit.include?(threshold)
end