Class: LanguageOperator::Dsl::AgentDefinition

Inherits:
Object
  • Object
show all
Includes:
Loggable
Defined in:
lib/language_operator/dsl/agent_definition.rb

Overview

Agent definition for autonomous agents

Defines an agent with objectives, tasks, main execution block, schedule, and constraints. Used within the DSL to create agents that can be executed standalone or deployed to Kubernetes.

Examples:

Define a simple scheduled agent

agent "news-summarizer" do
  description "Daily news summarization agent"

  schedule "0 12 * * *"

  task :search,
    instructions: "search for latest news",
    inputs: {},
    outputs: { results: 'array' }

  main do |inputs|
    results = execute_task(:search)
    results
  end
end

Define a webhook agent

agent "github-webhook" do
  description "Handle GitHub webhooks"
  mode :reactive

  webhook "/github/pr-opened" do
    method :post
    on_request do |context|
      # Process webhook
    end
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Loggable

#logger

Constructor Details

#initialize(name) ⇒ AgentDefinition

Returns a new instance of AgentDefinition.



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 53

def initialize(name)
  @name = name
  @description = nil
  @persona = nil
  @schedule = nil
  @objectives = []
  @main = nil
  @tasks = {}
  @constraints = {}
  @output_config = nil
  @execution_mode = :autonomous
  @webhooks = []
  @mcp_server = nil

  logger.debug('Agent definition initialized',
               name: name,
               mode: @execution_mode)
end

Instance Attribute Details

#constraints { ... } ⇒ Hash (readonly)

Define constraints (max_iterations, timeout, etc.)

Yields:

  • Constraints block

Returns:

  • Current constraints



216
217
218
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 216

def constraints
  @constraints
end

#description(val = nil) ⇒ String (readonly)

Set or get description

Parameters:

  • (defaults to: nil)

    Description text

Returns:

  • Current description



76
77
78
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 76

def description
  @description
end

#execution_mode ⇒ Object (readonly)

Returns the value of attribute execution_mode.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def execution_mode
  @execution_mode
end

#main { ... } ⇒ MainDefinition (readonly)

Define main execution block (DSL v1)

The main block is the imperative entry point for agent execution. It receives agent inputs and returns agent outputs. Use execute_task() to call organic functions (tasks) defined with the task directive.

Examples:

main do |inputs|
  result = execute_task(:fetch_data, inputs: inputs)
  execute_task(:process_data, inputs: result)
end

Yields:

  • Main execution block

Returns:

  • Current main definition



134
135
136
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 134

def main
  @main
end

#mcp_server ⇒ Object (readonly)

Returns the value of attribute mcp_server.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def mcp_server
  @mcp_server
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def name
  @name
end

#objectives(list = nil) ⇒ Array<String> (readonly)

Set objectives (list of goals)

Parameters:

  • (defaults to: nil)

    List of objectives

Returns:

  • Current objectives



107
108
109
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 107

def objectives
  @objectives
end

#output_config ⇒ Object (readonly)

Returns the value of attribute output_config.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def output_config
  @output_config
end

#persona(text = nil) ⇒ String (readonly)

Set persona/system prompt

Parameters:

  • (defaults to: nil)

    Persona text or system prompt

Returns:

  • Current persona



86
87
88
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 86

def persona
  @persona
end

#schedule(cron = nil) ⇒ String (readonly)

Set schedule (cron expression)

Parameters:

  • (defaults to: nil)

    Cron expression

Returns:

  • Current schedule



96
97
98
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 96

def schedule
  @schedule
end

#tasks ⇒ Object (readonly)

Returns the value of attribute tasks.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def tasks
  @tasks
end

#webhooks ⇒ Object (readonly)

Returns the value of attribute webhooks.



50
51
52
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 50

def webhooks
  @webhooks
end

Instance Method Details

#as_mcp_server { ... } ⇒ McpServerDefinition

Define MCP server capabilities

Allows this agent to expose tools via MCP protocol. Other agents or MCP clients can discover and call these tools.

Yields:

  • MCP server configuration block

Returns:

  • The MCP server definition



308
309
310
311
312
313
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 308

def as_mcp_server(&block)
  @mcp_server = McpServerDefinition.new(@name)
  @mcp_server.instance_eval(&block) if block
  @execution_mode = :reactive if @execution_mode == :autonomous
  @mcp_server
end

#mode(mode = nil) ⇒ Symbol

Set execution mode

Parameters:

  • (defaults to: nil)

    Execution mode (:autonomous, :scheduled, :reactive)

Returns:

  • Current execution mode



282
283
284
285
286
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 282

def mode(mode = nil)
  return @execution_mode if mode.nil?

  @execution_mode = mode
end

#objective(text) ⇒ void

This method returns an undefined value.

Define a single objective

Parameters:

  • Objective text



117
118
119
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 117

def objective(text)
  @objectives << text
end

#output(**options) {|outputs| ... } ⇒ TaskDefinition

Define output handler (organic function) - DSL v1

The output is an organic function that receives the final outputs from main execution and handles them (logging, saving to workspace, notifications, etc.). Like tasks, it can be neural (instructions-based), symbolic (code block), or hybrid (both).

Examples:

Neural output

output instructions: "save results to workspace as JSON"

Symbolic output

output do |outputs|
  File.write("/workspace/result.json", JSON.pretty_generate(outputs))
end

Hybrid output

output instructions: "save results to workspace" do |outputs|
  File.write("/workspace/result.json", outputs.to_json)
end

Parameters:

  • Output configuration

Options Hash (**options):

  • :instructions (String) —

    Natural language instructions (neural)

Yields:

  • (outputs) —

    Symbolic implementation block (optional)

Yield Parameters:

  • outputs (Hash) —

    The outputs returned from main execution

Returns:

  • The output task definition



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 248

def output(**options, &block)
  return @output_config if options.empty? && block.nil?

  # Create a TaskDefinition for output (it's an organic function)
  output_task = TaskDefinition.new(:output)

  # Output task always receives main's outputs as inputs (type: any)
  # No need to specify inputs - they come from main

  # Configure instructions if provided (neural)
  output_task.instructions(options[:instructions]) if options[:instructions]

  # Symbolic implementation (if block provided)
  output_task.execute(&block) if block

  @output_config = output_task

  task_type = if output_task.neural? && output_task.symbolic?
                'hybrid'
              elsif output_task.neural?
                'neural'
              else
                'symbolic'
              end

  logger.debug('Output defined', type: task_type)

  output_task
end

#run! ⇒ void

This method returns an undefined value.

Execute the agent



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 319

def run!
  logger.info('Starting agent',
              name: @name,
              mode: @execution_mode,
              objectives_count: @objectives.size,
              has_main: !@main.nil?)

  case @execution_mode
  when :scheduled
    run_scheduled
  when :autonomous
    run_autonomous
  when :reactive
    run_reactive
  else
    logger.error('Unknown execution mode', mode: @execution_mode)
    raise "Unknown execution mode: #{@execution_mode}"
  end
end

#task(name, **options) {|inputs| ... } ⇒ TaskDefinition

Define a task (organic function) - DSL v1

Tasks are the core primitive of DSL v1, representing organic functions with stable input/output contracts. Tasks can be neural (instructions-based), symbolic (code-based), or hybrid (both).

Examples:

Neural task

task :analyze_data,
  instructions: "Analyze the data for anomalies",
  inputs: { data: 'array' },
  outputs: { issues: 'array', summary: 'string' }

Symbolic task

task :calculate_total,
  inputs: { items: 'array' },
  outputs: { total: 'number' }
do |inputs|
  { total: inputs[:items].sum { |i| i['amount'] } }
end

Hybrid task

task :fetch_user,
  instructions: "Fetch user from database",
  inputs: { user_id: 'integer' },
  outputs: { user: 'hash' }
do |inputs|
  execute_tool('database', 'get_user', id: inputs[:user_id])
end

Parameters:

  • Task name

  • Task configuration

Options Hash (**options):

  • :inputs (Hash) —

    Input schema (param => type)

  • :outputs (Hash) —

    Output schema (field => type)

  • :instructions (String) —

    Natural language instructions (neural)

Yields:

  • (inputs) —

    Symbolic implementation block (optional)

Yield Parameters:

  • inputs (Hash) —

    Validated input parameters

Yield Returns:

  • (Hash) —

    Output matching outputs schema

Returns:

  • The task definition



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
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 180

def task(name, **options, &block)
  # Create task definition
  task_def = TaskDefinition.new(name)

  # Configure from options (keyword arguments)
  task_def.inputs(options[:inputs]) if options[:inputs]
  task_def.outputs(options[:outputs]) if options[:outputs]
  task_def.instructions(options[:instructions]) if options[:instructions]

  # Symbolic implementation (if block provided)
  task_def.execute(&block) if block

  # Store in tasks collection
  @tasks[name] = task_def

  task_type = if task_def.neural? && task_def.symbolic?
                'hybrid'
              elsif task_def.neural?
                'neural'
              else
                'symbolic'
              end

  logger.debug('Task defined',
               name: name,
               type: task_type,
               inputs: options[:inputs]&.keys || [],
               outputs: options[:outputs]&.keys || [])

  task_def
end

#webhook(path) { ... } ⇒ WebhookDefinition

Define a webhook endpoint

Parameters:

  • URL path for the webhook

Yields:

  • Webhook configuration block

Returns:

  • The webhook definition



293
294
295
296
297
298
299
 
# File 'lib/language_operator/dsl/agent_definition.rb', line 293

def webhook(path, &block)
  webhook_def = WebhookDefinition.new(path)
  webhook_def.instance_eval(&block) if block
  @webhooks << webhook_def
  @execution_mode = :reactive if @execution_mode == :autonomous
  webhook_def
end