Class: Legate::AgentDefinition

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/legate/agent_definition.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ AgentDefinition

Returns a new instance of AgentDefinition.



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/legate/agent_definition.rb', line 95

def initialize
  @name = nil
  @description = ''
  @instruction = ''
  @tool_names = Set.new
  @model_name = nil
  @temperature = nil
  # --- Webhook Defaults ---
  @webhook_enabled = false
  @webhook_validator = nil
  @webhook_secret = nil
  @webhook_transformer = nil
  @webhook_session_extractor = nil
  @fallback_mode = :error # Default fallback mode
  @mcp_servers = [] # Default MCP servers
  @sub_agent_names = Set.new # MAS attribute for sub-agent definitions
  @output_key = nil # MAS attribute for state management
  # --- MAS Workflow Agent Attributes ---
  @agent_type = :llm # Default agent type
  @planning_strategy = :plan # :plan (upfront plan) or :react (agentic loop)
  @sequential_sub_agent_names = Set.new # For SequentialAgent
  @parallel_sub_agent_names = Set.new # For ParallelAgent
  @loop_sub_agent_names = Set.new # For LoopAgent
  @loop_max_iterations = nil # Maximum number of loop iterations
  @loop_timeout_seconds = nil
  @parallel_timeout_seconds = nil
  @loop_condition_state_key = nil
  @loop_condition_expected_value = nil # Expected value for loop condition
  @delegation_targets = Set.new # Agent names that this agent can delegate to
  # -----------------------

  # --- Authentication Attributes ---
  @auth_credential_names = Set.new # Credential names this agent can use
  @auth_url_mappings = [] # URL pattern to scheme/credential mappings
  @auth_scheme_assignments = {} # Service to scheme assignments
  @auth_credential_assignments = {} # Service to credential assignments
  # -----------------------

  @proxy = DefinitionProxy.new(self)
end

Instance Attribute Details

#after_agent_callback ⇒ Proc? (readonly)

Returns Callback run after agent execution completes.

Returns:

  • (Proc, nil) —

    Callback run after agent execution completes



79
80
81
 
# File 'lib/legate/agent_definition.rb', line 79

def after_agent_callback
  @after_agent_callback
end

#after_model_callback ⇒ Proc? (readonly)

Returns Callback run after LLM model interaction.

Returns:

  • (Proc, nil) —

    Callback run after LLM model interaction



83
84
85
 
# File 'lib/legate/agent_definition.rb', line 83

def after_model_callback
  @after_model_callback
end

#after_tool_callback ⇒ Proc? (readonly)

Returns Callback run after any tool execution.

Returns:

  • (Proc, nil) —

    Callback run after any tool execution



87
88
89
 
# File 'lib/legate/agent_definition.rb', line 87

def after_tool_callback
  @after_tool_callback
end

#agent_type ⇒ Symbol (readonly)

Returns The type of agent (:llm, :sequential, :parallel, :loop). Defaults to :llm.

Returns:

  • (Symbol) —

    The type of agent (:llm, :sequential, :parallel, :loop). Defaults to :llm.



42
43
44
 
# File 'lib/legate/agent_definition.rb', line 42

def agent_type
  @agent_type
end

#auth_credential_assignments ⇒ Hash<Symbol, Symbol> (readonly)

Returns Service to credential name assignments.

Returns:

  • (Hash<Symbol, Symbol>) —

    Service to credential name assignments.



73
74
75
 
# File 'lib/legate/agent_definition.rb', line 73

def auth_credential_assignments
  @auth_credential_assignments
end

#auth_credential_names ⇒ Set<Symbol> (readonly)

— Authentication Attributes —

Returns:

  • (Set<Symbol>) —

    A set of credential names this agent can use.



67
68
69
 
# File 'lib/legate/agent_definition.rb', line 67

def auth_credential_names
  @auth_credential_names
end

#auth_scheme_assignments ⇒ Hash<Symbol, Symbol> (readonly)

Returns Service to scheme name assignments.

Returns:

  • (Hash<Symbol, Symbol>) —

    Service to scheme name assignments.



71
72
73
 
# File 'lib/legate/agent_definition.rb', line 71

def auth_scheme_assignments
  @auth_scheme_assignments
end

#auth_url_mappings ⇒ Array<Hash> (readonly)

Returns URL pattern to scheme/credential mappings for this agent.

Returns:

  • (Array<Hash>) —

    URL pattern to scheme/credential mappings for this agent.



69
70
71
 
# File 'lib/legate/agent_definition.rb', line 69

def auth_url_mappings
  @auth_url_mappings
end

#before_agent_callback ⇒ Proc? (readonly)

— Callback Attributes —

Returns:

  • (Proc, nil) —

    Callback run before agent execution begins



77
78
79
 
# File 'lib/legate/agent_definition.rb', line 77

def before_agent_callback
  @before_agent_callback
end

#before_model_callback ⇒ Proc? (readonly)

Returns Callback run before LLM model interaction.

Returns:

  • (Proc, nil) —

    Callback run before LLM model interaction



81
82
83
 
# File 'lib/legate/agent_definition.rb', line 81

def before_model_callback
  @before_model_callback
end

#before_tool_callback ⇒ Proc? (readonly)

Returns Callback run before any tool execution.

Returns:

  • (Proc, nil) —

    Callback run before any tool execution



85
86
87
 
# File 'lib/legate/agent_definition.rb', line 85

def before_tool_callback
  @before_tool_callback
end

#delegation_targets ⇒ Set<Symbol> (readonly)

Returns A set of names of agents that this agent can delegate tasks to via LLM planning.

Returns:

  • (Set<Symbol>) —

    A set of names of agents that this agent can delegate tasks to via LLM planning.



63
64
65
 
# File 'lib/legate/agent_definition.rb', line 63

def delegation_targets
  @delegation_targets
end

#description ⇒ String (readonly)

Returns A description of the agent’s purpose.

Returns:

  • (String) —

    A description of the agent’s purpose.



14
15
16
 
# File 'lib/legate/agent_definition.rb', line 14

def description
  @description
end

#fallback_mode ⇒ Symbol (readonly)

Returns The fallback mode (:error or :echo). Defaults to :error.

Returns:

  • (Symbol) —

    The fallback mode (:error or :echo). Defaults to :error.



34
35
36
 
# File 'lib/legate/agent_definition.rb', line 34

def fallback_mode
  @fallback_mode
end

#instruction ⇒ String (readonly)

Returns The core instructions given to the language model.

Returns:

  • (String) —

    The core instructions given to the language model.



16
17
18
 
# File 'lib/legate/agent_definition.rb', line 16

def instruction
  @instruction
end

#loop_condition_expected_value ⇒ Object? (readonly)

Returns The expected value for loop condition (for LoopAgent).

Returns:

  • (Object, nil) —

    The expected value for loop condition (for LoopAgent).



59
60
61
 
# File 'lib/legate/agent_definition.rb', line 59

def loop_condition_expected_value
  @loop_condition_expected_value
end

#loop_condition_state_key ⇒ Symbol? (readonly)

Returns The key in the session state to check for loop condition (for LoopAgent).

Returns:

  • (Symbol, nil) —

    The key in the session state to check for loop condition (for LoopAgent).



57
58
59
 
# File 'lib/legate/agent_definition.rb', line 57

def loop_condition_state_key
  @loop_condition_state_key
end

#loop_max_iterations ⇒ Integer? (readonly)

Returns The maximum number of loop iterations (for LoopAgent).

Returns:

  • (Integer, nil) —

    The maximum number of loop iterations (for LoopAgent).



53
54
55
 
# File 'lib/legate/agent_definition.rb', line 53

def loop_max_iterations
  @loop_max_iterations
end

#loop_sub_agent_names ⇒ Set<Symbol> (readonly)

Returns A set of names of sub-agents to execute in each loop iteration (for LoopAgent).

Returns:

  • (Set<Symbol>) —

    A set of names of sub-agents to execute in each loop iteration (for LoopAgent).



51
52
53
 
# File 'lib/legate/agent_definition.rb', line 51

def loop_sub_agent_names
  @loop_sub_agent_names
end

#loop_timeout_seconds ⇒ Integer? (readonly)

Returns Wall-clock timeout in seconds for the entire loop (for LoopAgent).

Returns:

  • (Integer, nil) —

    Wall-clock timeout in seconds for the entire loop (for LoopAgent).



55
56
57
 
# File 'lib/legate/agent_definition.rb', line 55

def loop_timeout_seconds
  @loop_timeout_seconds
end

#mcp_servers ⇒ Array<Hash> (readonly)

Returns Configuration for MCP servers. Defaults to [].

Returns:

  • (Array<Hash>) —

    Configuration for MCP servers. Defaults to [].



36
37
38
 
# File 'lib/legate/agent_definition.rb', line 36

def mcp_servers
  @mcp_servers
end

#model_name ⇒ String? (readonly)

Returns The specific model name to use (e.g., “gpt-4-turbo”). Overrides global default.

Returns:

  • (String, nil) —

    The specific model name to use (e.g., “gpt-4-turbo”). Overrides global default.



20
21
22
 
# File 'lib/legate/agent_definition.rb', line 20

def model_name
  @model_name
end

#name ⇒ Symbol (readonly)

Returns The unique name identifying this agent definition.

Returns:

  • (Symbol) —

    The unique name identifying this agent definition.



12
13
14
 
# File 'lib/legate/agent_definition.rb', line 12

def name
  @name
end

#output_key ⇒ Symbol? (readonly)

Returns The key under which the agent’s final output should be stored in the session state.

Returns:

  • (Symbol, nil) —

    The key under which the agent’s final output should be stored in the session state.



40
41
42
 
# File 'lib/legate/agent_definition.rb', line 40

def output_key
  @output_key
end

#parallel_sub_agent_names ⇒ Set<Symbol> (readonly)

Returns A set of names of sub-agents to execute in parallel (for ParallelAgent).

Returns:

  • (Set<Symbol>) —

    A set of names of sub-agents to execute in parallel (for ParallelAgent).



49
50
51
 
# File 'lib/legate/agent_definition.rb', line 49

def parallel_sub_agent_names
  @parallel_sub_agent_names
end

#parallel_timeout_seconds ⇒ Integer? (readonly)

Returns Timeout in seconds for each parallel sub-agent (for ParallelAgent). Defaults to 120.

Returns:

  • (Integer, nil) —

    Timeout in seconds for each parallel sub-agent (for ParallelAgent). Defaults to 120.



61
62
63
 
# File 'lib/legate/agent_definition.rb', line 61

def parallel_timeout_seconds
  @parallel_timeout_seconds
end

#planning_strategy ⇒ Symbol (readonly)

Returns Planning strategy for :llm agents — :plan (one upfront plan, default) or :react (agentic observe->think->act loop).

Returns:

  • (Symbol) —

    Planning strategy for :llm agents — :plan (one upfront plan, default) or :react (agentic observe->think->act loop).



45
46
47
 
# File 'lib/legate/agent_definition.rb', line 45

def planning_strategy
  @planning_strategy
end

#sequential_sub_agent_names ⇒ Set<Symbol> (readonly)

Returns A set of names of sub-agents to execute in sequence (for SequentialAgent).

Returns:

  • (Set<Symbol>) —

    A set of names of sub-agents to execute in sequence (for SequentialAgent).



47
48
49
 
# File 'lib/legate/agent_definition.rb', line 47

def sequential_sub_agent_names
  @sequential_sub_agent_names
end

#sub_agent_names ⇒ Set<Symbol> (readonly)

Returns A set of names of sub-agent definitions to instantiate.

Returns:

  • (Set<Symbol>) —

    A set of names of sub-agent definitions to instantiate.



38
39
40
 
# File 'lib/legate/agent_definition.rb', line 38

def sub_agent_names
  @sub_agent_names
end

#temperature ⇒ Float? (readonly)

Returns The temperature setting for the model. Overrides global default.

Returns:

  • (Float, nil) —

    The temperature setting for the model. Overrides global default.



22
23
24
 
# File 'lib/legate/agent_definition.rb', line 22

def temperature
  @temperature
end

#tool_names ⇒ Set<Symbol> (readonly)

Returns A set of names of the tools available to this agent.

Returns:

  • (Set<Symbol>) —

    A set of names of the tools available to this agent.



18
19
20
 
# File 'lib/legate/agent_definition.rb', line 18

def tool_names
  @tool_names
end

#webhook_enabled ⇒ Boolean (readonly)

Returns Whether this agent can be triggered by webhooks. Defaults to false.

Returns:

  • (Boolean) —

    Whether this agent can be triggered by webhooks. Defaults to false.



24
25
26
 
# File 'lib/legate/agent_definition.rb', line 24

def webhook_enabled
  @webhook_enabled
end

#webhook_secret ⇒ String? (readonly)

Returns The secret key for webhook validation.

Returns:

  • (String, nil) —

    The secret key for webhook validation.



28
29
30
 
# File 'lib/legate/agent_definition.rb', line 28

def webhook_secret
  @webhook_secret
end

#webhook_session_extractor ⇒ Proc? (readonly)

Returns The session extractor proc for webhook requests.

Returns:

  • (Proc, nil) —

    The session extractor proc for webhook requests.



32
33
34
 
# File 'lib/legate/agent_definition.rb', line 32

def webhook_session_extractor
  @webhook_session_extractor
end

#webhook_transformer ⇒ Proc? (readonly)

Returns The transformer proc for webhook payloads.

Returns:

  • (Proc, nil) —

    The transformer proc for webhook payloads.



30
31
32
 
# File 'lib/legate/agent_definition.rb', line 30

def webhook_transformer
  @webhook_transformer
end

#webhook_validator ⇒ Symbol, ... (readonly)

Returns The validator (name or proc) for webhook requests.

Returns:

  • (Symbol, Proc, nil) —

    The validator (name or proc) for webhook requests.



26
27
28
 
# File 'lib/legate/agent_definition.rb', line 26

def webhook_validator
  @webhook_validator
end

Class Method Details

.from_hash(hash_data) ⇒ Legate::AgentDefinition?

Class method to create an AgentDefinition instance from a hash. This is typically used when loading a definition from a persistent store.

Parameters:

  • hash_data (Hash) —

    The hash containing agent definition attributes.

Returns:



597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
 
# File 'lib/legate/agent_definition.rb', line 597

def self.from_hash(hash_data)
  return nil unless hash_data.is_a?(Hash)

  definition = new

  # Helper method to convert array values to Sets if present in the source hash
  convert_to_set = lambda do |key, default = nil|
    if hash_data.key?(key)
      val = hash_data[key]
      if val.is_a?(Array)
        Set.new(val.map(&:to_sym))
      else
        (val.nil? ? default : Set.new([val.to_sym]))
      end
    else
      default || Set.new
    end
  end

  # Map string or symbol keys to our keys
  definition.instance_variable_set(:@name, hash_data[:name]&.to_sym || hash_data['name']&.to_sym)
  definition.instance_variable_set(:@description, hash_data[:description]&.to_s || hash_data['description']&.to_s || '')
  definition.instance_variable_set(:@instruction, hash_data[:instruction]&.to_s || hash_data['instruction']&.to_s || '')

  # Handle tools/tool_names (expected to be an array of strings or symbols)
  tool_names = nil
  if hash_data.key?(:tool_names) || hash_data.key?('tool_names')
    tool_names = hash_data[:tool_names] || hash_data['tool_names']
  elsif hash_data.key?(:tools) || hash_data.key?('tools')
    tool_names = hash_data[:tools] || hash_data['tools']
  end

  # Convert tool_names to a Set of symbols (always ensure it's a Set)
  if tool_names.is_a?(Array)
    definition.instance_variable_set(:@tool_names, Set.new(tool_names.map(&:to_sym)))
  elsif tool_names.is_a?(String)
    # Special case: if it's a JSON string, try to parse it
    begin
      parsed_tools = JSON.parse(tool_names)
      if parsed_tools.is_a?(Array)
        definition.instance_variable_set(:@tool_names, Set.new(parsed_tools.map(&:to_sym)))
      else
        definition.instance_variable_set(:@tool_names, Set.new)
      end
    rescue JSON::ParserError
      Legate.logger.warn("AgentDefinition.from_hash: tool_names string is not valid JSON, ignoring: #{tool_names.inspect}")
      definition.instance_variable_set(:@tool_names, Set.new)
    end
  else
    # No valid tools provided, use empty set
    definition.instance_variable_set(:@tool_names, Set.new)
  end

  # Process model_name (string or symbol)
  model_name = hash_data[:model_name] || hash_data['model_name'] || hash_data[:model] || hash_data['model']
  definition.instance_variable_set(:@model_name, model_name&.to_sym)

  # Process temperature (float)
  temp_value = hash_data[:temperature] || hash_data['temperature']
  definition.instance_variable_set(:@temperature, temp_value&.to_f)

  # --- Process webhook fields ---
  # Boolean conversion helper for webhook_enabled
  wb_enabled = hash_data[:webhook_enabled] || hash_data['webhook_enabled']
  wb_enabled = wb_enabled.to_s.downcase == 'true' if wb_enabled.is_a?(String)
  definition.instance_variable_set(:@webhook_enabled, !!wb_enabled) # Force to boolean

  # webhook_validator can be symbol or nil
  wb_validator = hash_data[:webhook_validator] || hash_data['webhook_validator']
  definition.instance_variable_set(:@webhook_validator, wb_validator.is_a?(Symbol) ? wb_validator : nil)

  # webhook_secret is a string or nil
  wb_secret = hash_data[:webhook_secret] || hash_data['webhook_secret']
  # Special case: '<present>' is a placeholder used in to_h when the secret exists
  definition.instance_variable_set(:@webhook_secret, wb_secret == '<present>' ? wb_secret : wb_secret)

  # webhook_transformer and webhook_session_extractor are Procs (can't be serialized)
  # Always nil when recreated from a hash
  definition.instance_variable_set(:@webhook_transformer, nil)
  definition.instance_variable_set(:@webhook_session_extractor, nil)

  # --- Process MCP servers ---
  # MCP servers can be array of hashes, or JSON string
  mcp_value = hash_data[:mcp_servers] || hash_data['mcp_servers'] || hash_data[:mcp_servers_json] || hash_data['mcp_servers_json']
  if mcp_value.is_a?(String)
    begin
      parsed_mcp = JSON.parse(mcp_value)
      definition.instance_variable_set(:@mcp_servers, parsed_mcp.is_a?(Array) ? parsed_mcp : [])
    rescue JSON::ParserError
      # Not valid JSON, use empty array
      definition.instance_variable_set(:@mcp_servers, [])
    end
  elsif mcp_value.is_a?(Array)
    definition.instance_variable_set(:@mcp_servers, mcp_value)
  else
    definition.instance_variable_set(:@mcp_servers, [])
  end

  # --- Process fallback_mode (convert to symbol) ---
  fallback = hash_data[:fallback_mode] || hash_data['fallback_mode']
  if fallback.is_a?(String) || fallback.is_a?(Symbol)
    fb_sym = fallback.to_sym
    definition.instance_variable_set(:@fallback_mode, fb_sym == :echo ? :echo : :error)
  else
    definition.instance_variable_set(:@fallback_mode, :error) # Default
  end

  # --- Process MAS attributes ---
  # Sub-agent names (convert to Set of symbols)
  definition.instance_variable_set(:@sub_agent_names, convert_to_set.call(:sub_agent_names))

  # Output key (convert to symbol if present)
  output_key = hash_data[:output_key] || hash_data['output_key']
  definition.instance_variable_set(:@output_key, output_key&.to_sym)

  # --- MAS Workflow Agent Attributes ---
  # Agent type (convert to symbol, default to :llm)
  agent_type = hash_data[:agent_type] || hash_data['agent_type'] || :llm
  if agent_type.is_a?(String) || agent_type.is_a?(Symbol)
    agent_type_sym = agent_type.to_sym
    valid_types = %i[llm sequential parallel loop]
    # If invalid type, use default :llm
    agent_type_sym = :llm unless valid_types.include?(agent_type_sym)
    definition.instance_variable_set(:@agent_type, agent_type_sym)
  else
    definition.instance_variable_set(:@agent_type, :llm) # Default
  end

  # Planning strategy (:plan default, :react opt-in)
  strategy = (hash_data[:planning_strategy] || hash_data['planning_strategy'] || :plan).to_sym
  strategy = :plan unless %i[plan react].include?(strategy)
  definition.instance_variable_set(:@planning_strategy, strategy)

  # Workflow-specific sub-agent lists
  definition.instance_variable_set(:@sequential_sub_agent_names, convert_to_set.call(:sequential_sub_agent_names))
  definition.instance_variable_set(:@parallel_sub_agent_names, convert_to_set.call(:parallel_sub_agent_names))
  definition.instance_variable_set(:@loop_sub_agent_names, convert_to_set.call(:loop_sub_agent_names))

  # Loop configuration
  loop_max = hash_data[:loop_max_iterations] || hash_data['loop_max_iterations']
  definition.instance_variable_set(:@loop_max_iterations, loop_max&.to_i)

  loop_key = hash_data[:loop_condition_state_key] || hash_data['loop_condition_state_key']
  definition.instance_variable_set(:@loop_condition_state_key, loop_key&.to_sym)

  loop_value = hash_data[:loop_condition_expected_value] || hash_data['loop_condition_expected_value']
  definition.instance_variable_set(:@loop_condition_expected_value, loop_value)

  # Delegation targets
  definition.instance_variable_set(:@delegation_targets, convert_to_set.call(:delegation_targets))

  # --- Authentication fields ---
  # Auth credential names (convert to Set of symbols)
  definition.instance_variable_set(:@auth_credential_names, convert_to_set.call(:auth_credential_names))

  # Auth URL mappings (array of hashes)
  auth_mappings_raw = hash_data[:auth_url_mappings] || hash_data['auth_url_mappings'] || []
  if auth_mappings_raw.is_a?(String)
    begin
      auth_mappings_raw = JSON.parse(auth_mappings_raw)
    rescue JSON::ParserError
      auth_mappings_raw = []
    end
  end
  auth_url_mappings = (auth_mappings_raw || []).map do |m|
    pattern = m['pattern'] || m[:pattern]
    pattern_type = m['pattern_type'] || m[:pattern_type]
    # Convert back to Regexp if it was serialized as such
    if pattern_type == 'regexp' && pattern.is_a?(String)
      if pattern.length > 500
        Legate.logger.warn("AgentDefinition.from_h: Rejecting oversized regex pattern (#{pattern.length} chars)")
      else
        begin
          pattern = Regexp.new(pattern, timeout: 1)
        rescue RegexpError
          # Keep as string if invalid regexp
        end
      end
    end
    {
      pattern: pattern,
      scheme_name: (m['scheme_name'] || m[:scheme_name])&.to_sym,
      credential_name: (m['credential_name'] || m[:credential_name])&.to_sym
    }
  end
  definition.instance_variable_set(:@auth_url_mappings, auth_url_mappings)

  # Auth scheme assignments (hash of symbol -> symbol)
  auth_scheme_raw = hash_data[:auth_scheme_assignments] || hash_data['auth_scheme_assignments'] || {}
  if auth_scheme_raw.is_a?(String)
    begin
      auth_scheme_raw = JSON.parse(auth_scheme_raw)
    rescue JSON::ParserError
      auth_scheme_raw = {}
    end
  end
  auth_scheme_assignments = (auth_scheme_raw || {}).transform_keys(&:to_sym).transform_values(&:to_sym)
  definition.instance_variable_set(:@auth_scheme_assignments, auth_scheme_assignments)

  # Auth credential assignments (hash of symbol -> symbol)
  auth_cred_raw = hash_data[:auth_credential_assignments] || hash_data['auth_credential_assignments'] || {}
  if auth_cred_raw.is_a?(String)
    begin
      auth_cred_raw = JSON.parse(auth_cred_raw)
    rescue JSON::ParserError
      auth_cred_raw = {}
    end
  end
  auth_credential_assignments = (auth_cred_raw || {}).transform_keys(&:to_sym).transform_values(&:to_sym)
  definition.instance_variable_set(:@auth_credential_assignments, auth_credential_assignments)

  definition.validate!
  definition
end

Instance Method Details

#define(&block) ⇒ Object

DSL method used within ‘Agent.define` block.

Parameters:

  • block (Proc) —

    The block containing the definition DSL calls.



138
139
140
141
142
 
# File 'lib/legate/agent_definition.rb', line 138

def define(&block)
  @proxy.instance_eval(&block)
  validate!
  self
end

#to_h ⇒ Hash

Returns a hash representation suitable for logging or inspection.

Returns:

  • (Hash) 


172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/legate/agent_definition.rb', line 172

def to_h
  {
    name: @name,
    description: @description,
    instruction: @instruction,
    tool_names: @tool_names.to_a,
    model_name: @model_name,
    temperature: @temperature,
    webhook_enabled: @webhook_enabled,
    webhook_validator: @webhook_validator.is_a?(Proc) ? '<Proc>' : @webhook_validator,
    webhook_secret: @webhook_secret ? '<present>' : nil,
    webhook_transformer: @webhook_transformer.is_a?(Proc) ? '<Proc>' : nil,
    webhook_session_extractor: @webhook_session_extractor.is_a?(Proc) ? '<Proc>' : nil,
    fallback_mode: @fallback_mode,
    mcp_servers: @mcp_servers,
    sub_agent_names: @sub_agent_names.to_a, # MAS attribute
    output_key: @output_key, # MAS attribute
    # Adding new MAS attributes for agent hierarchy and workflow
    agent_type: @agent_type || :llm, # Default to :llm if not set
    planning_strategy: @planning_strategy || :plan, # :plan (default) or :react
    sequential_sub_agent_names: @sequential_sub_agent_names&.to_a || [],
    parallel_sub_agent_names: @parallel_sub_agent_names&.to_a || [],
    loop_sub_agent_names: @loop_sub_agent_names&.to_a || [],
    loop_max_iterations: @loop_max_iterations,
    loop_condition_state_key: @loop_condition_state_key,
    loop_condition_expected_value: @loop_condition_expected_value,
    delegation_targets: @delegation_targets&.to_a || [],
    # --- Authentication fields ---
    auth_credential_names: @auth_credential_names&.to_a || [],
    auth_url_mappings: (@auth_url_mappings || []).map do |m|
      {
        pattern: m[:pattern].is_a?(Regexp) ? m[:pattern].source : m[:pattern],
        pattern_type: m[:pattern].is_a?(Regexp) ? 'regexp' : 'string',
        scheme_name: m[:scheme_name]&.to_s,
        credential_name: m[:credential_name]&.to_s
      }
    end,
    auth_scheme_assignments: (@auth_scheme_assignments || {}).transform_keys(&:to_s).transform_values(&:to_s),
    auth_credential_assignments: (@auth_credential_assignments || {}).transform_keys(&:to_s).transform_values(&:to_s)
  }
end

#validate! ⇒ Object

Validates that the definition has all required fields.

Raises:

  • (ArgumentError) —

    If validation fails.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/legate/agent_definition.rb', line 146

def validate!
  raise ArgumentError, 'Agent definition must have a name.' if @name.nil? || @name.to_s.strip.empty?
  raise ArgumentError, 'Agent name must be a Symbol.' unless @name.is_a?(Symbol)

  # Instruction is optional: a tool-only agent doesn't need a hand-written
  # system prompt, so derive a sensible default from the name/description
  # rather than failing the build.
  if @instruction.nil? || @instruction.strip.empty?
    description = @description.to_s.strip
    @instruction = "You are the #{@name} agent.#{description.empty? ? '' : " #{description}"} " \
                   'Use the available tools to help the user.'
  end

  # Explicitly check instance variable to bypass potential method resolution issues
  return unless @webhook_enabled

  # raise ArgumentError, "Agent '#{@name}' enabled for webhooks must define a webhook_transformer." unless @webhook_transformer.is_a?(Proc)
  # raise ArgumentError, "Agent '#{@name}' enabled for webhooks must define a webhook_session_extractor." unless @webhook_session_extractor.is_a?(Proc)
  Legate.logger.warn { "Agent '#{@name}' is webhook_enabled but lacks a valid :webhook_transformer Proc." } unless @webhook_transformer.is_a?(Proc)
  return if @webhook_session_extractor.is_a?(Proc)

  Legate.logger.warn { "Agent '#{@name}' is webhook_enabled but lacks a valid :webhook_session_extractor Proc." }
end