Class: Ask::Agent::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/agent/definition.rb

Overview

Declarative agent definition backed by a file convention.

Subclass Definition inside an agent.rb file under agents/<name>/ or app/agents/<name>/. The directory name becomes the agent name. Instructions load automatically from a sibling instructions.md.

Examples:

agents/health_check/agent.rb

module HealthCheck
  class Agent < Ask::Agent::Definition
    model "gpt-4o"
    tools :bash, :read, :grep
    schedule "every 5 minutes"
  end
end

# agents/health_check/instructions.md is auto-loaded

Using from Ruby

agent = Ask::Agent.new("health_check")
agent.run("Check server health")

Class Method Summary collapse

Class Method Details

._config ⇒ Hash

Returns the raw config hash for this definition.

Returns:

  • (Hash) —

    the raw config hash for this definition



55
56
57
 
# File 'lib/ask/agent/definition.rb', line 55

def _config
  @_config ||= { tools: [] }
end

.inherited(subclass) ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/ask/agent/definition.rb', line 36

def inherited(subclass)
  # Track on Definition itself, not self — inherited fires with the
  # immediate parent as receiver, so an intermediate base class
  # (e.g. an ApplicationAgent in a Rails app) would otherwise have a
  # nil @subclasses ivar.
  Definition.subclasses << subclass
  subclass.instance_variable_set(:@_config, { tools: [] })

  # Auto-detect the directory from the file where this class is defined
  # caller(1) is the file containing the `class ... < Definition` line
  path = caller(1)&.first&.sub(/:.*/, "")  # strip line number
  if path && File.basename(path) == "agent.rb"
    subclass._config[:dir] = File.dirname(path)
  end

  super
end

.instructions_content ⇒ Object

Contents of the instructions.md file, or nil.



140
141
142
143
 
# File 'lib/ask/agent/definition.rb', line 140

def instructions_content
  path = instructions_path
  path ? File.read(path) : nil
end

.instructions_path ⇒ Object

Path to instructions.md relative to this definition's directory. Returns nil if no instructions file exists.



131
132
133
134
135
136
137
 
# File 'lib/ask/agent/definition.rb', line 131

def instructions_path
  dir = _config[:dir]
  return nil unless dir

  path = File.join(dir, "instructions.md")
  File.exist?(path) ? path : nil
end

.max_turns(value = :__no_value__) ⇒ Object

Set or get max turns for the session.



78
79
80
81
82
83
84
 
# File 'lib/ask/agent/definition.rb', line 78

def max_turns(value = :__no_value__)
  if value == :__no_value__
    _config[:max_turns]
  else
    _config[:max_turns] = value
  end
end

.model(value = :__no_value__) ⇒ Object

Set or get the model identifier.



60
61
62
63
64
65
66
 
# File 'lib/ask/agent/definition.rb', line 60

def model(value = :__no_value__)
  if value == :__no_value__
    _config[:model]
  else
    _config[:model] = value
  end
end

.option(key, value = :__no_value__) ⇒ Object

Set an arbitrary Session option. Accepts any key that Ask::Agent::Session.new understands.

option :temperature, 0.7
option :reflector, true
option :telemetry, false


101
102
103
104
105
106
107
108
109
 
# File 'lib/ask/agent/definition.rb', line 101

def option(key, value = :__no_value__)
  if value == :__no_value__
    _config[:options] ||= {}
    _config[:options][key]
  else
    _config[:options] ||= {}
    _config[:options][key] = value
  end
end

.parallel_tools(value = :__no_value__) ⇒ Object

Set or get parallel tool execution flag.



87
88
89
90
91
92
93
 
# File 'lib/ask/agent/definition.rb', line 87

def parallel_tools(value = :__no_value__)
  if value == :__no_value__
    _config.key?(:parallel_tools) ? _config[:parallel_tools] : true
  else
    _config[:parallel_tools] = value
  end
end

.provider(value = :__no_value__) ⇒ Object

Set or get the provider override.



69
70
71
72
73
74
75
 
# File 'lib/ask/agent/definition.rb', line 69

def provider(value = :__no_value__)
  if value == :__no_value__
    _config[:provider]
  else
    _config[:provider] = value
  end
end

.schedule(value = :__no_value__) ⇒ Object

Set a cron or interval schedule for recurring runs.



121
122
123
124
125
126
127
 
# File 'lib/ask/agent/definition.rb', line 121

def schedule(value = :__no_value__)
  if value == :__no_value__
    _config[:schedule]
  else
    _config[:schedule] = value
  end
end

.subclasses ⇒ Object

All subclasses that have been loaded, in definition order. Reads from Definition itself so intermediate base classes (e.g. ApplicationAgent) report the same registry.



32
33
34
 
# File 'lib/ask/agent/definition.rb', line 32

def subclasses
  Definition.instance_variable_get(:@subclasses) || []
end

.tools(*values) ⇒ Object

Set tool symbols or classes.



112
113
114
115
116
117
118
 
# File 'lib/ask/agent/definition.rb', line 112

def tools(*values)
  if values.any?
    _config[:tools] = values
  else
    _config[:tools]
  end
end