ai-agents 0.12.0 → 0.13.0

data/lib/agents/helpers/message_extractor.rb

@@ -76,20 +76,21 @@ module Agents
       end
 
       def extract_user_or_assistant_message(msg, current_agent)
-        content_present = message_content?(msg)
         tool_calls_present = assistant_tool_calls?(msg)
-        return nil unless content_present || tool_calls_present
+        return nil unless extractable_message?(msg, tool_calls_present)
 
-        message = {
-          role: msg.role,
-          content: content_present ? msg.content : ""
-        }
+        message = { role: msg.role, content: persisted_content(msg) }
 
         return message unless msg.role == :assistant
 
         attributed_agent_name = attributed_agent_name_for(msg) || current_agent&.name
         message[:agent_name] = attributed_agent_name if attributed_agent_name
 
+        if msg.respond_to?(:thinking) && msg.thinking&.signature
+          message[:thinking] = msg.thinking.text if msg.thinking.text
+          message[:thinking_signature] = msg.thinking.signature
+        end
+
         if tool_calls_present
           # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
           # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
@@ -99,6 +100,21 @@ module Agents
         message
       end
 
+      def persisted_content(msg)
+        content = message_content?(msg) ? msg.content : ""
+        return content if msg.attachments.empty?
+
+        parts = content.to_s.empty? ? [] : [{ type: "text", text: content }]
+        parts + msg.attachments.map do |attachment|
+          { type: "image_url", image_url: { url: attachment.source.to_s } }
+        end
+      end
+
+      def extractable_message?(msg, tool_calls_present)
+        message_content?(msg) || tool_calls_present || msg.attachments.any? ||
+          (msg.role == :assistant && msg.respond_to?(:thinking) && msg.thinking&.signature)
+      end
+
       def message_content?(msg)
         msg.content && !content_empty?(msg.content)
       end
@@ -117,8 +133,8 @@ module Agents
         }
       end
 
-      private_class_method :extract_user_or_assistant_message, :message_content?, :assistant_tool_calls?,
-                           :extract_tool_message
+      private_class_method :extract_user_or_assistant_message, :persisted_content, :extractable_message?,
+                           :message_content?, :assistant_tool_calls?, :extract_tool_message
     end
   end
 end

data/lib/agents/instrumentation/constants.rb

@@ -19,6 +19,7 @@ module Agents
       ATTR_GEN_AI_PROVIDER      = "gen_ai.provider.name"
       ATTR_GEN_AI_USAGE_INPUT   = "gen_ai.usage.input_tokens"
       ATTR_GEN_AI_USAGE_OUTPUT  = "gen_ai.usage.output_tokens"
+      ATTR_GEN_AI_USAGE_REASONING_OUTPUT = "gen_ai.usage.reasoning.output_tokens"
 
       # Langfuse trace-level attributes
       ATTR_LANGFUSE_USER_ID     = "langfuse.user.id"
@@ -34,6 +35,7 @@ module Agents
       ATTR_LANGFUSE_OBS_INPUT  = "langfuse.observation.input"
       ATTR_LANGFUSE_OBS_OUTPUT = "langfuse.observation.output"
       ATTR_LANGFUSE_OBS_METADATA_PREFIX = "langfuse.observation.metadata."
+      ATTR_LANGFUSE_REASONING_SUMMARY = "langfuse.observation.metadata.reasoning_summary"
     end
   end
 end

data/lib/agents/instrumentation/tracing_callbacks.rb

@@ -60,6 +60,8 @@ module Agents
         return unless tracing
 
         tracing[:pending_llm_input] = serialize_output(input)
+        # The response hook runs after the provider call; preserve its real start time.
+        tracing[:llm_started_at] = Time.now
 
         return if tracing[:current_agent_name] == agent_name
 
@@ -77,14 +79,18 @@ module Agents
         finish_agent_span(tracing)
       end
 
-      def on_chat_created(chat, agent_name, model, context_wrapper, temperature = nil)
+      def on_chat_created(chat, _agent_name, model, context_wrapper, temperature = nil, protocol = nil, thinking = nil)
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
-        request_attributes = { model: model, temperature: temperature }
+        tracing[:request_attributes] = { model: model, temperature: temperature,
+                                         protocol: protocol, thinking: thinking }
+        return if tracing[:instrumented_chat].equal?(chat)
 
-        chat.on_end_message do |message|
-          handle_end_message(chat, agent_name, request_attributes, message, context_wrapper)
+        tracing[:instrumented_chat] = chat
+
+        chat.after_message do |message|
+          handle_end_message(chat, message, context_wrapper)
         end
       end
 
@@ -109,7 +115,7 @@ module Agents
         tracing[:current_tool_span] = tool_span
       end
 
-      def on_tool_complete(_tool_name, result, context_wrapper)
+      def on_tool_complete(_tool_name, result, context_wrapper, error = nil)
         tracing = tracing_state(context_wrapper)
         return unless tracing
 
@@ -117,6 +123,10 @@ module Agents
         return unless tool_span
 
         tool_span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, serialize_output(result))
+        if error
+          tool_span.record_exception(error)
+          tool_span.status = OpenTelemetry::Trace::Status.error(error.message)
+        end
         tool_span.finish
         tracing[:current_tool_span] = nil
       end
@@ -153,7 +163,7 @@ module Agents
 
       private
 
-      def handle_end_message(chat, _agent_name, request_attributes, message, context_wrapper)
+      def handle_end_message(chat, message, context_wrapper)
         return unless message.respond_to?(:role) && message.role == :assistant
 
         tracing = tracing_state(context_wrapper)
@@ -162,13 +172,14 @@ module Agents
         llm_span = @tracer.start_span(
           @llm_span_name,
           with_parent: parent_context(tracing),
+          start_timestamp: tracing.delete(:llm_started_at),
           attributes: generation_span_attributes(tracing, chat, message, context_wrapper)
         )
 
-        set_llm_request_attributes(llm_span, request_attributes)
+        set_llm_request_attributes(llm_span, tracing[:request_attributes])
 
         output = llm_output_text(message)
-        set_llm_response_attributes(llm_span, message, output)
+        set_llm_response_attributes(llm_span, message, output, tracing[:request_attributes])
         tracing[:last_agent_output] = output unless output.empty?
 
         llm_span.finish
@@ -218,16 +229,23 @@ module Agents
         root_span.status = OpenTelemetry::Trace::Status.error(error.message)
       end
 
-      def set_llm_response_attributes(span, response, output)
-        if response.respond_to?(:input_tokens) && response.input_tokens
-          span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, response.input_tokens)
-        end
-        if response.respond_to?(:output_tokens) && response.output_tokens
-          span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, response.output_tokens)
-        end
+      def set_llm_response_attributes(span, response, output, request_attributes)
+        tokens = response.tokens if response.respond_to?(:tokens)
+        span.set_attribute(ATTR_GEN_AI_USAGE_INPUT, tokens.input) if tokens&.input
+        span.set_attribute(ATTR_GEN_AI_USAGE_OUTPUT, tokens.output) if tokens&.output
+        span.set_attribute(ATTR_GEN_AI_USAGE_REASONING_OUTPUT, tokens.thinking) if tokens&.thinking
+        set_reasoning_summary(span, response, request_attributes)
         span.set_attribute(ATTR_LANGFUSE_OBS_OUTPUT, output) unless output.empty?
       end
 
+      def set_reasoning_summary(span, response, request_attributes)
+        return unless request_attributes[:protocol] == :responses
+        return unless request_attributes.dig(:thinking, :display).to_s == "summarized"
+        return unless response.respond_to?(:thinking) && response.thinking&.text
+
+        span.set_attribute(ATTR_LANGFUSE_REASONING_SUMMARY, response.thinking.text)
+      end
+
       # Returns serialized text content if present, otherwise falls back to tool call formatting.
       # Uses .to_json for Hash/Array (structured output) to avoid Ruby's .to_s format.
       def llm_output_text(response)
@@ -252,6 +270,7 @@ module Agents
       def format_single_message(msg)
         text = serialize_output(msg.content)
         text = append_tool_calls(msg, text)
+        text = append_attachment_summary(text, msg.attachments) if msg.respond_to?(:attachments)
         { role: msg.role.to_s, content: text }
       end
 
@@ -265,7 +284,16 @@ module Agents
       def serialize_output(value)
         return serialize_multimodal_content(value) if multimodal_content?(value)
 
-        value.is_a?(Hash) || value.is_a?(Array) ? value.to_json : value.to_s
+        return value.map { |part| redact_image_source(part) }.to_json if value.is_a?(Array)
+
+        value.is_a?(Hash) ? redact_image_source(value).to_json : value.to_s
+      end
+
+      def redact_image_source(part)
+        return part unless part.is_a?(Hash) && (part[:type] || part["type"]) == "image_url"
+
+        key = part.key?(:image_url) ? :image_url : "image_url"
+        part.merge(key => "[image]")
       end
 
       def format_tool_calls(response)
@@ -426,16 +454,17 @@ module Agents
       end
 
       def serialize_multimodal_content(content)
-        parts = []
-        text = content.text
-        parts << text if text && !text.empty?
+        append_attachment_summary(content.text.to_s, content.attachments)
+      end
 
-        if content.attachments&.any?
-          urls = content.attachments.map { |a| a.respond_to?(:source) ? a.source.to_s : a.to_s }
-          parts << "Attachments: #{urls.join(", ")}"
-        end
+      def append_attachment_summary(text, attachments)
+        return text unless attachments&.any?
 
-        parts.join("\n")
+        types = attachments.map do |attachment|
+          type = attachment.mime_type if attachment.respond_to?(:mime_type)
+          type.to_s.empty? ? "file" : type
+        end
+        [text, "Attachments: #{types.join(", ")}"].reject(&:empty?).join("\n")
       end
     end
   end

data/lib/agents/run_context.rb

@@ -95,16 +95,17 @@ module Agents
 
       # Add usage metrics from an LLM response to the running totals.
       # Only tracks usage for responses that have token data (e.g., RubyLLM::Message).
-      # Safely skips responses without token methods (e.g., RubyLLM::Tool::Halt).
+      # Safely skips values without token usage.
       #
       # @param response [RubyLLM::Message] A RubyLLM::Message object with token usage data
       # @example Adding usage from an LLM response
       #   usage.add(llm_response)
       def add(response)
-        return unless response.respond_to?(:input_tokens)
+        tokens = response.tokens if response.respond_to?(:tokens)
+        return unless tokens
 
-        input = response.input_tokens || 0
-        output = response.output_tokens || 0
+        input = tokens.input || 0
+        output = tokens.output || 0
 
         @input_tokens += input
         @output_tokens += output

data/lib/agents/runner.rb

@@ -103,11 +103,7 @@ module Agents
       agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
 
       # Create chat and restore conversation history
-      chat = RubyLLM::Chat.new(
-        model: current_agent.model,
-        provider: current_agent.provider,
-        assume_model_exists: current_agent.assume_model_exists
-      )
+      chat = build_chat(current_agent)
       current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
       current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
       apply_headers(chat, current_headers)
@@ -115,28 +111,24 @@ module Agents
       configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
       restore_conversation_history(chat, context_wrapper)
       input_already_in_history = last_message_matches?(chat, input)
+      unless input_already_in_history
+        content, attachments = build_content(input)
+        chat.ask_later(content, with: attachments)
+      end
       context_wrapper.callback_manager.emit_chat_created(
-        chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
+        chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature,
+        current_agent.protocol, current_agent.thinking
       )
 
       loop do
         current_turn += 1
         raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
 
-        # Get response from LLM (RubyLLM handles tool execution with halting based handoff detection)
+        # One provider request per turn. Run tools separately so handoffs stop before another request.
         message_count_before_response = chat_message_count(chat)
-        response = if current_turn == 1
-                     # Emit agent thinking event for initial message
-                     context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, input, context_wrapper)
-                     # If conversation history already ends with this user message (e.g. passed
-                     # in via context from an external system), use complete to avoid duplicating it.
-                     input_already_in_history ? chat.complete : chat.ask(input)
-                   else
-                     # Emit agent thinking event for continuation
-                     context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, "(continuing conversation)",
-                                                                          context_wrapper)
-                     chat.complete
-                   end
+        thinking_input = current_turn == 1 ? input : "(continuing conversation)"
+        context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, thinking_input, context_wrapper)
+        response = chat.generate
         assign_agent_name_to_new_assistant_messages(chat, current_agent, message_count_before_response)
         track_usage(response, context_wrapper)
 
@@ -145,8 +137,9 @@ module Agents
           current_agent.name, current_agent.model, response, context_wrapper
         )
 
-        # Check for handoff via RubyLLM's halt mechanism
-        if response.is_a?(RubyLLM::Tool::Halt) && context_wrapper.context[:pending_handoff]
+        chat.run_tools if response.tool_call?
+
+        if context_wrapper.context[:pending_handoff]
           handoff_info = context_wrapper.context.delete(:pending_handoff)
           next_agent = handoff_info[:target_agent]
 
@@ -171,16 +164,20 @@ module Agents
           current_agent = next_agent
           context_wrapper.context[:current_agent] = next_agent.name
 
-          # Reconfigure existing chat for new agent - preserves conversation history automatically
-          configure_chat_for_agent(chat, current_agent, context_wrapper, replace: true)
+          # A fresh chat prevents protocol and thinking settings leaking across agents.
+          next_chat = build_chat(current_agent)
+          next_chat.messages = chat.messages
+          chat = next_chat
+          configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
           agent_headers = Helpers::HashNormalizer.normalize(current_agent.headers, label: "headers")
           current_headers = Helpers::HashNormalizer.merge(agent_headers, runtime_headers)
-          apply_headers(chat, current_headers)
+          chat.with_headers(current_headers)
           agent_params = Helpers::HashNormalizer.normalize(current_agent.params, label: "params")
           current_params = Helpers::HashNormalizer.merge(agent_params, runtime_params)
-          apply_params(chat, current_params)
+          chat.with_provider_options(current_params)
           context_wrapper.callback_manager.emit_chat_created(
-            chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature
+            chat, current_agent.name, current_agent.model, context_wrapper, current_agent.temperature,
+            current_agent.protocol, current_agent.thinking
           )
 
           # Force the new agent to respond to the conversation context
@@ -189,16 +186,12 @@ module Agents
           next
         end
 
-        # Handle non-handoff halts - return the halt content as final response
-        if response.is_a?(RubyLLM::Tool::Halt)
-          return finalize_run(chat, context_wrapper, current_agent, output: response.content)
-        end
-
-        # If tools were called, continue the loop to let them execute
+        # A tool result needs another provider request under the turn limit.
         next if response.tool_call?
 
         # If no tools were called, we have our final response
-        return finalize_run(chat, context_wrapper, current_agent, output: response.content)
+        output = current_agent.response_schema ? response.parsed : response.content
+        return finalize_run(chat, context_wrapper, current_agent, output: output)
       end
     rescue MaxTurnsExceeded => e
       finalize_run(chat, context_wrapper, current_agent,
@@ -209,8 +202,13 @@ module Agents
 
     private
 
+    def build_chat(agent)
+      RubyLLM::Chat.new(model: agent.model, provider: agent.provider, protocol: agent.protocol,
+                        assume_model_exists: agent.assume_model_exists)
+    end
+
     # Saves conversation state, builds a RunResult, emits completion callbacks, and returns it.
-    # Centralises the finalize-and-return pattern used by the normal path, halt path, and error rescues.
+    # Centralises the finalize-and-return pattern used by the normal path and error rescues.
     #
     # @param chat [RubyLLM::Chat, nil] The chat instance (nil in early-failure rescues)
     # @param context_wrapper [RunContext] Context wrapper for state and callbacks
@@ -260,7 +258,8 @@ module Agents
       history = context_wrapper.context[:conversation_history] || []
       valid_tool_call_ids = Set.new
 
-      history.each do |msg|
+      history.each_with_index do |msg, index|
+        msg = with_completed_tool_calls(history, index, msg)
         next unless restorable_message?(msg)
 
         if msg[:role].to_sym == :tool &&
@@ -283,15 +282,26 @@ module Agents
       end
     end
 
+    def with_completed_tool_calls(history, index, msg)
+      return msg unless msg[:role].to_sym == :assistant && msg[:tool_calls]&.any?
+
+      msg.merge(tool_calls: completed_tool_calls(history, index, msg[:tool_calls]))
+    end
+
+    def completed_tool_calls(history, index, tool_calls)
+      following_results = history[(index + 1)..].take_while { |entry| entry[:role].to_sym == :tool }
+      following_ids = following_results.map { |entry| entry[:tool_call_id] }.to_set
+      tool_calls.select { |call| following_ids.include?(call[:id] || call["id"]) }
+    end
+
     # Check if a message should be restored
     def restorable_message?(msg)
       role = msg[:role].to_sym
       return false unless %i[user assistant tool].include?(role)
 
       # Allow assistant messages that only contain tool calls (no text content)
-      tool_calls_present = role == :assistant && msg[:tool_calls] && !msg[:tool_calls].empty?
-      return false if role != :tool && !tool_calls_present &&
-                      Helpers::MessageExtractor.content_empty?(msg[:content])
+      assistant_payload = role == :assistant && (msg[:tool_calls]&.any? || msg[:thinking_signature])
+      return false if role != :tool && !assistant_payload && Helpers::MessageExtractor.content_empty?(msg[:content])
 
       true
     end
@@ -304,10 +314,12 @@ module Agents
       # Assistant tool-call messages may have empty text, but still need placeholder content
       content_value = "" if content_value.nil? && role == :assistant && msg[:tool_calls]&.any?
 
-      params = {
-        role: role,
-        content: build_content(content_value)
-      }
+      content, attachments = build_content(content_value)
+      params = { role: role, content: content }
+      params[:attachments] = attachments if attachments.any?
+      if role == :assistant && msg[:thinking_signature]
+        params[:thinking] = { text: msg[:thinking], signature: msg[:thinking_signature] }
+      end
 
       # Handle tool-specific parameters (Tool Results)
       if role == :tool
@@ -330,7 +342,8 @@ module Agents
           hash[tool_call_id] = RubyLLM::ToolCall.new(
             id: tool_call_id,
             name: tc[:name] || tc["name"],
-            arguments: tc[:arguments] || tc["arguments"] || {}
+            arguments: tc[:arguments] || tc["arguments"] || {},
+            thought_signature: tc[:thought_signature] || tc["thought_signature"]
           )
         end
       end
@@ -338,10 +351,11 @@ module Agents
       params
     end
 
-    # Build RubyLLM::Content from stored content, handling multimodal arrays with image attachments.
+    # Split stored content into RubyLLM 2 text and attachments.
     # Multimodal arrays follow the OpenAI content format: [{type: 'text', text: '...'}, {type: 'image_url', ...}]
     def build_content(content_value)
-      return RubyLLM::Content.new(content_value) unless content_value.is_a?(Array)
+      return [content_value.to_json, []] if content_value.is_a?(Hash)
+      return [content_value, []] unless content_value.is_a?(Array)
 
       text_parts = content_value.filter_map { |p| p[:text] || p["text"] if (p[:type] || p["type"]) == "text" }
       image_urls = content_value.filter_map do |p|
@@ -350,10 +364,9 @@ module Agents
         p.dig(:image_url, :url) || p.dig("image_url", "url")
       end
 
-      return RubyLLM::Content.new(content_value.to_json) if text_parts.empty? && image_urls.empty?
+      return [content_value.to_json, []] if text_parts.empty? && image_urls.empty?
 
-      text = text_parts.join(" ")
-      image_urls.any? ? RubyLLM::Content.new(text, image_urls) : RubyLLM::Content.new(text)
+      [text_parts.join(" "), image_urls]
     end
 
     # Validate tool message has required tool_call_id
@@ -414,7 +427,7 @@ module Agents
     end
 
     # Configures a RubyLLM chat instance with agent-specific settings.
-    # Uses RubyLLM's replace option to swap agent context while preserving conversation history during handoffs.
+    # Swaps agent settings while preserving conversation history during handoffs.
     #
     # @param chat [RubyLLM::Chat] The chat instance to configure
     # @param agent [Agents::Agent] The agent whose configuration to apply
@@ -433,15 +446,18 @@ module Agents
         chat.with_model(
           agent.model,
           provider: agent.provider,
-          assume_exists: agent.assume_model_exists
+          protocol: agent.protocol,
+          assume_model_exists: agent.assume_model_exists
         )
       end
 
       # Configure chat with instructions, temperature, tools, and schema
-      chat.with_instructions(system_prompt, replace: replace) if system_prompt
-      chat.with_temperature(agent.temperature) if agent.temperature
-      chat.with_tools(*all_tools, replace: replace)
-      chat.with_schema(agent.response_schema) if agent.response_schema
+      chat.with_instructions(system_prompt)
+      chat.with_temperature(agent.temperature)
+      chat.with_thinking(**agent.thinking) if agent.thinking
+      chat.with_tools(nil) if replace
+      chat.with_tools(*all_tools)
+      chat.with_schema(agent.response_schema)
 
       chat
     end
@@ -458,19 +474,22 @@ module Agents
       return false unless input && chat.respond_to?(:messages)
 
       last_msg = chat.messages.last
-      last_msg && last_msg.role == :user && last_msg.content.to_s == input.to_s
+      return false unless last_msg&.role == :user
+
+      content, attachments = build_content(input)
+      last_msg.content == content && last_msg.attachments.map { |attachment| attachment.source.to_s } == attachments
     end
 
     def apply_headers(chat, headers)
       return if headers.empty?
 
-      chat.with_headers(**headers)
+      chat.with_headers(headers)
     end
 
     def apply_params(chat, params)
       return if params.empty?
 
-      chat.with_params(**params)
+      chat.with_provider_options(params)
     end
 
     def track_usage(response, context_wrapper)

data/lib/agents/tool.rb

@@ -20,7 +20,7 @@
 #   class WeatherTool < Agents::Tool
 #     name "get_weather"
 #     description "Get current weather for a location"
-#     param :location, type: "string", desc: "City name or coordinates"
+#     parameter :location, type: "string", description: "City name or coordinates"
 #
 #     def perform(tool_context, location:)
 #       # All state comes from parameters - no instance variables!
@@ -38,6 +38,13 @@
 #
 module Agents
   class Tool < RubyLLM::Tool
+    # Keep custom tools written for ai-agents 0.12 working with RubyLLM 2.
+    def self.param(name, **options)
+      old_description = options.delete(:desc)
+      options[:description] ||= old_description
+      parameter(name, **options)
+    end
+
     # Execute the tool with context injection.
     # This method is called by the runner and handles the thread-safe
     # execution pattern by passing all state through parameters.

data/lib/agents/tool_wrapper.rb

@@ -18,14 +18,14 @@ module Agents
   #
   # ## The Solution
   # Each Runner creates new wrapper instances for each execution, capturing the context
-  # in the wrapper's closure. When RubyLLM calls execute(), the wrapper injects the
+  # in the wrapper's closure. When RubyLLM calls call(), the wrapper injects the
   # context before calling the actual tool:
   #
   #   # Runner creates wrapper
   #   wrapped = ToolWrapper.new(my_tool, context_wrapper)
   #
   #   # RubyLLM calls wrapper
-  #   wrapped.execute(city: "NYC")  # No context parameter
+  #   wrapped.call(city: "NYC")  # No context parameter
   #
   #   # Wrapper injects context
   #   tool_context = ToolContext.new(run_context: context_wrapper)
@@ -40,11 +40,12 @@ module Agents
       # Copy tool metadata for RubyLLM
       @name = tool.name
       @description = tool.description
-      @params = tool.class.params if tool.class.respond_to?(:params)
     end
 
     # RubyLLM calls this method (follows RubyLLM::Tool pattern)
-    def call(args)
+    def call(tool_call: nil, **args) # rubocop:disable Lint/UnusedMethodArgument
+      return "Skipped after agent handoff" if @context_wrapper.context[:pending_handoff]
+
       tool_context = ToolContext.new(run_context: @context_wrapper)
 
       @context_wrapper.callback_manager.emit_tool_start(@tool.name, args, @context_wrapper)
@@ -54,7 +55,7 @@ module Agents
         @context_wrapper.callback_manager.emit_tool_complete(@tool.name, result, @context_wrapper)
         result
       rescue StandardError => e
-        @context_wrapper.callback_manager.emit_tool_complete(@tool.name, "ERROR: #{e.message}", @context_wrapper)
+        @context_wrapper.callback_manager.emit_tool_complete(@tool.name, "ERROR: #{e.message}", @context_wrapper, e)
         raise
       end
     end
@@ -68,18 +69,20 @@ module Agents
       @description || @tool.description
     end
 
-    # RubyLLM calls this to get parameter definitions
-    def parameters
-      @tool.parameters
+    def parameters_schema
+      @tool.parameters_schema
+    end
+
+    def provider_options
+      @tool.provider_options
     end
 
-    # Expose params schema for RubyLLM providers that expect it
-    def params_schema
-      @tool.respond_to?(:params_schema) ? @tool.params_schema : nil
+    def requires_approval?
+      @tool.requires_approval?
     end
 
-    def provider_params
-      @tool.respond_to?(:provider_params) ? @tool.provider_params : {}
+    def approval_resolver
+      @tool.approval_resolver
     end
 
     # Make this work with RubyLLM's tool calling

data/lib/agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

data/lib/agents.rb

@@ -53,6 +53,7 @@ module Agents
       apply_if_present(config, :openai_api_base)
       apply_if_present(config, :openai_organization_id)
       apply_if_present(config, :openai_project_id)
+      apply_if_present(config, :openai_protocol)
 
       # Other providers
       apply_if_present(config, :anthropic_api_key)
@@ -75,6 +76,7 @@ module Agents
       config.default_model = configuration.default_model
       config.log_level = configuration.debug == true ? :debug : :info
       apply_if_present(config, :request_timeout)
+      apply_if_present(config, :model_registry_file)
     end
 
     def apply_if_present(config, key)
@@ -85,13 +87,13 @@ module Agents
 
   class Configuration
     # Provider API keys and configuration
-    attr_accessor :openai_api_key, :openai_api_base, :openai_organization_id, :openai_project_id
+    attr_accessor :openai_api_key, :openai_api_base, :openai_organization_id, :openai_project_id, :openai_protocol
     attr_accessor :anthropic_api_key, :azure_api_base, :azure_api_key, :azure_ai_auth_token, :gemini_api_key,
                   :deepseek_api_key, :openrouter_api_key, :ollama_api_base, :bedrock_api_key, :bedrock_secret_key,
                   :bedrock_region, :bedrock_session_token
 
     # General configuration
-    attr_accessor :request_timeout, :default_model, :debug
+    attr_accessor :request_timeout, :default_model, :debug, :model_registry_file
 
     def initialize
       @default_model = "gpt-4o-mini"