Class: ActiveAgent::Delegation::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/active_agent/delegation/definition.rb

Overview

A sub-agent bound into a calling agent as a tool.

Pairs the sub-agent's Contract — what it accepts and returns — with the decisions that belong to the caller: what to call it, what it may spend, and which backend serves it.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(agent_class:, contract:, tool_name: nil, description: nil, backend: nil, budget: nil, params: nil) ⇒ Definition

Returns a new instance of Definition.

Parameters:

  • agent_class (Class)
  • contract (Contract)
  • tool_name (Symbol, String, nil) (defaults to: nil) —

    defaults to the contract's action

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

    overrides the contract's description

  • backend (Backend, Symbol, Hash, nil) (defaults to: nil)
  • budget (Budget, Hash, nil) (defaults to: nil) —

    merged over the contract's default budget

  • params (Hash, Symbol, Proc, nil) (defaults to: nil) 


33
34
35
36
37
38
39
40
41
 
# File 'lib/active_agent/delegation/definition.rb', line 33

def initialize(agent_class:, contract:, tool_name: nil, description: nil, backend: nil, budget: nil, params: nil)
  @agent_class = agent_class
  @contract    = contract
  @tool_name   = (tool_name || contract.action).to_sym
  @description = description.presence || contract.description
  @backend     = Backend.build(backend)
  @budget      = contract.budget.merge(Budget.build(budget))
  @params      = params
end

Instance Attribute Details

#agent_class ⇒ Class (readonly)

Returns the sub-agent class.

Returns:

  • (Class) —

    the sub-agent class



12
13
14
 
# File 'lib/active_agent/delegation/definition.rb', line 12

def agent_class
  @agent_class
end

#backend ⇒ Backend (readonly)

Returns:



20
21
22
 
# File 'lib/active_agent/delegation/definition.rb', line 20

def backend
  @backend
end

#budget ⇒ Budget (readonly)

Returns:



22
23
24
 
# File 'lib/active_agent/delegation/definition.rb', line 22

def budget
  @budget
end

#contract ⇒ Contract (readonly)

Returns:



14
15
16
 
# File 'lib/active_agent/delegation/definition.rb', line 14

def contract
  @contract
end

#description ⇒ String (readonly)

Returns:

  • (String) 


18
19
20
 
# File 'lib/active_agent/delegation/definition.rb', line 18

def description
  @description
end

#params ⇒ Hash, ... (readonly)

Returns params forwarded to the sub-agent.

Returns:

  • (Hash, Symbol, Proc, nil) —

    params forwarded to the sub-agent



24
25
26
 
# File 'lib/active_agent/delegation/definition.rb', line 24

def params
  @params
end

#tool_name ⇒ Symbol (readonly)

Returns the tool name exposed to the calling model.

Returns:

  • (Symbol) —

    the tool name exposed to the calling model



16
17
18
 
# File 'lib/active_agent/delegation/definition.rb', line 16

def tool_name
  @tool_name
end

Instance Method Details

#action ⇒ Symbol

Returns the sub-agent action invoked.

Returns:

  • (Symbol) —

    the sub-agent action invoked



44
 
# File 'lib/active_agent/delegation/definition.rb', line 44

def action = contract.action

#on_invalid ⇒ Symbol

Returns:

  • (Symbol) 


56
 
# File 'lib/active_agent/delegation/definition.rb', line 56

def on_invalid = contract.on_invalid

#resolved_agent_class ⇒ Class

The class a call actually instantiates, after any backend swap.

Returns:

  • (Class) 


61
62
63
 
# File 'lib/active_agent/delegation/definition.rb', line 61

def resolved_agent_class
  backend.agent_class_for(agent_class)
end

#returns ⇒ Schema?

Returns declared outputs.

Returns:

  • (Schema, nil) —

    declared outputs



50
 
# File 'lib/active_agent/delegation/definition.rb', line 50

def returns = contract.returns

#schema ⇒ Schema

Returns declared inputs.

Returns:

  • (Schema) —

    declared inputs



47
 
# File 'lib/active_agent/delegation/definition.rb', line 47

def schema = contract.schema

#structured? ⇒ Boolean

Returns:

  • (Boolean) 


53
 
# File 'lib/active_agent/delegation/definition.rb', line 53

def structured? = contract.structured?

#to_tool ⇒ Hash

Tool definition in ActiveAgent's common tools format.

This is what the calling model sees — the whole point of declaring a schema rather than describing the sub-agent in prose.

Returns:

  • (Hash) 


71
72
73
74
75
76
77
 
# File 'lib/active_agent/delegation/definition.rb', line 71

def to_tool
  {
    name: tool_name.to_s,
    description: description,
    parameters: schema.to_json_schema
  }
end

#with(tool_name: nil, description: nil, backend: nil, budget: nil, params: nil) ⇒ Definition

Returns a copy with call-site overrides applied.

Returns:



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/active_agent/delegation/definition.rb', line 82

def with(tool_name: nil, description: nil, backend: nil, budget: nil, params: nil)
  self.class.new(
    agent_class: agent_class,
    contract: contract,
    tool_name: tool_name || self.tool_name,
    description: description || self.description,
    backend: backend || self.backend,
    budget: budget ? self.budget.merge(Budget.build(budget)) : self.budget,
    params: params || self.params
  )
end