Class: TurnKit::Agent

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [], system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil, max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil, output_schema: nil, output_audit: nil, output_audit_mode: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, on_event: nil) ⇒ Agent

Returns a new instance of Agent.

Raises:

  • (ArgumentError) 


10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/turnkit/agent.rb', line 10

def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
  system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
  max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil,
  output_schema: nil, output_audit: nil, output_audit_mode: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, on_event: nil)
  @name = name.to_s
  @description = description.to_s
  @model = model
  @instructions = instructions.to_s
  @tools = Array(tools)
  @skills = Array(skills)
  @available_skills = Array(available_skills)
  @sub_agents = Array(sub_agents)
  @system_prompt = system_prompt
  @prompt_sections = prompt_sections
  @prompt_mode = prompt_mode&.to_sym
  @client = client
  @store = store
  @max_iterations = max_iterations
  @timeout = timeout
  @cost_limit = cost_limit
  @max_depth = max_depth
  @max_tool_executions = max_tool_executions
  @max_tool_executions_by_name = max_tool_executions_by_name
  @thinking = self.class.normalize_thinking(thinking)
  @compaction = compaction
  @output_schema = output_schema
  @output_policy_model = output_policy_model
  @output_audit = normalize_output_policy_options(output_audit: output_audit, output_policy: output_policy, output_policy_model: output_policy_model, output_policy_thinking: output_policy_thinking)
  @output_audit_mode = normalize_output_policy_mode(output_audit_mode: output_audit_mode, output_policy_mode: output_policy_mode)
  @on_event = on_event
  raise ArgumentError, "name is required" if @name.empty?
  validate_tools!
end

Instance Attribute Details

#available_skills ⇒ Object (readonly)

Returns the value of attribute available_skills.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def available_skills
  @available_skills
end

#client ⇒ Object (readonly)

Returns the value of attribute client.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def client
  @client
end

#compaction ⇒ Object (readonly)

Returns the value of attribute compaction.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def compaction
  @compaction
end

#cost_limit ⇒ Object (readonly)

Returns the value of attribute cost_limit.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def cost_limit
  @cost_limit
end

#description ⇒ Object (readonly)

Returns the value of attribute description.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def description
  @description
end

#instructions ⇒ Object (readonly)

Returns the value of attribute instructions.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def instructions
  @instructions
end

#max_depth ⇒ Object (readonly)

Returns the value of attribute max_depth.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def max_depth
  @max_depth
end

#max_iterations ⇒ Object (readonly)

Returns the value of attribute max_iterations.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def max_iterations
  @max_iterations
end

#max_tool_executions ⇒ Object (readonly)

Returns the value of attribute max_tool_executions.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def max_tool_executions
  @max_tool_executions
end

#max_tool_executions_by_name ⇒ Object (readonly)

Returns the value of attribute max_tool_executions_by_name.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def max_tool_executions_by_name
  @max_tool_executions_by_name
end

#model ⇒ Object (readonly)

Returns the value of attribute model.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def model
  @model
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def name
  @name
end

#on_event ⇒ Object (readonly)

Returns the value of attribute on_event.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def on_event
  @on_event
end

#output_audit ⇒ Object (readonly)

Returns the value of attribute output_audit.



8
9
10
 
# File 'lib/turnkit/agent.rb', line 8

def output_audit
  @output_audit
end

#output_audit_mode ⇒ Object (readonly)

Returns the value of attribute output_audit_mode.



8
9
10
 
# File 'lib/turnkit/agent.rb', line 8

def output_audit_mode
  @output_audit_mode
end

#output_policy_model ⇒ Object (readonly)

Returns the value of attribute output_policy_model.



8
9
10
 
# File 'lib/turnkit/agent.rb', line 8

def output_policy_model
  @output_policy_model
end

#output_schema ⇒ Object (readonly)

Returns the value of attribute output_schema.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def output_schema
  @output_schema
end

#prompt_mode ⇒ Object (readonly)

Returns the value of attribute prompt_mode.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def prompt_mode
  @prompt_mode
end

#prompt_sections ⇒ Object (readonly)

Returns the value of attribute prompt_sections.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def prompt_sections
  @prompt_sections
end

#skills ⇒ Object (readonly)

Returns the value of attribute skills.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def skills
  @skills
end

#store ⇒ Object (readonly)

Returns the value of attribute store.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def store
  @store
end

#sub_agents ⇒ Object (readonly)

Returns the value of attribute sub_agents.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def sub_agents
  @sub_agents
end

#system_prompt ⇒ Object (readonly)

Returns the value of attribute system_prompt.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def system_prompt
  @system_prompt
end

#thinking ⇒ Object (readonly)

Returns the value of attribute thinking.



7
8
9
 
# File 'lib/turnkit/agent.rb', line 7

def thinking
  @thinking
end

#timeout ⇒ Object (readonly)

Returns the value of attribute timeout.



6
7
8
 
# File 'lib/turnkit/agent.rb', line 6

def timeout
  @timeout
end

#tools ⇒ Object (readonly)

Returns the value of attribute tools.



5
6
7
 
# File 'lib/turnkit/agent.rb', line 5

def tools
  @tools
end

Class Method Details

.normalize_thinking(value) ⇒ Object

Raises:

  • (ArgumentError) 


44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/turnkit/agent.rb', line 44

def self.normalize_thinking(value)
  return nil if value.nil?

  attrs = value.respond_to?(:to_h) ? value.to_h : value
  raise ArgumentError, "thinking must be a hash" unless attrs.is_a?(Hash)

  attrs = attrs.transform_keys(&:to_sym)
  unknown = attrs.keys - %i[effort budget]
  raise ArgumentError, "unknown thinking attributes: #{unknown.join(", ")}" if unknown.any?
  raise ArgumentError, "thinking requires :effort or :budget" if attrs[:effort].nil? && attrs[:budget].nil?
  raise ArgumentError, "thinking budget must be an Integer" if attrs[:budget] && !attrs[:budget].is_a?(Integer)

  attrs.slice(:effort, :budget).compact
end

Instance Method Details

#build_budget(root_started_at: Clock.now) ⇒ Object 



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/turnkit/agent.rb', line 157

def build_budget(root_started_at: Clock.now)
  Budget.new(
    max_iterations: max_iterations || TurnKit.max_iterations,
    timeout: timeout || TurnKit.timeout,
    max_depth: max_depth || TurnKit.max_depth,
    max_tool_executions: max_tool_executions || TurnKit.max_tool_executions,
    max_tool_executions_by_name: max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
    cost_limit: cost_limit || TurnKit.cost_limit,
    root_started_at: root_started_at
  )
end

#conversation(model: nil, subject: nil, metadata: {}) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
 
# File 'lib/turnkit/agent.rb', line 59

def conversation(model: nil, subject: nil, metadata: {})
  store = effective_store
  record = store.create_conversation(
    "agent_name" => name,
    "model" => model || effective_model,
    "subject" => subject,
    "metadata" => metadata
  )
  Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
end

#cost ⇒ Object 



86
87
88
 
# File 'lib/turnkit/agent.rb', line 86

def cost
  Cost.from_records(effective_store.list_turns(agent_name: name))
end

#effective_available_skills ⇒ Object 



130
131
132
 
# File 'lib/turnkit/agent.rb', line 130

def effective_available_skills
  (Array(TurnKit.available_skills) + available_skills).uniq { |skill| skill.key }
end

#effective_client ⇒ Object 



114
115
116
 
# File 'lib/turnkit/agent.rb', line 114

def effective_client
  client || TurnKit.client
end

#effective_model ⇒ Object 



94
95
96
 
# File 'lib/turnkit/agent.rb', line 94

def effective_model
  model || TurnKit.default_model
end

#effective_on_event ⇒ Object 



126
127
128
 
# File 'lib/turnkit/agent.rb', line 126

def effective_on_event
  on_event || TurnKit.on_event
end

#effective_output_audit ⇒ Object 



102
103
104
 
# File 'lib/turnkit/agent.rb', line 102

def effective_output_audit
  Array(output_audit).compact
end

#effective_prompt_mode(turn: nil) ⇒ Object 



138
139
140
141
142
 
# File 'lib/turnkit/agent.rb', line 138

def effective_prompt_mode(turn: nil)
  return prompt_mode if prompt_mode

  turn&.depth.to_i.positive? ? :minimal : :full
end

#effective_prompt_sections ⇒ Object 



134
135
136
 
# File 'lib/turnkit/agent.rb', line 134

def effective_prompt_sections
  prompt_sections || TurnKit.prompt_sections
end

#effective_store ⇒ Object 



118
119
120
 
# File 'lib/turnkit/agent.rb', line 118

def effective_store
  store || TurnKit.store
end

#effective_thinking ⇒ Object 



98
99
100
 
# File 'lib/turnkit/agent.rb', line 98

def effective_thinking
  thinking
end

#effective_tools ⇒ Object 



122
123
124
 
# File 'lib/turnkit/agent.rb', line 122

def effective_tools
  tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
end

#instructions_with_skills ⇒ Object 



169
170
171
172
173
 
# File 'lib/turnkit/agent.rb', line 169

def instructions_with_skills
  parts = [ instructions ]
  parts << SystemPrompt.loaded_skills_text(skills)
  parts.reject(&:empty?).join("\n\n")
end

#output_policy ⇒ Object 



106
107
108
 
# File 'lib/turnkit/agent.rb', line 106

def output_policy
  output_audit
end

#output_policy_mode ⇒ Object 



110
111
112
 
# File 'lib/turnkit/agent.rb', line 110

def output_policy_mode
  output_audit_mode
end

#run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options) ⇒ Object

Raises:

  • (ArgumentError) 


70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/turnkit/agent.rb', line 70

def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
  task = task || prompt
  raise ArgumentError, "task is required" if task.to_s.empty?

  conversation = self.conversation(subject: subject, metadata: metadata)
  message = conversation.say(task_message(task, input), metadata: { "source" => "application", "task" => true })
  turn = conversation.build_turn(
    trigger_message_id: message.id,
    root_turn_id: root_turn_id || parent_run_root_turn_id(parent_run),
    prompt_mode: prompt_mode,
    **options
  )
  run = Run.new(turn)
  async ? run : run.run!
end

#system_prompt_for(turn:, conversation:) ⇒ Object 



144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/turnkit/agent.rb', line 144

def system_prompt_for(turn:, conversation:)
  prompt = SystemPrompt.new(agent: self, turn: turn, conversation: conversation, mode: effective_prompt_mode(turn: turn))

  case system_prompt
  when nil
    prompt.to_s
  when String
    system_prompt
  else
    system_prompt.call(prompt).to_s
  end
end

#usage ⇒ Object 



90
91
92
 
# File 'lib/turnkit/agent.rb', line 90

def usage
  Usage.from_records(effective_store.list_turns(agent_name: name))
end