ai-agents 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +15 -0
  3. data/CLAUDE.md +1 -1
  4. data/README.md +3 -3
  5. data/docs/architecture.md +1 -1
  6. data/docs/concepts/agents.md +16 -0
  7. data/docs/concepts/tools.md +1 -1
  8. data/docs/guides/instrumentation.md +54 -5
  9. data/docs/guides/rails-integration.md +2 -2
  10. data/docs/guides/state-persistence.md +2 -2
  11. data/docs/guides/structured-output.md +3 -3
  12. data/examples/collaborative-copilot/tools/create_linear_ticket_tool.rb +5 -5
  13. data/examples/collaborative-copilot/tools/get_article_tool.rb +1 -1
  14. data/examples/collaborative-copilot/tools/get_contact_tool.rb +1 -1
  15. data/examples/collaborative-copilot/tools/get_conversation_tool.rb +1 -1
  16. data/examples/collaborative-copilot/tools/get_stripe_billing_tool.rb +1 -1
  17. data/examples/collaborative-copilot/tools/search_contacts_tool.rb +3 -2
  18. data/examples/collaborative-copilot/tools/search_conversations_tool.rb +2 -2
  19. data/examples/collaborative-copilot/tools/search_knowledge_base_tool.rb +4 -3
  20. data/examples/collaborative-copilot/tools/search_linear_issues_tool.rb +5 -4
  21. data/examples/isp-support/agents_factory.rb +4 -4
  22. data/examples/isp-support/tools/create_checkout_tool.rb +1 -1
  23. data/examples/isp-support/tools/create_lead_tool.rb +3 -3
  24. data/examples/isp-support/tools/crm_lookup_tool.rb +1 -1
  25. data/examples/isp-support/tools/search_docs_tool.rb +1 -1
  26. data/lib/agents/agent.rb +19 -6
  27. data/lib/agents/agent_tool.rb +1 -1
  28. data/lib/agents/handoff.rb +2 -5
  29. data/lib/agents/helpers/message_extractor.rb +32 -8
  30. data/lib/agents/instrumentation/constants.rb +2 -0
  31. data/lib/agents/instrumentation/tracing_callbacks.rb +53 -24
  32. data/lib/agents/run_context.rb +5 -4
  33. data/lib/agents/runner.rb +86 -57
  34. data/lib/agents/tool.rb +8 -1
  35. data/lib/agents/tool_wrapper.rb +22 -13
  36. data/lib/agents/version.rb +1 -1
  37. data/lib/agents.rb +4 -2
  38. metadata +11 -5
@@ -76,20 +76,23 @@ module Agents
76
76
  end
77
77
 
78
78
  def extract_user_or_assistant_message(msg, current_agent)
79
- content_present = message_content?(msg)
80
79
  tool_calls_present = assistant_tool_calls?(msg)
81
- return nil unless content_present || tool_calls_present
80
+ return nil unless extractable_message?(msg, tool_calls_present)
82
81
 
83
- message = {
84
- role: msg.role,
85
- content: content_present ? msg.content : ""
86
- }
82
+ message = { role: msg.role, content: persisted_content(msg) }
87
83
 
88
84
  return message unless msg.role == :assistant
89
85
 
90
86
  attributed_agent_name = attributed_agent_name_for(msg) || current_agent&.name
91
87
  message[:agent_name] = attributed_agent_name if attributed_agent_name
92
88
 
89
+ if msg.respond_to?(:thinking) && msg.thinking&.signature
90
+ message[:thinking] = msg.thinking.text if msg.thinking.text
91
+ message[:thinking_signature] = msg.thinking.signature
92
+ producer = producing_entry(msg)
93
+ message.merge!(thinking_provider: producer.provider, thinking_model: producer.model) if producer
94
+ end
95
+
93
96
  if tool_calls_present
94
97
  # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
95
98
  # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
@@ -99,6 +102,27 @@ module Agents
99
102
  message
100
103
  end
101
104
 
105
+ # RubyLLM replays a thinking signature only to the producer named in the message's usage
106
+ # entries. RubyLLM 2.0 checks the provider, and RubyLLM 2.1 checks the provider and model.
107
+ def producing_entry(msg)
108
+ msg.ruby_llm_usage_entries.reverse.find(&:succeeded?)
109
+ end
110
+
111
+ def persisted_content(msg)
112
+ content = message_content?(msg) ? msg.content : ""
113
+ return content if msg.attachments.empty?
114
+
115
+ parts = content.to_s.empty? ? [] : [{ type: "text", text: content }]
116
+ parts + msg.attachments.map do |attachment|
117
+ { type: "image_url", image_url: { url: attachment.source.to_s } }
118
+ end
119
+ end
120
+
121
+ def extractable_message?(msg, tool_calls_present)
122
+ message_content?(msg) || tool_calls_present || msg.attachments.any? ||
123
+ (msg.role == :assistant && msg.respond_to?(:thinking) && msg.thinking&.signature)
124
+ end
125
+
102
126
  def message_content?(msg)
103
127
  msg.content && !content_empty?(msg.content)
104
128
  end
@@ -117,8 +141,8 @@ module Agents
117
141
  }
118
142
  end
119
143
 
120
- private_class_method :extract_user_or_assistant_message, :message_content?, :assistant_tool_calls?,
121
- :extract_tool_message
144
+ private_class_method :extract_user_or_assistant_message, :producing_entry, :persisted_content,
145
+ :extractable_message?, :message_content?, :assistant_tool_calls?, :extract_tool_message
122
146
  end
123
147
  end
124
148
  end
@@ -19,6 +19,7 @@ module Agents
19
19
  ATTR_GEN_AI_PROVIDER = "gen_ai.provider.name"
20
20
  ATTR_GEN_AI_USAGE_INPUT = "gen_ai.usage.input_tokens"
21
21
  ATTR_GEN_AI_USAGE_OUTPUT = "gen_ai.usage.output_tokens"
22
+ ATTR_GEN_AI_USAGE_REASONING_OUTPUT = "gen_ai.usage.reasoning.output_tokens"
22
23
 
23
24
  # Langfuse trace-level attributes
24
25
  ATTR_LANGFUSE_USER_ID = "langfuse.user.id"
@@ -34,6 +35,7 @@ module Agents
34
35
  ATTR_LANGFUSE_OBS_INPUT = "langfuse.observation.input"
35
36
  ATTR_LANGFUSE_OBS_OUTPUT = "langfuse.observation.output"
36
37
  ATTR_LANGFUSE_OBS_METADATA_PREFIX = "langfuse.observation.metadata."
38
+ ATTR_LANGFUSE_REASONING_SUMMARY = "langfuse.observation.metadata.reasoning_summary"
37
39
  end
38
40
  end
39
41
  end
@@ -60,6 +60,8 @@ module Agents
60
60
  return unless tracing
61
61
 
62
62
  tracing[:pending_llm_input] = serialize_output(input)
63
+ # The response hook runs after the provider call; preserve its real start time.
64
+ tracing[:llm_started_at] = Time.now
63
65
 
64
66
  return if tracing[:current_agent_name] == agent_name
65
67
 
@@ -77,14 +79,18 @@ module Agents
77
79
  finish_agent_span(tracing)
78
80
  end
79
81
 
80
- def on_chat_created(chat, agent_name, model, context_wrapper, temperature = nil)
82
+ def on_chat_created(chat, _agent_name, model, context_wrapper, temperature = nil, protocol = nil, thinking = nil)
81
83
  tracing = tracing_state(context_wrapper)
82
84
  return unless tracing
83
85
 
84
- request_attributes = { model: model, temperature: temperature }
86
+ tracing[:request_attributes] = { model: model, temperature: temperature,
87
+ protocol: protocol, thinking: thinking }
88
+ return if tracing[:instrumented_chat].equal?(chat)
85
89
 
86
- chat.on_end_message do |message|
87
- handle_end_message(chat, agent_name, request_attributes, message, context_wrapper)
90
+ tracing[:instrumented_chat] = chat
91
+
92
+ chat.after_message do |message|
93
+ handle_end_message(chat, message, context_wrapper)
88
94
  end
89
95
  end
90
96
 
@@ -109,7 +115,7 @@ module Agents
109
115
  tracing[:current_tool_span] = tool_span
110
116
  end
111
117
 
112
- def on_tool_complete(_tool_name, result, context_wrapper)
118
+ def on_tool_complete(_tool_name, result, context_wrapper, error = nil)
113
119
  tracing = tracing_state(context_wrapper)
114
120
  return unless tracing
115
121
 
@@ -117,6 +123,10 @@ module Agents
117
123
  return unless tool_span
118
124
 
119
125
  tool_span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, serialize_output(result))
126
+ if error
127
+ tool_span.record_exception(error)
128
+ tool_span.status = OpenTelemetry::Trace::Status.error(error.message)
129
+ end
120
130
  tool_span.finish
121
131
  tracing[:current_tool_span] = nil
122
132
  end
@@ -153,7 +163,7 @@ module Agents
153
163
 
154
164
  private
155
165
 
156
- def handle_end_message(chat, _agent_name, request_attributes, message, context_wrapper)
166
+ def handle_end_message(chat, message, context_wrapper)
157
167
  return unless message.respond_to?(:role) && message.role == :assistant
158
168
 
159
169
  tracing = tracing_state(context_wrapper)
@@ -162,13 +172,14 @@ module Agents
162
172
  llm_span = @tracer.start_span(
163
173
  @llm_span_name,
164
174
  with_parent: parent_context(tracing),
175
+ start_timestamp: tracing.delete(:llm_started_at),
165
176
  attributes: generation_span_attributes(tracing, chat, message, context_wrapper)
166
177
  )
167
178
 
168
- set_llm_request_attributes(llm_span, request_attributes)
179
+ set_llm_request_attributes(llm_span, tracing[:request_attributes])
169
180
 
170
181
  output = llm_output_text(message)
171
- set_llm_response_attributes(llm_span, message, output)
182
+ set_llm_response_attributes(llm_span, message, output, tracing[:request_attributes])
172
183
  tracing[:last_agent_output] = output unless output.empty?
173
184
 
174
185
  llm_span.finish
@@ -218,16 +229,23 @@ module Agents
218
229
  root_span.status = OpenTelemetry::Trace::Status.error(error.message)
219
230
  end
220
231
 
221
- def set_llm_response_attributes(span, response, output)
222
- if response.respond_to?(:input_tokens) && response.input_tokens
223
- span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, response.input_tokens)
224
- end
225
- if response.respond_to?(:output_tokens) && response.output_tokens
226
- span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, response.output_tokens)
227
- end
232
+ def set_llm_response_attributes(span, response, output, request_attributes)
233
+ tokens = response.tokens if response.respond_to?(:tokens)
234
+ span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, tokens.input) if tokens&.input
235
+ span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, tokens.output) if tokens&.output
236
+ span.set_attribute(ATTR_GEN_AI_USAGE_REASONING_OUTPUT, tokens.thinking) if tokens&.thinking
237
+ set_reasoning_summary(span, response, request_attributes)
228
238
  span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, output) unless output.empty?
229
239
  end
230
240
 
241
+ def set_reasoning_summary(span, response, request_attributes)
242
+ return unless request_attributes[:protocol] == :responses
243
+ return unless request_attributes.dig(:thinking, :display).to_s == "summarized"
244
+ return unless response.respond_to?(:thinking) && response.thinking&.text
245
+
246
+ span.set_attribute(ATTR_LANGFUSE_REASONING_SUMMARY, response.thinking.text)
247
+ end
248
+
231
249
  # Returns serialized text content if present, otherwise falls back to tool call formatting.
232
250
  # Uses .to_json for Hash/Array (structured output) to avoid Ruby's .to_s format.
233
251
  def llm_output_text(response)
@@ -252,6 +270,7 @@ module Agents
252
270
  def format_single_message(msg)
253
271
  text = serialize_output(msg.content)
254
272
  text = append_tool_calls(msg, text)
273
+ text = append_attachment_summary(text, msg.attachments) if msg.respond_to?(:attachments)
255
274
  { role: msg.role.to_s, content: text }
256
275
  end
257
276
 
@@ -265,7 +284,16 @@ module Agents
265
284
  def serialize_output(value)
266
285
  return serialize_multimodal_content(value) if multimodal_content?(value)
267
286
 
268
- value.is_a?(Hash) || value.is_a?(Array) ? value.to_json : value.to_s
287
+ return value.map { |part| redact_image_source(part) }.to_json if value.is_a?(Array)
288
+
289
+ value.is_a?(Hash) ? redact_image_source(value).to_json : value.to_s
290
+ end
291
+
292
+ def redact_image_source(part)
293
+ return part unless part.is_a?(Hash) && (part[:type] || part["type"]) == "image_url"
294
+
295
+ key = part.key?(:image_url) ? :image_url : "image_url"
296
+ part.merge(key => "[image]")
269
297
  end
270
298
 
271
299
  def format_tool_calls(response)
@@ -426,16 +454,17 @@ module Agents
426
454
  end
427
455
 
428
456
  def serialize_multimodal_content(content)
429
- parts = []
430
- text = content.text
431
- parts << text if text && !text.empty?
457
+ append_attachment_summary(content.text.to_s, content.attachments)
458
+ end
432
459
 
433
- if content.attachments&.any?
434
- urls = content.attachments.map { |a| a.respond_to?(:source) ? a.source.to_s : a.to_s }
435
- parts << "Attachments: #{urls.join(", ")}"
436
- end
460
+ def append_attachment_summary(text, attachments)
461
+ return text unless attachments&.any?
437
462
 
438
- parts.join("\n")
463
+ types = attachments.map do |attachment|
464
+ type = attachment.mime_type if attachment.respond_to?(:mime_type)
465
+ type.to_s.empty? ? "file" : type
466
+ end
467
+ [text, "Attachments: #{types.join(", ")}"].reject(&:empty?).join("\n")
439
468
  end
440
469
  end
441
470
  end
@@ -95,16 +95,17 @@ module Agents
95
95
 
96
96
  # Add usage metrics from an LLM response to the running totals.
97
97
  # Only tracks usage for responses that have token data (e.g., RubyLLM::Message).
98
- # Safely skips responses without token methods (e.g., RubyLLM::Tool::Halt).
98
+ # Safely skips values without token usage.
99
99
  #
100
100
  # @param response [RubyLLM::Message] A RubyLLM::Message object with token usage data
101
101
  # @example Adding usage from an LLM response
102
102
  # usage.add(llm_response)
103
103
  def add(response)
104
- return unless response.respond_to?(:input_tokens)
104
+ tokens = response.tokens if response.respond_to?(:tokens)
105
+ return unless tokens
105
106
 
106
- input = response.input_tokens || 0
107
- output = response.output_tokens || 0
107
+ input = tokens.input || 0
108
+ output = tokens.output || 0
108
109
 
109
110
  @input_tokens += input
110
111
  @output_tokens += output
data/lib/agents/runner.rb CHANGED
@@ -103,11 +103,7 @@ module Agents
103
103
  agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
104
104
 
105
105
  # Create chat and restore conversation history
106
- chat = RubyLLM::Chat.new(
107
- model: current_agent.model,
108
- provider: current_agent.provider,
109
- assume_model_exists: current_agent.assume_model_exists
110
- )
106
+ chat = build_chat(current_agent)
111
107
  current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
112
108
  current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
113
109
  apply_headers(chat, current_headers)
@@ -115,28 +111,24 @@ module Agents
115
111
  configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
116
112
  restore_conversation_history(chat, context_wrapper)
117
113
  input_already_in_history = last_message_matches?(chat, input)
114
+ unless input_already_in_history
115
+ content, attachments = build_content(input)
116
+ chat.ask_later(content, with: attachments)
117
+ end
118
118
  context_wrapper.callback_manager.emit_chat_created(
119
- chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
119
+ chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature,
120
+ current_agent.protocol, current_agent.thinking
120
121
  )
121
122
 
122
123
  loop do
123
124
  current_turn += 1
124
125
  raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
125
126
 
126
- # Get response from LLM (RubyLLM handles tool execution with halting based handoff detection)
127
+ # One provider request per turn. Run tools separately so handoffs stop before another request.
127
128
  message_count_before_response = chat_message_count(chat)
128
- response = if current_turn == 1
129
- # Emit agent thinking event for initial message
130
- context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, input, context_wrapper)
131
- # If conversation history already ends with this user message (e.g. passed
132
- # in via context from an external system), use complete to avoid duplicating it.
133
- input_already_in_history ? chat.complete : chat.ask(input)
134
- else
135
- # Emit agent thinking event for continuation
136
- context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, "(continuing conversation)",
137
- context_wrapper)
138
- chat.complete
139
- end
129
+ thinking_input = current_turn == 1 ? input : "(continuing conversation)"
130
+ context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, thinking_input, context_wrapper)
131
+ response = chat.generate
140
132
  assign_agent_name_to_new_assistant_messages(chat, current_agent, message_count_before_response)
141
133
  track_usage(response, context_wrapper)
142
134
 
@@ -145,8 +137,9 @@ module Agents
145
137
  current_agent.name, current_agent.model, response, context_wrapper
146
138
  )
147
139
 
148
- # Check for handoff via RubyLLM's halt mechanism
149
- if response.is_a?(RubyLLM::Tool::Halt) && context_wrapper.context[:pending_handoff]
140
+ chat.run_tools if response.tool_call?
141
+
142
+ if context_wrapper.context[:pending_handoff]
150
143
  handoff_info = context_wrapper.context.delete(:pending_handoff)
151
144
  next_agent = handoff_info[:target_agent]
152
145
 
@@ -171,16 +164,20 @@ module Agents
171
164
  current_agent = next_agent
172
165
  context_wrapper.context[:current_agent] = next_agent.name
173
166
 
174
- # Reconfigure existing chat for new agent - preserves conversation history automatically
175
- configure_chat_for_agent(chat, current_agent, context_wrapper, replace: true)
167
+ # A fresh chat prevents protocol and thinking settings leaking across agents.
168
+ next_chat = build_chat(current_agent)
169
+ next_chat.messages = chat.messages
170
+ chat = next_chat
171
+ configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
176
172
  agent_headers = Helpers::HashNormalizer.normalize(current_agent.headers, label: "headers")
177
173
  current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
178
- apply_headers(chat, current_headers)
174
+ chat.with_headers(current_headers)
179
175
  agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
180
176
  current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
181
- apply_params(chat, current_params)
177
+ chat.with_provider_options(current_params)
182
178
  context_wrapper.callback_manager.emit_chat_created(
183
- chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
179
+ chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature,
180
+ current_agent.protocol, current_agent.thinking
184
181
  )
185
182
 
186
183
  # Force the new agent to respond to the conversation context
@@ -189,16 +186,12 @@ module Agents
189
186
  next
190
187
  end
191
188
 
192
- # Handle non-handoff halts - return the halt content as final response
193
- if response.is_a?(RubyLLM::Tool::Halt)
194
- return finalize_run(chat, context_wrapper, current_agent, output: response.content)
195
- end
196
-
197
- # If tools were called, continue the loop to let them execute
189
+ # A tool result needs another provider request under the turn limit.
198
190
  next if response.tool_call?
199
191
 
200
192
  # If no tools were called, we have our final response
201
- return finalize_run(chat, context_wrapper, current_agent, output: response.content)
193
+ output = current_agent.response_schema ? response.parsed : response.content
194
+ return finalize_run(chat, context_wrapper, current_agent, output: output)
202
195
  end
203
196
  rescue MaxTurnsExceeded => e
204
197
  finalize_run(chat, context_wrapper, current_agent,
@@ -209,8 +202,13 @@ module Agents
209
202
 
210
203
  private
211
204
 
205
+ def build_chat(agent)
206
+ RubyLLM::Chat.new(model: agent.model, provider: agent.provider, protocol: agent.protocol,
207
+ assume_model_exists: agent.assume_model_exists)
208
+ end
209
+
212
210
  # Saves conversation state, builds a RunResult, emits completion callbacks, and returns it.
213
- # Centralises the finalize-and-return pattern used by the normal path, halt path, and error rescues.
211
+ # Centralises the finalize-and-return pattern used by the normal path and error rescues.
214
212
  #
215
213
  # @param chat [RubyLLM::Chat, nil] The chat instance (nil in early-failure rescues)
216
214
  # @param context_wrapper [RunContext] Context wrapper for state and callbacks
@@ -260,7 +258,8 @@ module Agents
260
258
  history = context_wrapper.context[:conversation_history] || []
261
259
  valid_tool_call_ids = Set.new
262
260
 
263
- history.each do |msg|
261
+ history.each_with_index do |msg, index|
262
+ msg = with_completed_tool_calls(history, index, msg)
264
263
  next unless restorable_message?(msg)
265
264
 
266
265
  if msg[:role].to_sym == :tool &&
@@ -283,15 +282,26 @@ module Agents
283
282
  end
284
283
  end
285
284
 
285
+ def with_completed_tool_calls(history, index, msg)
286
+ return msg unless msg[:role].to_sym == :assistant && msg[:tool_calls]&.any?
287
+
288
+ msg.merge(tool_calls: completed_tool_calls(history, index, msg[:tool_calls]))
289
+ end
290
+
291
+ def completed_tool_calls(history, index, tool_calls)
292
+ following_results = history[(index + 1)..].take_while { |entry| entry[:role].to_sym == :tool }
293
+ following_ids = following_results.map { |entry| entry[:tool_call_id] }.to_set
294
+ tool_calls.select { |call| following_ids.include?(call[:id] || call["id"]) }
295
+ end
296
+
286
297
  # Check if a message should be restored
287
298
  def restorable_message?(msg)
288
299
  role = msg[:role].to_sym
289
300
  return false unless %i[user assistant tool].include?(role)
290
301
 
291
302
  # Allow assistant messages that only contain tool calls (no text content)
292
- tool_calls_present = role == :assistant && msg[:tool_calls] && !msg[:tool_calls].empty?
293
- return false if role != :tool && !tool_calls_present &&
294
- Helpers::MessageExtractor.content_empty?(msg[:content])
303
+ assistant_payload = role == :assistant && (msg[:tool_calls]&.any? || msg[:thinking_signature])
304
+ return false if role != :tool && !assistant_payload && Helpers::MessageExtractor.content_empty?(msg[:content])
295
305
 
296
306
  true
297
307
  end
@@ -304,10 +314,14 @@ module Agents
304
314
  # Assistant tool-call messages may have empty text, but still need placeholder content
305
315
  content_value = "" if content_value.nil? && role == :assistant && msg[:tool_calls]&.any?
306
316
 
307
- params = {
308
- role: role,
309
- content: build_content(content_value)
310
- }
317
+ content, attachments = build_content(content_value)
318
+ params = { role: role, content: content }
319
+ params[:attachments] = attachments if attachments.any?
320
+ if role == :assistant && msg[:thinking_signature]
321
+ params[:thinking] = { text: msg[:thinking], signature: msg[:thinking_signature] }
322
+ usage_entries = thinking_usage_entries(msg[:thinking_provider], msg[:thinking_model])
323
+ params[:usage_entries] = usage_entries if usage_entries
324
+ end
311
325
 
312
326
  # Handle tool-specific parameters (Tool Results)
313
327
  if role == :tool
@@ -330,7 +344,8 @@ module Agents
330
344
  hash[tool_call_id] = RubyLLM::ToolCall.new(
331
345
  id: tool_call_id,
332
346
  name: tc[:name] || tc["name"],
333
- arguments: tc[:arguments] || tc["arguments"] || {}
347
+ arguments: tc[:arguments] || tc["arguments"] || {},
348
+ thought_signature: tc[:thought_signature] || tc["thought_signature"]
334
349
  )
335
350
  end
336
351
  end
@@ -338,10 +353,19 @@ module Agents
338
353
  params
339
354
  end
340
355
 
341
- # Build RubyLLM::Content from stored content, handling multimodal arrays with image attachments.
356
+ # Restores the producer that RubyLLM checks before it replays a thinking signature.
357
+ # RubyLLM's Rails persistence restores the same entry from its usage table.
358
+ def thinking_usage_entries(provider, model)
359
+ return unless provider
360
+
361
+ [RubyLLM::Accounting::Usage::Entry.new(operation: :chat, provider: provider, model: model, status: :succeeded)]
362
+ end
363
+
364
+ # Split stored content into RubyLLM 2 text and attachments.
342
365
  # Multimodal arrays follow the OpenAI content format: [{type: 'text', text: '...'}, {type: 'image_url', ...}]
343
366
  def build_content(content_value)
344
- return RubyLLM::Content.new(content_value) unless content_value.is_a?(Array)
367
+ return [content_value.to_json, []] if content_value.is_a?(Hash)
368
+ return [content_value, []] unless content_value.is_a?(Array)
345
369
 
346
370
  text_parts = content_value.filter_map { |p| p[:text] || p["text"] if (p[:type] || p["type"]) == "text" }
347
371
  image_urls = content_value.filter_map do |p|
@@ -350,10 +374,9 @@ module Agents
350
374
  p.dig(:image_url, :url) || p.dig("image_url", "url")
351
375
  end
352
376
 
353
- return RubyLLM::Content.new(content_value.to_json) if text_parts.empty? && image_urls.empty?
377
+ return [content_value.to_json, []] if text_parts.empty? && image_urls.empty?
354
378
 
355
- text = text_parts.join(" ")
356
- image_urls.any? ? RubyLLM::Content.new(text, image_urls) : RubyLLM::Content.new(text)
379
+ [text_parts.join(" "), image_urls]
357
380
  end
358
381
 
359
382
  # Validate tool message has required tool_call_id
@@ -414,7 +437,7 @@ module Agents
414
437
  end
415
438
 
416
439
  # Configures a RubyLLM chat instance with agent-specific settings.
417
- # Uses RubyLLM's replace option to swap agent context while preserving conversation history during handoffs.
440
+ # Swaps agent settings while preserving conversation history during handoffs.
418
441
  #
419
442
  # @param chat [RubyLLM::Chat] The chat instance to configure
420
443
  # @param agent [Agents::Agent] The agent whose configuration to apply
@@ -433,15 +456,18 @@ module Agents
433
456
  chat.with_model(
434
457
  agent.model,
435
458
  provider: agent.provider,
436
- assume_exists: agent.assume_model_exists
459
+ protocol: agent.protocol,
460
+ assume_model_exists: agent.assume_model_exists
437
461
  )
438
462
  end
439
463
 
440
464
  # Configure chat with instructions, temperature, tools, and schema
441
- chat.with_instructions(system_prompt, replace: replace) if system_prompt
442
- chat.with_temperature(agent.temperature) if agent.temperature
443
- chat.with_tools(*all_tools, replace: replace)
444
- chat.with_schema(agent.response_schema) if agent.response_schema
465
+ chat.with_instructions(system_prompt)
466
+ chat.with_temperature(agent.temperature)
467
+ chat.with_thinking(**agent.thinking) if agent.thinking
468
+ chat.with_tools(nil) if replace
469
+ chat.with_tools(*all_tools)
470
+ chat.with_schema(agent.response_schema)
445
471
 
446
472
  chat
447
473
  end
@@ -458,19 +484,22 @@ module Agents
458
484
  return false unless input && chat.respond_to?(:messages)
459
485
 
460
486
  last_msg = chat.messages.last
461
- last_msg && last_msg.role == :user && last_msg.content.to_s == input.to_s
487
+ return false unless last_msg&.role == :user
488
+
489
+ content, attachments = build_content(input)
490
+ last_msg.content == content && last_msg.attachments.map { |attachment| attachment.source.to_s } == attachments
462
491
  end
463
492
 
464
493
  def apply_headers(chat, headers)
465
494
  return if headers.empty?
466
495
 
467
- chat.with_headers(**headers)
496
+ chat.with_headers(headers)
468
497
  end
469
498
 
470
499
  def apply_params(chat, params)
471
500
  return if params.empty?
472
501
 
473
- chat.with_params(**params)
502
+ chat.with_provider_options(params)
474
503
  end
475
504
 
476
505
  def track_usage(response, context_wrapper)
data/lib/agents/tool.rb CHANGED
@@ -20,7 +20,7 @@
20
20
  # class WeatherTool < Agents::Tool
21
21
  # name "get_weather"
22
22
  # description "Get current weather for a location"
23
- # param :location, type: "string", desc: "City name or coordinates"
23
+ # parameter :location, type: "string", description: "City name or coordinates"
24
24
  #
25
25
  # def perform(tool_context, location:)
26
26
  # # All state comes from parameters - no instance variables!
@@ -38,6 +38,13 @@
38
38
  #
39
39
  module Agents
40
40
  class Tool < RubyLLM::Tool
41
+ # Keep custom tools written for ai-agents 0.12 working with RubyLLM 2.
42
+ def self.param(name, **options)
43
+ old_description = options.delete(:desc)
44
+ options[:description] ||= old_description
45
+ parameter(name, **options)
46
+ end
47
+
41
48
  # Execute the tool with context injection.
42
49
  # This method is called by the runner and handles the thread-safe
43
50
  # execution pattern by passing all state through parameters.
@@ -18,14 +18,14 @@ module Agents
18
18
  #
19
19
  # ## The Solution
20
20
  # Each Runner creates new wrapper instances for each execution, capturing the context
21
- # in the wrapper's closure. When RubyLLM calls execute(), the wrapper injects the
21
+ # in the wrapper's closure. When RubyLLM calls call(), the wrapper injects the
22
22
  # context before calling the actual tool:
23
23
  #
24
24
  # # Runner creates wrapper
25
25
  # wrapped = ToolWrapper.new(my_tool, context_wrapper)
26
26
  #
27
27
  # # RubyLLM calls wrapper
28
- # wrapped.execute(city: "NYC") # No context parameter
28
+ # wrapped.call(city: "NYC") # No context parameter
29
29
  #
30
30
  # # Wrapper injects context
31
31
  # tool_context = ToolContext.new(run_context: context_wrapper)
@@ -33,6 +33,12 @@ module Agents
33
33
  #
34
34
  # This ensures each execution has its own context without any shared mutable state.
35
35
  class ToolWrapper
36
+ # RubyLLM 2.1 reads deferral from the tool class. ai-agents does not support
37
+ # deferred tools, so every wrapped tool is sent to the model up front.
38
+ def self.deferred?
39
+ false
40
+ end
41
+
36
42
  def initialize(tool, context_wrapper)
37
43
  @tool = tool
38
44
  @context_wrapper = context_wrapper
@@ -40,11 +46,12 @@ module Agents
40
46
  # Copy tool metadata for RubyLLM
41
47
  @name = tool.name
42
48
  @description = tool.description
43
- @params = tool.class.params if tool.class.respond_to?(:params)
44
49
  end
45
50
 
46
51
  # RubyLLM calls this method (follows RubyLLM::Tool pattern)
47
- def call(args)
52
+ def call(tool_call: nil, **args) # rubocop:disable Lint/UnusedMethodArgument
53
+ return "Skipped after agent handoff" if @context_wrapper.context[:pending_handoff]
54
+
48
55
  tool_context = ToolContext.new(run_context: @context_wrapper)
49
56
 
50
57
  @context_wrapper.callback_manager.emit_tool_start(@tool.name, args, @context_wrapper)
@@ -54,7 +61,7 @@ module Agents
54
61
  @context_wrapper.callback_manager.emit_tool_complete(@tool.name, result, @context_wrapper)
55
62
  result
56
63
  rescue StandardError => e
57
- @context_wrapper.callback_manager.emit_tool_complete(@tool.name, "ERROR: #{e.message}", @context_wrapper)
64
+ @context_wrapper.callback_manager.emit_tool_complete(@tool.name, "ERROR: #{e.message}", @context_wrapper, e)
58
65
  raise
59
66
  end
60
67
  end
@@ -68,18 +75,20 @@ module Agents
68
75
  @description || @tool.description
69
76
  end
70
77
 
71
- # RubyLLM calls this to get parameter definitions
72
- def parameters
73
- @tool.parameters
78
+ def parameters_schema
79
+ @tool.parameters_schema
80
+ end
81
+
82
+ def provider_options
83
+ @tool.provider_options
74
84
  end
75
85
 
76
- # Expose params schema for RubyLLM providers that expect it
77
- def params_schema
78
- @tool.respond_to?(:params_schema) ? @tool.params_schema : nil
86
+ def requires_approval?
87
+ @tool.requires_approval?
79
88
  end
80
89
 
81
- def provider_params
82
- @tool.respond_to?(:provider_params) ? @tool.provider_params : {}
90
+ def approval_resolver
91
+ @tool.approval_resolver
83
92
  end
84
93
 
85
94
  # Make this work with RubyLLM's tool calling
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Agents
4
- VERSION = "0.12.0"
4
+ VERSION = "0.14.0"
5
5
  end