ai-agents 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8fa7ec73784bc0fb1e9e6bd4852c6d0295160c4ca28d435c895cba28f5cd58
-  data.tar.gz: 3e489f11ae2a5c93b4232ec78e3c7385c83f303c28039ed35fa082669fedaf4b
+  metadata.gz: 6391e30443ff9e226e6b3bf3f629f3cd996cbb7fe4479c7a7dc437c82544ae2f
+  data.tar.gz: 22fc6ee4f3130006c1dd1f6c8fb704a176457d35602a434088d25cea5dd3c949
 SHA512:
-  metadata.gz: ba5050ba743466993826d888673d90696d27f422df3d3972027fa141de05d6436c45cd44dba0836dc6350ad83c0ff1628ba43bbce6d93e5e49e8efc450554e91
-  data.tar.gz: efed7a181a6f52c4c8feb8b84e1bbb2309b5216a85569dae69dd4038cde0cdad7a283e066181414e50657aee063e79935573799fdc24abc6253b02bcb8e5d09f
+  metadata.gz: ae3866cfbec885088c5b41b0e91bbc8532fc3115ed981c3428f56c09b40c1a75bc9bb1277ed1991f19cee4c43118c3f9a5d9ea8d6ecc07d29ad03117a77666e6
+  data.tar.gz: b7de2e98dc3ce52b4c80b7b1bcfa4fb1f07f62176d861ab61b9a1092d2de4273657d54edfa18d6afd83acccee21c89e465f18539b8966c5f9645a673b4e5a3c4

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-01-07
+
+### Added
+- **Provider Smoke Tests**: Comprehensive smoke tests for validating against the latest RubyLLM version
+
+### Changed
+- **RubyLLM Update**: Updated to latest RubyLLM version with improved API integration and tool call handling
+
+### Fixed
+- **Tool Message Restoration**: Fixed conversation history restoration to properly handle tool calls and results
+
+## [0.7.0] - 2025-10-16
+
+### Added
+- **Lifecycle Callback Hooks**: New callbacks for complete execution visibility and observability integration
+  - Added `on_run_start` callback triggered before agent execution begins with agent name, input, and run context
+  - Added `on_run_complete` callback triggered after execution ends (success or failure) with agent name, result, and run context
+  - Added `on_agent_complete` callback triggered after each agent turn with agent name, result, error (if any), and run context
+  - Run context parameter enables storing and retrieving custom data (e.g., span context, trace IDs) throughout execution
+  - Designed for integration with observability platforms (OpenTelemetry, Datadog, New Relic, etc.)
+  - All callbacks are thread-safe and non-blocking with proper error handling
+  - Updated callback documentation with integration patterns for UI feedback, logging, and metrics
+
+### Changed
+- CallbackManager now supports 7 event types (previously 4)
+- Enhanced callback system to provide complete lifecycle coverage for monitoring and tracing
+
 ## [0.6.0] - 2025-10-16
 
 ### Added

data/docs/concepts/callbacks.md

@@ -11,7 +11,13 @@ The AI Agents SDK provides real-time callbacks that allow you to monitor agent e
 
 ## Available Callbacks
 
-The SDK provides four types of callbacks that give you visibility into different stages of agent execution:
+The SDK provides seven types of callbacks that give you visibility into different stages of agent execution:
+
+**Run Start** - Triggered before agent execution begins. Receives the agent name, input message, and run context.
+
+**Run Complete** - Called after agent execution ends (whether successful or failed). Receives the agent name, result object, and run context.
+
+**Agent Complete** - Triggered after each agent turn finishes. Receives the agent name, result, error (if any), and run context.
 
 **Agent Thinking** - Triggered when an agent is about to make an LLM call. Useful for showing "thinking" indicators in UIs.
 
@@ -27,6 +33,9 @@ Callbacks are registered on the AgentRunner using chainable methods:
 
 ```ruby
 runner = Agents::Runner.with_agents(triage, support)
+  .on_run_start { |agent, input, ctx| puts "Starting: #{agent}" }
+  .on_run_complete { |agent, result, ctx| puts "Completed: #{agent}" }
+  .on_agent_complete { |agent, result, error, ctx| puts "Agent done: #{agent}" }
   .on_agent_thinking { |agent, input| puts "#{agent} thinking..." }
   .on_tool_start { |tool, args| puts "Using #{tool}" }
   .on_tool_complete { |tool, result| puts "#{tool} completed" }
@@ -35,7 +44,32 @@ runner = Agents::Runner.with_agents(triage, support)
 
 ## Integration Patterns
 
-Callbacks work well with real-time web frameworks like Rails ActionCable, allowing you to stream agent status updates directly to browser clients. They're also useful for logging, metrics collection, and building debug interfaces.
+### UI Feedback
+
+Callbacks work well with real-time web frameworks like Rails ActionCable, allowing you to stream agent status updates directly to browser clients:
+
+```ruby
+runner = Agents::Runner.with_agents(agent)
+  .on_agent_thinking { |agent, input|
+    ActionCable.server.broadcast("agent_#{user_id}", { type: 'thinking', agent: agent })
+  }
+  .on_tool_start { |tool, args|
+    ActionCable.server.broadcast("agent_#{user_id}", { type: 'tool', name: tool })
+  }
+```
+
+### Logging & Metrics
+
+Callbacks are also useful for structured logging and metrics collection:
+
+```ruby
+runner = Agents::Runner.with_agents(agent)
+  .on_run_start { |agent, input, ctx| logger.info("Run started", agent: agent) }
+  .on_tool_start { |tool, args| metrics.increment("tool.calls", tags: ["tool:#{tool}"]) }
+  .on_agent_complete do |agent, result, error, ctx|
+    logger.error("Agent failed", agent: agent, error: error) if error
+  end
+```
 
 ## Thread Safety
 

data/lib/agents/agent_runner.rb

@@ -44,6 +44,9 @@ module Agents
 
       # Initialize callback storage - use thread-safe arrays
       @callbacks = {
+        run_start: [],
+        run_complete: [],
+        agent_complete: [],
         tool_start: [],
         tool_complete: [],
         agent_thinking: [],
@@ -125,6 +128,42 @@ module Agents
       self
     end
 
+    # Register a callback for run start events.
+    # Called before agent execution begins.
+    #
+    # @param block [Proc] Callback block that receives (agent, input, run_context)
+    # @return [self] For method chaining
+    def on_run_start(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:run_start] << block }
+      self
+    end
+
+    # Register a callback for run complete events.
+    # Called after agent execution ends (success or error).
+    #
+    # @param block [Proc] Callback block that receives (agent, result, run_context)
+    # @return [self] For method chaining
+    def on_run_complete(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:run_complete] << block }
+      self
+    end
+
+    # Register a callback for agent complete events.
+    # Called after each agent turn finishes.
+    #
+    # @param block [Proc] Callback block that receives (agent_name, result, error, run_context)
+    # @return [self] For method chaining
+    def on_agent_complete(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:agent_complete] << block }
+      self
+    end
+
     private
 
     # Build agent registry from provided agents only.

data/lib/agents/callback_manager.rb

@@ -13,6 +13,9 @@ module Agents
   class CallbackManager
     # Supported callback event types
     EVENT_TYPES = %i[
+      run_start
+      run_complete
+      agent_complete
       tool_start
       tool_complete
       agent_thinking

data/lib/agents/helpers/headers.rb

@@ -1,29 +1,33 @@
 # frozen_string_literal: true
 
-module Agents::Helpers::Headers
-  module_function
+module Agents
+  module Helpers
+    module Headers
+      module_function
 
-  def normalize(headers, freeze_result: false)
-    return freeze_result ? {}.freeze : {} if headers.nil? || (headers.respond_to?(:empty?) && headers.empty?)
+      def normalize(headers, freeze_result: false)
+        return freeze_result ? {}.freeze : {} if headers.nil? || (headers.respond_to?(:empty?) && headers.empty?)
 
-    hash = headers.respond_to?(:to_h) ? headers.to_h : headers
-    raise ArgumentError, "headers must be a Hash or respond to #to_h" unless hash.is_a?(Hash)
+        hash = headers.respond_to?(:to_h) ? headers.to_h : headers
+        raise ArgumentError, "headers must be a Hash or respond to #to_h" unless hash.is_a?(Hash)
 
-    result = symbolize_keys(hash)
-    freeze_result ? result.freeze : result
-  end
+        result = symbolize_keys(hash)
+        freeze_result ? result.freeze : result
+      end
 
-  def merge(agent_headers, runtime_headers)
-    return runtime_headers if agent_headers.empty?
-    return agent_headers if runtime_headers.empty?
+      def merge(agent_headers, runtime_headers)
+        return runtime_headers if agent_headers.empty?
+        return agent_headers if runtime_headers.empty?
 
-    agent_headers.merge(runtime_headers) { |_key, _agent_value, runtime_value| runtime_value }
-  end
+        agent_headers.merge(runtime_headers) { |_key, _agent_value, runtime_value| runtime_value }
+      end
 
-  def symbolize_keys(hash)
-    hash.each_with_object({}) do |(key, value), memo|
-      memo[key.is_a?(Symbol) ? key : key.to_sym] = value
+      def symbolize_keys(hash)
+        hash.transform_keys do |key|
+          key.is_a?(Symbol) ? key : key.to_sym
+        end
+      end
+      private_class_method :symbolize_keys
     end
   end
-  private_class_method :symbolize_keys
 end

data/lib/agents/helpers/message_extractor.rb

@@ -15,74 +15,87 @@
 #     { role: :assistant, content: "Hi!", agent_name: "Support", tool_calls: [...] },
 #     { role: :tool, content: "Result", tool_call_id: "call_123" }
 #   ]
-module Agents::Helpers::MessageExtractor
-  module_function
+module Agents
+  module Helpers
+    module MessageExtractor
+      module_function
 
-  # Check if content is considered empty (handles both String and Hash content)
-  #
-  # @param content [String, Hash, nil] The content to check
-  # @return [Boolean] true if content is empty, false otherwise
-  def content_empty?(content)
-    case content
-    when String
-      content.strip.empty?
-    when Hash
-      content.empty?
-    else
-      content.nil?
-    end
-  end
+      # Check if content is considered empty (handles both String and Hash content)
+      #
+      # @param content [String, Hash, nil] The content to check
+      # @return [Boolean] true if content is empty, false otherwise
+      def content_empty?(content)
+        case content
+        when String
+          content.strip.empty?
+        when Hash
+          content.empty?
+        else
+          content.nil?
+        end
+      end
 
-  # Extract messages from a chat object for conversation history persistence
-  #
-  # @param chat [Object] Chat object that responds to :messages
-  # @param current_agent [Agent] The agent currently handling the conversation
-  # @return [Array<Hash>] Array of message hashes suitable for persistence
-  def extract_messages(chat, current_agent)
-    return [] unless chat.respond_to?(:messages)
+      # Extract messages from a chat object for conversation history persistence
+      #
+      # @param chat [Object] Chat object that responds to :messages
+      # @param current_agent [Agent] The agent currently handling the conversation
+      # @return [Array<Hash>] Array of message hashes suitable for persistence
+      def extract_messages(chat, current_agent)
+        return [] unless chat.respond_to?(:messages)
 
-    chat.messages.filter_map do |msg|
-      case msg.role
-      when :user, :assistant
-        extract_user_or_assistant_message(msg, current_agent)
-      when :tool
-        extract_tool_message(msg)
+        chat.messages.filter_map do |msg|
+          case msg.role
+          when :user, :assistant
+            extract_user_or_assistant_message(msg, current_agent)
+          when :tool
+            extract_tool_message(msg)
+          end
+        end
       end
-    end
-  end
 
-  def extract_user_or_assistant_message(msg, current_agent)
-    return nil unless msg.content && !content_empty?(msg.content)
+      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
+
+        message = {
+          role: msg.role,
+          content: content_present ? msg.content : ""
+        }
 
-    message = {
-      role: msg.role,
-      content: msg.content
-    }
+        return message unless msg.role == :assistant
 
-    if msg.role == :assistant
-      # Add agent attribution for conversation continuity
-      message[:agent_name] = current_agent.name if current_agent
+        message[:agent_name] = current_agent.name if current_agent
 
-      # Add tool calls if present
-      if msg.tool_call? && msg.tool_calls
-        # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
-        # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
-        message[:tool_calls] = msg.tool_calls.values.map(&:to_h)
+        if tool_calls_present
+          # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
+          # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
+          message[:tool_calls] = msg.tool_calls.values.map(&:to_h)
+        end
+
+        message
       end
-    end
 
-    message
-  end
-  private_class_method :extract_user_or_assistant_message
+      def message_content?(msg)
+        msg.content && !content_empty?(msg.content)
+      end
+
+      def assistant_tool_calls?(msg)
+        msg.role == :assistant && msg.tool_call? && msg.tool_calls && !msg.tool_calls.empty?
+      end
 
-  def extract_tool_message(msg)
-    return nil unless msg.tool_result?
+      def extract_tool_message(msg)
+        return nil unless msg.tool_result?
 
-    {
-      role: msg.role,
-      content: msg.content,
-      tool_call_id: msg.tool_call_id
-    }
+        {
+          role: msg.role,
+          content: msg.content,
+          tool_call_id: msg.tool_call_id
+        }
+      end
+
+      private_class_method :extract_user_or_assistant_message, :message_content?, :assistant_tool_calls?,
+                           :extract_tool_message
+    end
   end
-  private_class_method :extract_tool_message
 end

data/lib/agents/run_context.rb

@@ -94,15 +94,21 @@ module Agents
       end
 
       # Add usage metrics from an LLM response to the running totals.
-      # Safely handles nil values in the usage object.
+      # Only tracks usage for responses that have token data (e.g., RubyLLM::Message).
+      # Safely skips responses without token methods (e.g., RubyLLM::Tool::Halt).
       #
-      # @param usage [Object] An object responding to input_tokens, output_tokens, and total_tokens
+      # @param response [RubyLLM::Message] A RubyLLM::Message object with token usage data
       # @example Adding usage from an LLM response
-      #   usage.add(llm_response.usage)
-      def add(usage)
-        @input_tokens += usage.input_tokens || 0
-        @output_tokens += usage.output_tokens || 0
-        @total_tokens += usage.total_tokens || 0
+      #   usage.add(llm_response)
+      def add(response)
+        return unless response.respond_to?(:input_tokens)
+
+        input = response.input_tokens || 0
+        output = response.output_tokens || 0
+
+        @input_tokens += input
+        @output_tokens += output
+        @total_tokens += input + output
       end
     end
   end

data/lib/agents/runner.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Agents
   # The execution engine that orchestrates conversations between users and agents.
   # Runner manages the conversation flow, handles tool execution through RubyLLM,
@@ -90,6 +92,9 @@ module Agents
       context_wrapper = RunContext.new(context_copy, callbacks: callbacks)
       current_turn = 0
 
+      # Emit run start event
+      context_wrapper.callback_manager.emit_run_start(current_agent.name, input, context_wrapper)
+
       runtime_headers = Helpers::Headers.normalize(headers)
       agent_headers = Helpers::Headers.normalize(current_agent.headers)
 
@@ -100,7 +105,6 @@ module Agents
       configure_chat_for_agent(chat, current_agent, context_wrapper, replace: false)
       restore_conversation_history(chat, context_wrapper)
 
-
       loop do
         current_turn += 1
         raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
@@ -116,6 +120,7 @@ module Agents
                    chat.complete
                  end
         response = result
+        track_usage(response, context_wrapper)
 
         # Check for handoff via RubyLLM's halt mechanism
         if response.is_a?(RubyLLM::Tool::Halt) && context_wrapper.context[:pending_handoff]
@@ -127,18 +132,28 @@ module Agents
           unless registry[next_agent.name]
             save_conversation_state(chat, context_wrapper, current_agent)
             error = AgentNotFoundError.new("Handoff failed: Agent '#{next_agent.name}' not found in registry")
-            return RunResult.new(
+
+            result = RunResult.new(
               output: nil,
               messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
               usage: context_wrapper.usage,
               context: context_wrapper.context,
               error: error
             )
+
+            # Emit agent complete and run complete events with error
+            context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, error, context_wrapper)
+            context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+
+            return result
           end
 
           # Save current conversation state before switching
           save_conversation_state(chat, context_wrapper, current_agent)
 
+          # Emit agent complete event before handoff
+          context_wrapper.callback_manager.emit_agent_complete(current_agent.name, nil, nil, context_wrapper)
+
           # Emit agent handoff event
           context_wrapper.callback_manager.emit_agent_handoff(current_agent.name, next_agent.name, "handoff")
 
@@ -161,12 +176,19 @@ module Agents
         # Handle non-handoff halts - return the halt content as final response
         if response.is_a?(RubyLLM::Tool::Halt)
           save_conversation_state(chat, context_wrapper, current_agent)
-          return RunResult.new(
+
+          result = RunResult.new(
             output: response.content,
             messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
             usage: context_wrapper.usage,
             context: context_wrapper.context
           )
+
+          # Emit agent complete and run complete events
+          context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, nil, context_wrapper)
+          context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+
+          return result
         end
 
         # If tools were called, continue the loop to let them execute
@@ -177,35 +199,53 @@ module Agents
         # Save final state before returning
         save_conversation_state(chat, context_wrapper, current_agent)
 
-        return RunResult.new(
+        result = RunResult.new(
           output: response.content,
           messages: Helpers::MessageExtractor.extract_messages(chat, current_agent),
           usage: context_wrapper.usage,
           context: context_wrapper.context
         )
+
+        # Emit agent complete and run complete events
+        context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, nil, context_wrapper)
+        context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+
+        return result
       end
     rescue MaxTurnsExceeded => e
       # Save state even on error
       save_conversation_state(chat, context_wrapper, current_agent) if chat
 
-      RunResult.new(
+      result = RunResult.new(
         output: "Conversation ended: #{e.message}",
         messages: chat ? Helpers::MessageExtractor.extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
       )
+
+      # Emit agent complete and run complete events with error
+      context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, e, context_wrapper)
+      context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+
+      result
     rescue StandardError => e
       # Save state even on error
       save_conversation_state(chat, context_wrapper, current_agent) if chat
 
-      RunResult.new(
+      result = RunResult.new(
         output: nil,
         messages: chat ? Helpers::MessageExtractor.extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
       )
+
+      # Emit agent complete and run complete events with error
+      context_wrapper.callback_manager.emit_agent_complete(current_agent.name, result, e, context_wrapper)
+      context_wrapper.callback_manager.emit_run_complete(current_agent.name, result, context_wrapper)
+
+      result
     end
 
     private
@@ -227,26 +267,98 @@ module Agents
 
     # Restores conversation history from context into RubyLLM chat.
     # Converts stored message hashes back into RubyLLM::Message objects with proper content handling.
+    # Supports user, assistant, and tool role messages for complete conversation continuity.
     #
     # @param chat [RubyLLM::Chat] The chat instance to restore history into
     # @param context_wrapper [RunContext] Context containing conversation history
     def restore_conversation_history(chat, context_wrapper)
       history = context_wrapper.context[:conversation_history] || []
+      valid_tool_call_ids = Set.new
 
       history.each do |msg|
-        # Only restore user and assistant messages with content
-        next unless %i[user assistant].include?(msg[:role].to_sym)
-        next unless msg[:content] && !Helpers::MessageExtractor.content_empty?(msg[:content])
+        next unless restorable_message?(msg)
 
-        # Extract text content safely - handle both string and hash content
-        content = RubyLLM::Content.new(msg[:content])
+        if msg[:role].to_sym == :tool &&
+           msg[:tool_call_id] &&
+           !valid_tool_call_ids.include?(msg[:tool_call_id])
+          Agents.logger&.warn("Skipping tool message without matching assistant tool_call_id #{msg[:tool_call_id]}")
+          next
+        end
 
-        # Create a proper RubyLLM::Message and pass it to add_message
-        message = RubyLLM::Message.new(
-          role: msg[:role].to_sym,
-          content: content
-        )
+        message_params = build_message_params(msg)
+        next unless message_params # Skip invalid messages
+
+        message = RubyLLM::Message.new(**message_params)
         chat.add_message(message)
+
+        if message.role == :assistant && message_params[:tool_calls]
+          valid_tool_call_ids.merge(message_params[:tool_calls].keys)
+        end
+      end
+    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])
+
+      true
+    end
+
+    # Build message parameters for restoration
+    def build_message_params(msg)
+      role = msg[:role].to_sym
+
+      content_value = msg[:content]
+      # 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: RubyLLM::Content.new(content_value)
+      }
+
+      # Handle tool-specific parameters (Tool Results)
+      if role == :tool
+        return nil unless valid_tool_message?(msg)
+
+        params[:tool_call_id] = msg[:tool_call_id]
+      end
+
+      # FIX: Restore tool_calls on assistant messages
+      # This is required by OpenAI/Anthropic API contracts to link
+      # subsequent tool result messages back to this request.
+      if role == :assistant && msg[:tool_calls] && !msg[:tool_calls].empty?
+        # Convert stored array of hashes back into the Hash format RubyLLM expects
+        # RubyLLM stores tool_calls as: { call_id => ToolCall_object, ... }
+        # Reference: openai/tools.rb:35 uses hash iteration |_, tc|
+        params[:tool_calls] = msg[:tool_calls].each_with_object({}) do |tc, hash|
+          tool_call_id = tc[:id] || tc["id"]
+          next unless tool_call_id
+
+          hash[tool_call_id] = RubyLLM::ToolCall.new(
+            id: tool_call_id,
+            name: tc[:name] || tc["name"],
+            arguments: tc[:arguments] || tc["arguments"] || {}
+          )
+        end
+      end
+
+      params
+    end
+
+    # Validate tool message has required tool_call_id
+    def valid_tool_message?(msg)
+      if msg[:tool_call_id]
+        true
+      else
+        Agents.logger&.warn("Skipping tool message without tool_call_id in conversation history")
+        false
       end
     end
 
@@ -303,6 +415,12 @@ module Agents
       chat.with_headers(**headers)
     end
 
+    def track_usage(response, context_wrapper)
+      return unless context_wrapper&.usage
+
+      context_wrapper.usage.add(response)
+    end
+
     # Builds thread-safe tool wrappers for an agent's tools and handoff tools.
     #
     # @param agent [Agents::Agent] The agent whose tools to wrap

data/lib/agents/tool_wrapper.rb

@@ -73,6 +73,15 @@ module Agents
       @tool.parameters
     end
 
+    # Expose params schema for RubyLLM providers that expect it
+    def params_schema
+      @tool.respond_to?(:params_schema) ? @tool.params_schema : nil
+    end
+
+    def provider_params
+      @tool.respond_to?(:provider_params) ? @tool.provider_params : {}
+    end
+
     # Make this work with RubyLLM's tool calling
     def to_s
       name

data/lib/agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Shivam Mishra
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.2
+        version: 1.9.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.8.2
+        version: 1.9.1
 description: Ruby AI Agents SDK enables creating complex AI workflows with multi-agent
   orchestration, tool execution, safety guardrails, and provider-agnostic LLM integration.
 email: