Class: ActiveAgent::Delegation::Contract

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

Overview

What a sub-agent promises: one action, its inputs, and optionally the shape of what it returns.

The contract is declared on the sub-agent itself, next to the action it describes, so a delegation stays correct when the action changes. Callers then say only which agent they want — they never restate its parameters.

Examples:

class SummarizerAgent < ApplicationAgent
  delegation :summarize, description: "Condense a document into key points" do
    string  :text, required: true, description: "Full document text"
    integer :limit, description: "Maximum number of key points"

    returns do
      string :summary, required: true, description: "One-paragraph summary"
      array  :points, of: :string, required: true, description: "Key points"
    end
  end

  def summarize(text:, limit: 5)
    prompt(message: text, limit: limit)
  end
end

Defined Under Namespace

Classes: DSL

Constant Summary collapse

INVALID_POLICIES =

What to do when a sub-agent's output does not satisfy its returns schema.

:error — hand the calling model a structured error so it can retry or route around the failure (default). :raise — raise InvalidResultError and abort the generation.

%i[error raise].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(action:, description:, schema: nil, returns: nil, budget: nil, on_invalid: :error) { ... } ⇒ Contract

Returns a new instance of Contract.

Parameters:

  • action (Symbol, String)
  • description (String)
  • schema (Schema, Hash, Class, nil) (defaults to: nil) —

    inputs, or nil to use the block DSL

  • returns (Schema, Hash, Class, nil) (defaults to: nil) —

    declared output shape

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

    default budget for callers

  • on_invalid (Symbol) (defaults to: :error) —

    :error or :raise

Yields:

  • input DSL; may also call returns to declare the output shape

Raises:

  • (ArgumentError) 


58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/active_agent/delegation/contract.rb', line 58

def initialize(action:, description:, schema: nil, returns: nil, budget: nil, on_invalid: :error, &block)
  @action      = action.to_sym
  @description = description
  @returns     = returns && Schema.build(returns)
  @budget      = Budget.build(budget)
  @on_invalid  = on_invalid.to_sym

  unless INVALID_POLICIES.include?(@on_invalid)
    raise ArgumentError, "Unknown delegation on_invalid policy #{@on_invalid.inspect}. " \
      "Valid policies: #{INVALID_POLICIES.join(", ")}"
  end

  raise ArgumentError, "A delegation needs a description — it is the only thing the calling model reads" if @description.blank?

  @schema = Schema.build(schema)

  if block
    dsl = DSL.new(self, @schema)
    block.arity == 1 ? block.call(dsl) : dsl.instance_eval(&block)
  end
end

Instance Attribute Details

#action ⇒ Symbol (readonly)

Returns the sub-agent action this contract describes.

Returns:

  • (Symbol) —

    the sub-agent action this contract describes



39
40
41
 
# File 'lib/active_agent/delegation/contract.rb', line 39

def action
  @action
end

#budget ⇒ Budget (readonly)

Returns default budget suggested by the sub-agent.

Returns:

  • (Budget) —

    default budget suggested by the sub-agent



47
48
49
 
# File 'lib/active_agent/delegation/contract.rb', line 47

def budget
  @budget
end

#description ⇒ String (readonly)

Returns what the action does, written for the calling model.

Returns:

  • (String) —

    what the action does, written for the calling model



41
42
43
 
# File 'lib/active_agent/delegation/contract.rb', line 41

def description
  @description
end

#on_invalid ⇒ Symbol (readonly)

Returns :error or :raise.

Returns:

  • (Symbol) —

    :error or :raise



49
50
51
 
# File 'lib/active_agent/delegation/contract.rb', line 49

def on_invalid
  @on_invalid
end

#returns ⇒ Schema?

Returns declared output shape, when the action returns structured data.

Returns:

  • (Schema, nil) —

    declared output shape, when the action returns structured data



45
46
47
 
# File 'lib/active_agent/delegation/contract.rb', line 45

def returns
  @returns
end

#schema ⇒ Schema (readonly)

Returns declared inputs.

Returns:

  • (Schema) —

    declared inputs



43
44
45
 
# File 'lib/active_agent/delegation/contract.rb', line 43

def schema
  @schema
end

Instance Method Details

#structured? ⇒ Boolean

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/active_agent/delegation/contract.rb', line 81

def structured?
  returns.present?
end