Class: Ragents::Tool

Inherits:
Object
  • Object
show all
Defined in:
lib/ragents/tool.rb

Overview

Tool definition for agent actions. Tools are declarative definitions of callable functions that agents can invoke.

Examples:

tool = Ragents::Tool.new(:search_web) do
  description "Search the web for information"
  parameter :query, type: :string, required: true, description: "Search query"
  parameter :limit, type: :integer, default: 10

  execute do |query:, limit:|
    # Search implementation
  end
end

Defined Under Namespace

Classes: Parameter

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, &block) ⇒ Tool

Returns a new instance of Tool.



21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/ragents/tool.rb', line 21

def initialize(name, &block)
  @name = name.to_sym
  @description_text = nil
  @parameters = {}
  @executor = nil
  @ractor_safe = true

  instance_eval(&block) if block_given?

  validate!
  freeze_for_ractor!
end

Instance Attribute Details

#description_text ⇒ Object (readonly)

Returns the value of attribute description_text.



19
20
21
 
# File 'lib/ragents/tool.rb', line 19

def description_text
  @description_text
end

#executor ⇒ Object (readonly)

Returns the value of attribute executor.



19
20
21
 
# File 'lib/ragents/tool.rb', line 19

def executor
  @executor
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



19
20
21
 
# File 'lib/ragents/tool.rb', line 19

def name
  @name
end

#parameters ⇒ Object (readonly)

Returns the value of attribute parameters.



19
20
21
 
# File 'lib/ragents/tool.rb', line 19

def parameters
  @parameters
end

Instance Method Details

#call(**args) ⇒ Object

Call the tool with arguments



66
67
68
69
 
# File 'lib/ragents/tool.rb', line 66

def call(**args)
  validated_args = validate_and_coerce_args(args)
  @executor.call(**validated_args)
end

#description(text) ⇒ Object

DSL: Set description



35
36
37
 
# File 'lib/ragents/tool.rb', line 35

def description(text)
  @description_text = text
end

#execute(&block) ⇒ Object

DSL: Define the execution block



52
53
54
 
# File 'lib/ragents/tool.rb', line 52

def execute(&block)
  @executor = block
end

#parameter(name, type:, required: false, description: nil, default: nil, enum: nil) ⇒ Object

DSL: Define a parameter



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/ragents/tool.rb', line 40

def parameter(name, type:, required: false, description: nil, default: nil, enum: nil)
  @parameters[name.to_sym] = Parameter.new(
    name: name.to_sym,
    type: type,
    required: required,
    description: description,
    default: default,
    enum: enum
  )
end

#parameters_schema ⇒ Object

Parameters as JSON Schema object



93
94
95
96
97
98
99
100
101
 
# File 'lib/ragents/tool.rb', line 93

def parameters_schema
  required_params = @parameters.select { |_, p| p.required }.keys.map(&:to_s)

  {
    type: "object",
    properties: @parameters.transform_values(&:to_json_schema).transform_keys(&:to_s),
    required: required_params
  }
end

#ractor_safe? ⇒ Boolean

Returns:

  • (Boolean) 


61
62
63
 
# File 'lib/ragents/tool.rb', line 61

def ractor_safe?
  @ractor_safe
end

#requires_main_thread! ⇒ Object

DSL: Mark as requiring main thread (not Ractor-safe)



57
58
59
 
# File 'lib/ragents/tool.rb', line 57

def requires_main_thread!
  @ractor_safe = false
end

#to_anthropic_schema ⇒ Object

Generate Anthropic tool format



84
85
86
87
88
89
90
 
# File 'lib/ragents/tool.rb', line 84

def to_anthropic_schema
  {
    name: @name.to_s,
    description: @description_text,
    input_schema: parameters_schema
  }
end

#to_json_schema ⇒ Object

Generate JSON Schema for this tool (OpenAI function format)



72
73
74
75
76
77
78
79
80
81
 
# File 'lib/ragents/tool.rb', line 72

def to_json_schema
  {
    type: "function",
    function: {
      name: @name.to_s,
      description: @description_text,
      parameters: parameters_schema
    }
  }
end