ai-agents 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63e05456e057d627b1b3a3f75bfbbf5753b7dc7521fc429376681d6ffe222e54
-  data.tar.gz: 354528a7d4eae51c5598b41ad7fbfb77ec715e9354469c827074a974cb1e43c4
+  metadata.gz: b2d0dbff300d9f3bd08da74d39e1fbf2eecbfa0b293558af01b5ecfcc765d58c
+  data.tar.gz: 84a94feb4a5faea46ec658159f1266d315ba8175ad8b4c62915745c6e430c741
 SHA512:
-  metadata.gz: 1d6ff99299ba88e2fba47cff1fb13f686e30bf4826014da7bec95b7363609f8b6acc2bb69a86393786d048bd693d4b1efb2697cd6a7376abe0a81f6ea347da0d
-  data.tar.gz: 43fb8db36d106caff7220bcdc4f6dba063a0b82b208baf757a7ffa578d7dde8dd917cff408cfa897037c0a2c6efbe004685399bbe93dce92958575f1181112f8
+  metadata.gz: 7bb4ab502f7c3362a3bc6f3549c30166f5e8e19d5f9aee7c3bf1fe17af334ae765122ecbff8c6b045aa28d5fac6e639dd5f56002ab7b24626ed0b2aae36eba48
+  data.tar.gz: 185d68208135a2f24b5ad8f5bbc075cdf06bcd54bad1b99f7910050224439bb8aacdec7a5c64f9768f7ec9cebdea9efa9e33734db4a650dd97bb16de901a00b5

data/.claude/commands/bump-version.md

@@ -0,0 +1,44 @@
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+description: Bump version, update changelog and commit changes
+---
+
+You need to bump the version of the ruby gem and update the CHANGELOG. We need a #$ARGUMENTS version bump.
+
+The types of version jumps are
+
+- patch: Increment the third number in the version number.
+- minor: Increment the second number in the version number.
+- major: Increment the first number in the version number.
+
+To bump up the version, follow these steps:
+
+1. Update the version number in the `lib/agents/version.rb` file.
+2. Run `bundle install` to ensure the lock file picks up the new version.
+
+To update the changelog.
+
+1. Find the changelog file in `CHANGELOG.md`.
+2. Add a new section for the new version number.
+3. List the changes made in the new version.
+
+We follow the `keepachangelog.com` guide for writing these changelogs and follow semantic versioning.
+
+Here's what makes a good changelog.
+
+**Guiding Principles**
+- Changelogs are for humans, not machines.
+- There should be an entry for every single version.
+- The same types of changes should be grouped.
+- Versions and sections should be linkable.
+- The latest version comes first.
+
+**Types of changes**
+`Added` for new features.
+`Changed` for changes in existing functionality.
+`Deprecated` for soon-to-be removed features.
+`Removed` for now removed features.
+`Fixed` for any bug fixes.
+`Security` in case of vulnerabilities
+
+Once done, commit the changes with a message like "chore: bump version to <new-version>".

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+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.2.0] - 2025-07-08
+
+### Added
+- Real-time callback system for monitoring agent execution
+  - `on_agent_thinking` callback for when agents are processing
+  - `on_tool_start` callback for when tools begin execution
+  - `on_tool_complete` callback for when tools finish execution
+  - `on_agent_handoff` callback for when control transfers between agents
+- Enhanced conversation history with complete tool call audit trail
+  - Tool calls now captured in assistant messages with arguments
+  - Tool result messages linked to original calls via `tool_call_id`
+  - Full conversation replay capability for debugging
+- CallbackManager for centralized event handling
+- MessageExtractor service for clean conversation history processing
+
+### Changed
+- RunContext now includes callback management capabilities
+- Improved thread safety for callback execution
+- Enhanced error handling for callback failures (non-blocking)
+
+## [0.1.3] - Previous Release
+
+### Added
+- Multi-agent orchestration with seamless handoffs
+- Thread-safe agent execution architecture
+- Tool integration system
+- Shared context management
+- Provider support for OpenAI, Anthropic, and Gemini

data/CLAUDE.md

@@ -9,6 +9,7 @@ This project is a Ruby SDK for building multi-agent AI workflows. It allows deve
 -   **Multi-Agent Orchestration**: Defining and managing multiple AI agents with distinct roles.
 -   **Seamless Handoffs**: Transferring conversations between agents without the user's knowledge.
 -   **Tool Integration**: Allowing agents to use custom tools to interact with external systems.
+-   **Real-time Callbacks**: Event-driven system for monitoring agent execution, tool usage, and handoffs.
 -   **Shared Context**: Maintaining state and conversation history across agent interactions with full persistence support.
 -   **Thread-Safe Architecture**: Reusable agent runners that work safely across multiple threads.
 -   **Provider Agnostic**: Supporting various LLM providers like OpenAI, Anthropic, and Gemini.
@@ -52,6 +53,7 @@ ruby examples/isp-support/interactive.rb
 
 This will start a command-line interface where you can interact with the multi-agent system. The example demonstrates:
 - Thread-safe agent runner creation
+- Real-time callback system with UI feedback
 - Automatic agent selection based on conversation history
 - Context persistence that works across process boundaries
 - Seamless handoffs between triage, sales, and support agents
@@ -64,6 +66,7 @@ This will start a command-line interface where you can interact with the multi-a
 -   **AgentRunner**: The thread-safe execution manager that coordinates multi-agent conversations and provides the main API.
 -   **Runner**: Internal component that manages individual conversation turns (used by AgentRunner).
 -   **Context**: A shared state object that stores conversation history and agent information, fully serializable for persistence.
+-   **Callbacks**: Event hooks for monitoring agent execution, including agent thinking, tool start/complete, and handoffs.
 
 ## Development Commands
 
@@ -111,10 +114,12 @@ ruby examples/isp-support/interactive.rb
 ### Core Components
 
 - **Agents::Agent**: Individual AI agents with specific roles, instructions, and tools
+- **Agents::AgentRunner**: Thread-safe execution manager with callback support
 - **Agents::Runner**: Orchestrates multi-agent conversations with automatic handoffs
 - **Agents::Tool**: Base class for custom tools that agents can execute
 - **Agents::Context**: Shared state management across agent interactions
 - **Agents::Handoff**: Manages seamless transfers between agents
+- **Agents::CallbackManager**: Centralized event handling for real-time monitoring
 
 ### Key Design Principles
 
@@ -129,17 +134,19 @@ ruby examples/isp-support/interactive.rb
 
 ```
 lib/agents/
-├── agent.rb          # Core agent definition and configuration
-├── agent_runner.rb   # Thread-safe execution manager (main API)
-├── runner.rb         # Internal execution engine for conversation turns
-├── tool.rb           # Base class for custom tools
-├── handoff.rb        # Agent handoff management
-├── chat.rb           # Chat message handling
-├── result.rb         # Result object for agent responses
-├── run_context.rb    # Execution context management
-├── tool_context.rb   # Tool execution context
-├── tool_wrapper.rb   # Thread-safe tool wrapping
-└── version.rb        # Gem version
+├── agent.rb            # Core agent definition and configuration
+├── agent_runner.rb     # Thread-safe execution manager (main API)
+├── runner.rb           # Internal execution engine for conversation turns
+├── tool.rb             # Base class for custom tools
+├── handoff.rb          # Agent handoff management
+├── chat.rb             # Chat message handling
+├── result.rb           # Result object for agent responses
+├── run_context.rb      # Execution context management
+├── tool_context.rb     # Tool execution context
+├── tool_wrapper.rb     # Thread-safe tool wrapping
+├── callback_manager.rb # Centralized callback event handling
+├── message_extractor.rb # Conversation history processing
+└── version.rb          # Gem version
 ```
 
 ### Configuration
@@ -167,7 +174,13 @@ support = Agent.new(name: "Support", instructions: "Technical support...")
 triage.register_handoffs(billing, support)
 
 # Create thread-safe runner (first agent is default entry point)
-runner = Agents::Runner.with_agents(triage, billing, support)
+runner = Agents::AgentRunner.with_agents(triage, billing, support)
+
+# Add real-time callbacks for monitoring
+runner.on_agent_thinking { |agent_name, input| puts "🧠 #{agent_name} is thinking..." }
+runner.on_tool_start { |tool_name, args| puts "🔧 Using #{tool_name}..." }
+runner.on_tool_complete { |tool_name, result| puts "✅ #{tool_name} completed" }
+runner.on_agent_handoff { |from, to, reason| puts "🔄 Handoff: #{from} → #{to}" }
 
 # Use for conversations - automatically handles agent selection and persistence
 result = runner.run("I have a billing question")
@@ -184,10 +197,18 @@ When creating custom tools:
 
 ### Testing Strategy
 
+The codebase follows comprehensive testing patterns with strong emphasis on thread safety and isolation, here's some points to note
+
 - SimpleCov tracks coverage with 50% minimum overall, 40% per file
-- WebMock is used for HTTP mocking in tests
-- RSpec is the testing framework with standard configuration
-- Tests are organized by component in `spec/agents/`
+- RSpec testing framework with descriptive context blocks
+- Tests organized by component in `spec/agents/` mirroring lib structure
+- **Instance Doubles**: Extensive use of `instance_double` for clean dependency mocking, never use generic `double` or `stub`
+- **WebMock**: HTTP call stubbing with network isolation (`WebMock.disable_net_connect!`)
+- Unit tests for individual components
+- Integration tests for complex workflows
+- Thread-safety tests for concurrent scenarios
+- Clear separation of setup, execution, and assertion phases
+- Context description should always match /^when\b/, /^with\b/, or /^without\b/.
 
 ### Examples
 
@@ -195,3 +216,26 @@ The `examples/` directory contains complete working examples:
 - `isp-support/`: Multi-agent ISP customer support system
 - Shows hub-and-spoke architecture patterns
 - Demonstrates tool integration and handoff workflows
+- Includes real-time callback implementation for UI feedback
+
+## Callback System
+
+The SDK includes a comprehensive callback system for monitoring agent execution in real-time. This is particularly useful for:
+
+- **UI Feedback**: Show users what's happening during agent execution
+- **Debugging**: Track tool usage and agent handoffs
+- **Analytics**: Monitor system performance and usage patterns
+- **Rails Integration**: Stream updates via ActionCable
+
+### Available Callbacks
+
+- `on_agent_thinking`: Triggered when an agent starts processing
+- `on_tool_start`: Triggered when a tool begins execution
+- `on_tool_complete`: Triggered when a tool finishes execution
+- `on_agent_handoff`: Triggered when control transfers between agents
+
+### Callback Integration
+
+Callbacks are thread-safe and non-blocking. If a callback raises an exception, it won't interrupt agent execution. The system uses a centralized CallbackManager for efficient event handling.
+
+For detailed callback documentation, see `docs/concepts/callbacks.md`.

data/docs/concepts/callbacks.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Callbacks
+parent: Concepts
+nav_order: 6
+---
+
+# Real-time Callbacks
+
+The AI Agents SDK provides real-time callbacks that allow you to monitor agent execution as it happens. This is particularly useful for building user interfaces that show live feedback about what agents are doing.
+
+## Available Callbacks
+
+The SDK provides four types of callbacks that give you visibility into different stages of agent execution:
+
+**Agent Thinking** - Triggered when an agent is about to make an LLM call. Useful for showing "thinking" indicators in UIs.
+
+**Tool Start** - Called when an agent begins executing a tool. Shows which tool is being used and with what arguments.
+
+**Tool Complete** - Triggered when a tool finishes execution. Provides the tool name and result for status updates.
+
+**Agent Handoff** - Called when control transfers between agents. Shows the source agent, target agent, and handoff reason.
+
+## Basic Usage
+
+Callbacks are registered on the AgentRunner using chainable methods:
+
+```ruby
+runner = Agents::AgentRunner.with_agents(triage, support)
+  .on_agent_thinking { |agent, input| puts "#{agent} thinking..." }
+  .on_tool_start { |tool, args| puts "Using #{tool}" }
+  .on_tool_complete { |tool, result| puts "#{tool} completed" }
+  .on_agent_handoff { |from, to, reason| puts "#{from} → #{to}" }
+```
+
+## 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.
+
+## Thread Safety
+
+Callbacks execute synchronously in the same thread as agent execution. Exceptions in callbacks are caught and logged as warnings without interrupting agent operation. For heavy operations or external API calls, consider using background jobs triggered by the callbacks.

data/docs/concepts.md

@@ -18,4 +18,5 @@ The AI Agents library is built around several key concepts that work together to
 - **[Context](concepts/context.html)** - Serializable state management that persists across agent interactions
 - **[Handoffs](concepts/handoffs.html)** - Tool-based mechanism for seamless agent transitions
 - **[Tools](concepts/tools.html)** - Stateless extensions for external system integration
+- **[Callbacks](concepts/callbacks.html)** - Real-time notifications for agent thinking, tool execution, and handoffs
 - **[AgentTool](concepts/agent-tool.html)** - Agent-to-agent collaboration without conversation handoffs

data/docs/index.md

@@ -26,6 +26,7 @@ AI Agents is a Ruby SDK that enables developers to create sophisticated multi-ag
 - **Multi-Agent Orchestration**: Define and manage multiple AI agents with distinct roles
 - **Seamless Handoffs**: Transfer conversations between agents without user knowledge
 - **Tool Integration**: Allow agents to use custom tools to interact with external systems
+- **Callbacks**: Real-time notifications for agent thinking, tool execution, and handoffs
 - **Shared Context**: Maintain state and conversation history across agent interactions
 - **Thread-Safe Architecture**: Reusable agent runners that work safely across multiple threads
 - **Provider Agnostic**: Support for OpenAI, Anthropic, and Gemini
@@ -93,3 +94,4 @@ puts result.output
 - [Working with Tools](concepts/tools.html)
 - [Agent Handoffs](concepts/handoffs.html)
 - [Using the Runner](concepts/runner.html)
+- [Callbacks](concepts/callbacks.html)

data/examples/isp-support/interactive.rb

@@ -14,16 +14,20 @@ class ISPSupportDemo
     end
 
     # Create agents
-    agents = ISPSupport::AgentsFactory.create_agents
+    @agents = ISPSupport::AgentsFactory.create_agents
 
     # Create thread-safe runner with all agents (triage first = default entry point)
     @runner = Agents::Runner.with_agents(
-      agents[:triage],
-      agents[:sales],
-      agents[:support]
+      @agents[:triage],
+      @agents[:sales],
+      @agents[:support]
     )
 
+    # Setup real-time callbacks for UI feedback
+    setup_callbacks
+
     @context = {}
+    @current_status = ""
 
     puts "🏢 Welcome to ISP Customer Support!"
     puts "Type '/help' for commands or 'exit' to quit."
@@ -39,12 +43,18 @@ class ISPSupportDemo
       break if command_result == :exit
       next if command_result == :handled || user_input.empty?
 
+      # Clear any previous status and show agent is working
+      clear_status_line
+      print "🤖 Processing..."
+
       # Use the runner - it automatically determines the right agent from context
       result = @runner.run(user_input, context: @context)
 
       # Update our context with the returned context from Runner
       @context = result.context if result.respond_to?(:context) && result.context
 
+      # Clear status and show response
+      clear_status_line
       puts "🤖 #{result.output || "[No output]"}"
 
       puts
@@ -53,6 +63,35 @@ class ISPSupportDemo
 
   private
 
+  def setup_callbacks
+    @runner.on_agent_thinking do |agent_name, _input|
+      update_status("🧠 #{agent_name} is thinking...")
+    end
+
+    @runner.on_tool_start do |tool_name, _args|
+      update_status("🔧 Using #{tool_name}...")
+    end
+
+    @runner.on_tool_complete do |tool_name, _result|
+      update_status("✅ #{tool_name} completed")
+    end
+
+    @runner.on_agent_handoff do |from_agent, to_agent, _reason|
+      update_status("🔄 Handoff: #{from_agent} → #{to_agent}")
+    end
+  end
+
+  def update_status(message)
+    clear_status_line
+    print message
+    $stdout.flush
+  end
+
+  def clear_status_line
+    print "\r#{" " * 80}\r" # Clear the current line
+    $stdout.flush
+  end
+
   def handle_command(input)
     case input.downcase
     when "exit", "quit"

data/lib/agents/agent_runner.rb

@@ -11,6 +11,8 @@ module Agents
   # ## Usage Pattern
   #   # Create once (typically at application startup)
   #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+  #     .on_tool_start { |tool_name, args| broadcast_event('tool_start', tool_name, args) }
+  #     .on_tool_complete { |tool_name, result| broadcast_event('tool_complete', tool_name, result) }
   #
   #   # Use safely from multiple threads
   #   result = runner.run("I need billing help")           # New conversation
@@ -22,6 +24,10 @@ module Agents
   # - Each run() call creates independent execution context
   # - No shared mutable state between concurrent executions
   #
+  # ## Callback Thread Safety
+  # Callback registration is thread-safe using internal synchronization. Multiple threads
+  # can safely register callbacks concurrently without data races.
+  #
   class AgentRunner
     # Initialize with a list of agents. The first agent becomes the default entry point.
     #
@@ -30,10 +36,19 @@ module Agents
       raise ArgumentError, "At least one agent must be provided" if agents.empty?
 
       @agents = agents.dup.freeze
+      @callbacks_mutex = Mutex.new
       @default_agent = agents.first
 
       # Build simple registry from provided agents - developer controls what's available
       @registry = build_registry(agents).freeze
+
+      # Initialize callback storage - use thread-safe arrays
+      @callbacks = {
+        tool_start: [],
+        tool_complete: [],
+        agent_thinking: [],
+        agent_handoff: []
+      }
     end
 
     # Execute a conversation turn with automatic agent selection.
@@ -50,15 +65,65 @@ module Agents
       current_agent = determine_conversation_agent(context)
 
       # Execute using stateless Runner - each execution is independent and thread-safe
+      # Pass callbacks to enable real-time event notifications
       Runner.new.run(
         current_agent,
         input,
         context: context,
         registry: @registry,
-        max_turns: max_turns
+        max_turns: max_turns,
+        callbacks: @callbacks
       )
     end
 
+    # Register a callback for tool start events.
+    # Called when an agent is about to execute a tool.
+    #
+    # @param block [Proc] Callback block that receives (tool_name, args)
+    # @return [self] For method chaining
+    def on_tool_start(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:tool_start] << block }
+      self
+    end
+
+    # Register a callback for tool completion events.
+    # Called when an agent has finished executing a tool.
+    #
+    # @param block [Proc] Callback block that receives (tool_name, result)
+    # @return [self] For method chaining
+    def on_tool_complete(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:tool_complete] << block }
+      self
+    end
+
+    # Register a callback for agent thinking events.
+    # Called when an agent is about to make an LLM call.
+    #
+    # @param block [Proc] Callback block that receives (agent_name, input)
+    # @return [self] For method chaining
+    def on_agent_thinking(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:agent_thinking] << block }
+      self
+    end
+
+    # Register a callback for agent handoff events.
+    # Called when control is transferred from one agent to another.
+    #
+    # @param block [Proc] Callback block that receives (from_agent, to_agent, reason)
+    # @return [self] For method chaining
+    def on_agent_handoff(&block)
+      return self unless block
+
+      @callbacks_mutex.synchronize { @callbacks[:agent_handoff] << block }
+      self
+    end
+
     private
 
     # Build agent registry from provided agents only.

data/lib/agents/callback_manager.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Agents
+  # Manager for handling and emitting callback events in a thread-safe manner.
+  # Provides both generic emit() method and typed convenience methods.
+  #
+  # @example Using generic emit
+  #   manager.emit(:tool_start, tool_name, args)
+  #
+  # @example Using typed methods
+  #   manager.emit_tool_start(tool_name, args)
+  #   manager.emit_agent_thinking(agent_name, input)
+  class CallbackManager
+    # Supported callback event types
+    EVENT_TYPES = %i[
+      tool_start
+      tool_complete
+      agent_thinking
+      agent_handoff
+    ].freeze
+
+    def initialize(callbacks = {})
+      @callbacks = callbacks.dup.freeze
+    end
+
+    # Generic method to emit any callback event type
+    #
+    # @param event_type [Symbol] The type of event to emit
+    # @param args [Array] Arguments to pass to callbacks
+    def emit(event_type, *args)
+      callback_list = @callbacks[event_type] || []
+
+      callback_list.each do |callback|
+        callback.call(*args)
+      rescue StandardError => e
+        # Log callback errors but don't let them crash execution
+        warn "Callback error for #{event_type}: #{e.message}"
+      end
+    end
+
+    # Metaprogramming: Create typed emit methods for each event type
+    #
+    # This generates methods like:
+    #   emit_tool_start(tool_name, args)
+    #   emit_tool_complete(tool_name, result)
+    #   emit_agent_thinking(agent_name, input)
+    #   emit_agent_handoff(from_agent, to_agent, reason)
+    EVENT_TYPES.each do |event_type|
+      define_method("emit_#{event_type}") do |*args|
+        emit(event_type, *args)
+      end
+    end
+  end
+end

data/lib/agents/message_extractor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Agents
+  # Service object responsible for extracting and formatting conversation messages
+  # from RubyLLM chat objects into a format suitable for persistence and context restoration.
+  #
+  # Handles different message types:
+  # - User messages: Basic content preservation
+  # - Assistant messages: Includes agent attribution and tool calls
+  # - Tool result messages: Links back to original tool calls
+  #
+  # @example Extract messages from a chat
+  #   messages = MessageExtractor.extract_messages(chat, current_agent)
+  #   #=> [
+  #     { role: :user, content: "Hello" },
+  #     { role: :assistant, content: "Hi!", agent_name: "Support", tool_calls: [...] },
+  #     { role: :tool, content: "Result", tool_call_id: "call_123" }
+  #   ]
+  class MessageExtractor
+    # 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 self.extract_messages(chat, current_agent)
+      new(chat, current_agent).extract
+    end
+
+    def initialize(chat, current_agent)
+      @chat = chat
+      @current_agent = current_agent
+    end
+
+    def extract
+      return [] unless @chat.respond_to?(:messages)
+
+      @chat.messages.filter_map do |msg|
+        case msg.role
+        when :user, :assistant
+          extract_user_or_assistant_message(msg)
+        when :tool
+          extract_tool_message(msg)
+        end
+      end
+    end
+
+    private
+
+    def extract_user_or_assistant_message(msg)
+      return nil unless msg.content && !msg.content.strip.empty?
+
+      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
+
+        # 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
+
+    def extract_tool_message(msg)
+      return nil unless msg.tool_result?
+
+      {
+        role: msg.role,
+        content: msg.content,
+        tool_call_id: msg.tool_call_id
+      }
+    end
+  end
+end

data/lib/agents/run_context.rb

@@ -56,14 +56,17 @@
 #   # - No race conditions or data leakage between runs
 module Agents
   class RunContext
-    attr_reader :context, :usage
+    attr_reader :context, :usage, :callbacks, :callback_manager
 
     # Initialize a new RunContext with execution context and usage tracking
     #
     # @param context [Hash] The execution context data (will be duplicated for isolation)
-    def initialize(context)
+    # @param callbacks [Hash] Optional callbacks for real-time event notifications
+    def initialize(context, callbacks: {})
       @context = context
       @usage = Usage.new
+      @callbacks = callbacks || {}
+      @callback_manager = CallbackManager.new(@callbacks)
     end
 
     # Usage tracks token consumption across all LLM calls within a single run.

data/lib/agents/runner.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "message_extractor"
+
 module Agents
   # The execution engine that orchestrates conversations between users and agents.
   # Runner manages the conversation flow, handles tool execution through RubyLLM,
@@ -77,14 +79,15 @@ module Agents
     # @param context [Hash] Shared context data accessible to all tools
     # @param registry [Hash] Registry of agents for handoff resolution
     # @param max_turns [Integer] Maximum conversation turns before stopping
+    # @param callbacks [Hash] Optional callbacks for real-time event notifications
     # @return [RunResult] The result containing output, messages, and usage
-    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS)
+    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS, callbacks: {})
       # The starting_agent is already determined by AgentRunner based on conversation history
       current_agent = starting_agent
 
       # Create context wrapper with deep copy for thread safety
       context_copy = deep_copy_context(context)
-      context_wrapper = RunContext.new(context_copy)
+      context_wrapper = RunContext.new(context_copy, callbacks: callbacks)
       current_turn = 0
 
       # Create chat and restore conversation history
@@ -97,8 +100,12 @@ module Agents
 
         # Get response from LLM (Extended Chat handles tool execution with handoff detection)
         result = if current_turn == 1
+                   # Emit agent thinking event for initial message
+                   context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, input)
                    chat.ask(input)
                  else
+                   # Emit agent thinking event for continuation
+                   context_wrapper.callback_manager.emit_agent_thinking(current_agent.name, "(continuing conversation)")
                    chat.complete
                  end
         response = result
@@ -119,6 +126,9 @@ module Agents
           # Save current conversation state before switching
           save_conversation_state(chat, context_wrapper, current_agent)
 
+          # Emit agent handoff event
+          context_wrapper.callback_manager.emit_agent_handoff(current_agent.name, next_agent.name, "handoff")
+
           # Switch to new agent - store agent name for persistence
           current_agent = next_agent
           context_wrapper.context[:current_agent] = next_agent.name
@@ -143,7 +153,7 @@ module Agents
 
         return RunResult.new(
           output: response.content,
-          messages: extract_messages(chat, current_agent),
+          messages: MessageExtractor.extract_messages(chat, current_agent),
           usage: context_wrapper.usage,
           context: context_wrapper.context
         )
@@ -154,7 +164,7 @@ module Agents
 
       RunResult.new(
         output: "Conversation ended: #{e.message}",
-        messages: chat ? extract_messages(chat, current_agent) : [],
+        messages: chat ? MessageExtractor.extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -165,7 +175,7 @@ module Agents
 
       RunResult.new(
         output: nil,
-        messages: chat ? extract_messages(chat, current_agent) : [],
+        messages: chat ? MessageExtractor.extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -208,7 +218,7 @@ module Agents
 
     def save_conversation_state(chat, context_wrapper, current_agent)
       # Extract messages from chat
-      messages = extract_messages(chat, current_agent)
+      messages = MessageExtractor.extract_messages(chat, current_agent)
 
       # Update context with latest state
       context_wrapper.context[:conversation_history] = messages
@@ -244,26 +254,5 @@ module Agents
       chat.with_tools(*wrapped_regular_tools) if wrapped_regular_tools.any?
       chat
     end
-
-    def extract_messages(chat, current_agent)
-      return [] unless chat.respond_to?(:messages)
-
-      chat.messages.filter_map do |msg|
-        # Only include user and assistant messages with content
-        next unless %i[user assistant].include?(msg.role)
-        next unless msg.content && !msg.content.strip.empty?
-
-        message = {
-          role: msg.role,
-          content: msg.content
-        }
-
-        # Add agent attribution for assistant messages to enable conversation continuity
-        # This allows AgentRunner to determine which agent should continue the conversation
-        message[:agent_name] = current_agent.name if msg.role == :assistant && current_agent
-
-        message
-      end
-    end
   end
 end

data/lib/agents/tool_wrapper.rb

@@ -46,7 +46,17 @@ module Agents
     # RubyLLM calls this method (follows RubyLLM::Tool pattern)
     def call(args)
       tool_context = ToolContext.new(run_context: @context_wrapper)
-      @tool.execute(tool_context, **args.transform_keys(&:to_sym))
+
+      @context_wrapper.callback_manager.emit_tool_start(@tool.name, args)
+
+      begin
+        result = @tool.execute(tool_context, **args.transform_keys(&:to_sym))
+        @context_wrapper.callback_manager.emit_tool_complete(@tool.name, result)
+        result
+      rescue StandardError => e
+        @context_wrapper.callback_manager.emit_tool_complete(@tool.name, "ERROR: #{e.message}")
+        raise
+      end
     end
 
     # Delegate metadata methods to the tool

data/lib/agents/version.rb

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

data/lib/agents.rb

@@ -80,6 +80,8 @@ require_relative "agents/agent"
 # Execution components
 require_relative "agents/chat"
 require_relative "agents/tool_wrapper"
+require_relative "agents/message_extractor"
+require_relative "agents/callback_manager"
 require_relative "agents/agent_runner"
 require_relative "agents/runner"
 require_relative "agents/agent_tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Shivam Mishra
@@ -31,8 +31,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/bump-version.md"
 - ".rspec"
 - ".rubocop.yml"
+- CHANGELOG.md
 - CLAUDE.md
 - LICENSE
 - README.md
@@ -47,6 +49,7 @@ files:
 - docs/concepts.md
 - docs/concepts/agent-tool.md
 - docs/concepts/agents.md
+- docs/concepts/callbacks.md
 - docs/concepts/context.md
 - docs/concepts/handoffs.md
 - docs/concepts/runner.md
@@ -94,8 +97,10 @@ files:
 - lib/agents/agent.rb
 - lib/agents/agent_runner.rb
 - lib/agents/agent_tool.rb
+- lib/agents/callback_manager.rb
 - lib/agents/chat.rb
 - lib/agents/handoff.rb
+- lib/agents/message_extractor.rb
 - lib/agents/result.rb
 - lib/agents/run_context.rb
 - lib/agents/runner.rb