ai-agents 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8fa7ec73784bc0fb1e9e6bd4852c6d0295160c4ca28d435c895cba28f5cd58
-  data.tar.gz: 3e489f11ae2a5c93b4232ec78e3c7385c83f303c28039ed35fa082669fedaf4b
+  metadata.gz: c143345c7d0dd3a91ff483e0db22a7d23f6c85393275727eddcaf288a1341901
+  data.tar.gz: 0f1abfe692571706be41b85a1da924a717f980b8721b21ece7dd62ad4e995fbf
 SHA512:
-  metadata.gz: ba5050ba743466993826d888673d90696d27f422df3d3972027fa141de05d6436c45cd44dba0836dc6350ad83c0ff1628ba43bbce6d93e5e49e8efc450554e91
-  data.tar.gz: efed7a181a6f52c4c8feb8b84e1bbb2309b5216a85569dae69dd4038cde0cdad7a283e066181414e50657aee063e79935573799fdc24abc6253b02bcb8e5d09f
+  metadata.gz: 74c96799a138a5e725b3e889eba22c45e9581e7606a0cd235cecd50b8bdde1c6f10281ec1516fde77f48373c39022d2f72172be8c29489260df79fb575d92de8
+  data.tar.gz: 257fd42a178107182a53eb737848ae1a023c28712ac450c4603b12cb60e2ad39dbe7b957a324bd6c24a3a175af8b7c373ec30e25e36425e81642a8f160da7ceb

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [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,78 @@
 #     { 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)
+        return nil unless msg.content && !content_empty?(msg.content)
 
-    message = {
-      role: msg.role,
-      content: msg.content
-    }
+        message = {
+          role: msg.role,
+          content: msg.content
+        }
 
-    if msg.role == :assistant
-      # Add agent attribution for conversation continuity
-      message[:agent_name] = current_agent.name if current_agent
+        if msg.role == :assistant
+          # Add agent attribution for conversation continuity
+          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)
-      end
-    end
+          # 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)
+          end
+        end
 
-    message
-  end
-  private_class_method :extract_user_or_assistant_message
+        message
+      end
+      private_class_method :extract_user_or_assistant_message
 
-  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_tool_message
+    end
   end
-  private_class_method :extract_tool_message
 end

data/lib/agents/runner.rb

@@ -90,6 +90,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 +103,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
@@ -127,18 +129,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 +173,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 +196,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

data/lib/agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.6.0"
+  VERSION = "0.7.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.7.0
 platform: ruby
 authors:
 - Shivam Mishra