ai-agents 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d23007ce65c6dae4c20025ad5cacb683652452a973472fa3c9fba1166606e57
-  data.tar.gz: 39b4522bd4ee7e329285a3806a4e06e5e312526e9139d4369bb7a12f4ede2d06
+  metadata.gz: cc088132bc2b8dafa23669d0e2e15d110f6a8cb982f54ba026247008a90322ca
+  data.tar.gz: 93086217d9aa75ebf072a299aeadacf688cede7216bd41d64dc539072ec1469b
 SHA512:
-  metadata.gz: bc45c4328b0ec188abb77249ee3da9de9515251f2c872b8468c1704d49ea3765cb1dae285cad84c6fd1b644d6adde35073ddf09a6071c82b8ae7671ebbc67d52
-  data.tar.gz: 354a10db6fab8d2885c1bdd6e20e72086a9cd87e1a16b99c1b744f0c35b962b19b07aafcf7c0ca0301f30bccc0a8e3ba00de13807178e7d02ec16466ba002a79
+  metadata.gz: 7ac77c92850152aa9bb716d3d1ecd37444e7cab76c9ab5e4e63aef20ad337a2416f9b4a1d55895ff0d0af97d4e8903c1e73f03c3e7a8f9bd6de0b8ed2f4279d6
+  data.tar.gz: 4b3055a233c48902fdb570ca8dce896d09cdbd30dc52a0a5f03fb290c7f60725804d574e5df3e3d4428c61ad1af58b97d0f173c5b576a324ae84598f4d48fbbc

data/.rubocop.yml

@@ -24,3 +24,6 @@ RSpec/SpecFilePathFormat:
 
 Metrics/MethodLength:
   Max: 20
+
+RSpec/MultipleDescribes:
+  Enabled: false

data/CLAUDE.md

@@ -2,187 +2,196 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Repository Overview
+## Project Purpose
 
-This is a Ruby AI Agents SDK that provides multi-agent orchestration capabilities, similar to OpenAI's Agents SDK but built for Ruby. The SDK enables the creation of sophisticated AI workflows with specialized agents, tool execution, and conversation handoffs.
+This project is a Ruby SDK for building multi-agent AI workflows. It allows developers to create specialized AI agents that can collaborate to solve complex tasks. The key features include:
 
-**IMPORTANT**: This is a generic agent library. When implementing library code, ensure that:
-- No domain-specific logic from examples (airline booking, FAQ, seat management, etc.) leaks into the core library
-- The library remains agnostic to specific use cases
-- All domain-specific implementations belong in the examples directory only
+-   **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.
+-   **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.
 
-## Development Commands
+## Key Technologies
 
-### Building and Testing
-```bash
-# Install dependencies
-bundle install
+-   **Ruby**: The primary programming language.
+-   **RubyLLM**: The underlying library for interacting with Large Language Models.
+-   **RSpec**: The testing framework.
+-   **RuboCop**: The code style linter.
+-   **GitHub Actions**: For continuous integration (testing and linting).
 
-# Run tests with RSpec
-rake spec
-# OR
-bundle exec rspec
+## Project Structure
 
-# Run specific spec file
-bundle exec rspec spec/agents/agent_spec.rb
+-   `lib/`: The core source code of the `ai-agents` gem.
+    -   `lib/agents.rb`: The main entry point, handling configuration and loading other components.
+    -   `lib/agents/agent.rb`: Defines the `Agent` class, which represents an individual AI agent.
+    -   `lib/agents/tool.rb`: Defines the `Tool` class, the base for creating custom tools for agents.
+    -   `lib/agents/agent_runner.rb`: Thread-safe agent execution manager for multi-agent conversations.
+    -   `lib/agents/runner.rb`: Internal orchestrator that handles individual conversation turns.
+-   `spec/`: Contains the RSpec tests for the project.
+-   `examples/`: Includes example implementations of multi-agent systems, such as an ISP customer support demo.
+-   `Gemfile`: Manages the project's Ruby dependencies.
+-   `.rubocop.yml`: Configures the code style rules for RuboCop.
+-   `.github/workflows/main.yml`: Defines the CI pipeline for running tests and linting on push and pull requests.
 
-# Run tests with coverage report
-bundle exec rspec  # SimpleCov will generate coverage/index.html
+## Development Workflow
 
-# Lint code (includes RSpec cops)
-rake rubocop
-# OR
-bundle exec rubocop
+1.  **Dependencies**: Managed by Bundler (`bundle install`).
+2.  **Testing**: Run tests with `bundle exec rspec`.
+3.  **Linting**: Check code style with `bundle exec rubocop`.
+4.  **CI/CD**: GitHub Actions automatically runs tests and linting for all pushes and pull requests to the `main` branch.
 
-# Auto-fix linting issues
-bundle exec rubocop -a
+## How to Run the Example
 
-# Run all checks (spec + lint)
-rake
-```
+The project includes an interactive example of an ISP customer support system. To run it:
 
-### Interactive Development
 ```bash
-# Start interactive console
-bin/console
-
-# Run the airline booking demo
-ruby examples/booking/interactive.rb
-
-# Run automatic booking demo
-ruby examples/booking/automatic.rb
+ruby examples/isp-support/interactive.rb
 ```
 
-## Architecture and Code Structure
+This will start a command-line interface where you can interact with the multi-agent system. The example demonstrates:
+- Thread-safe agent runner creation
+- Automatic agent selection based on conversation history
+- Context persistence that works across process boundaries
+- Seamless handoffs between triage, sales, and support agents
 
-### Core Components (Generic Library)
+## Key Concepts
 
-**lib/agents.rb** - Main module and configuration entry point. Configures both the Agents SDK and underlying RubyLLM library. Contains the `RECOMMENDED_HANDOFF_PROMPT_PREFIX` for multi-agent workflows.
+-   **Agent**: An AI assistant with a specific role, instructions, and tools.
+-   **Tool**: A custom function that an agent can use to perform actions (e.g., look up customer data, send an email).
+-   **Handoff**: The process of transferring a conversation from one agent to another. This is a core feature of the SDK.
+-   **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.
 
-**lib/agents/agent.rb** - The core `Agent` class with Ruby-like DSL for defining AI agents. Key features:
-- Class-level configuration: `name`, `instructions`, `provider`, `model`, `uses`, `handoffs`
-- Instance execution via `call` method with conversation history management
-- Tool and handoff tool registration at runtime
-- Context-aware execution with proper conversation history restoration using `chat.add_message`
-- **No domain-specific logic** - remains completely generic
+## Development Commands
 
-**lib/agents/tool.rb** - Base class for tools that agents can use. Inherits from `RubyLLM::Tool` and adds:
-- Ruby-style parameter definitions with automatic JSON schema conversion
-- Context injection through `perform` method (called by `execute`)
-- Enhanced parameter definition supporting Ruby types (String, Integer, etc.)
-- **Domain-agnostic** - specific tool implementations belong in user code
+### Testing
+```bash
+# Run all tests with RSpec
+bundle exec rspec
 
-**lib/agents/handoff.rb** - Contains the handoff system classes:
-- `HandoffResult` - Represents a handoff decision
-- `AgentResponse` - Wraps agent responses with optional handoff results
-- `HandoffTool` - Generic tool for transferring between agents using context-based signaling
-- **Generic handoff mechanism** - no assumptions about specific agent types
+# Run tests with coverage report (uses SimpleCov)
+bundle exec rake spec
 
-**lib/agents/context.rb** - Base context class for sharing state between agents and tools across handoffs. Must be subclassed for domain-specific context. The base class provides only generic state management capabilities.
+# Run specific test file
+bundle exec rspec spec/agents/agent_spec.rb
 
-**lib/agents/runner.rb** - Execution engine for orchestrating multi-agent workflows (future implementation).
+# Run specific test with line number
+bundle exec rspec spec/agents/agent_spec.rb:25
+```
 
-### Key Design Patterns
+### Code Quality
+```bash
+# Run RuboCop linter
+bundle exec rubocop
 
-#### Agent Definition Pattern (Generic)
-```ruby
-class MyAgent < Agents::Agent
-  name "Agent Name"
-  instructions "Behavior description" # Can be dynamic via Proc
-  provider :openai  # Optional, defaults to configured provider
-  model "gpt-4o"    # Optional, defaults to configured model
-
-  uses SomeTool     # Register tools by class
-  handoffs OtherAgent, AnotherAgent  # Define possible handoff targets
-end
+# Run RuboCop with auto-correction
+bundle exec rubocop -a
+
+# Run both tests and linting (default rake task)
+bundle exec rake
 ```
 
-#### Tool Definition Pattern (Generic)
-```ruby
-class MyTool < Agents::Tool
-  description "What this tool does"
-  param :input_param, String, "Parameter description"
-  param :optional_param, Integer, "Optional param", required: false
-
-  def perform(input_param:, optional_param: nil, context:)
-    # context is always available for state management
-    # Must implement perform, not execute
-    # Tool logic should be domain-specific in user implementations
-    "Tool result"
-  end
-end
+### Development
+```bash
+# Install dependencies
+bundle install
+
+# Interactive Ruby console with gem loaded
+bundle exec irb -r ./lib/agents
+
+# Run ISP support example interactively
+ruby examples/isp-support/interactive.rb
 ```
 
-#### Context-Based Handoff System
-The handoff system uses context signaling rather than text parsing:
-1. `HandoffTool` instances are created automatically from `handoffs` declarations
-2. When called, `HandoffTool.perform` sets `context[:pending_handoff]`
-3. `Agent.detect_handoff_from_context` checks for pending handoffs after LLM responses
-4. Interactive systems handle handoffs by switching to the target agent class
+## Architecture
 
-#### Conversation History Management
-Critical for multi-turn conversations:
-- Agents maintain `@conversation_history` as array of `{user:, assistant:, timestamp:}` hashes
-- `restore_conversation_history(chat)` uses `chat.add_message(role:, content:)` to restore RubyLLM chat state
-- This prevents agents from "forgetting" previous conversation turns
+### Core Components
 
-### Configuration Rules
+- **Agents::Agent**: Individual AI agents with specific roles, instructions, and tools
+- **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
 
-#### Class Naming
-- Use flat naming like `class Agents::Tool` instead of nested declarations
-- Follow Ruby naming conventions for agent and tool classes
+### Key Design Principles
 
-#### Documentation
-- Always write doc strings when writing functions
-- Use YARD format for documentation
-- Always write RDoc for new methods
-- When creating a new file, start the file with a description comment on what the file has and where does it fit in the project
+1. **Thread Safety**: All components are designed to be thread-safe. Tools receive context as parameters, not instance variables.
 
-#### Model Defaults
-- Default model for OpenAI provider is `gpt-4.1-mini` (configured in lib/agents.rb)
-- Can be overridden in agent classes or runtime configuration
+2. **Immutable Agents**: Agents are configured once and can be cloned with modifications. No execution state is stored in agent instances.
 
-### Examples Structure
+3. **Provider Agnostic**: Built on RubyLLM, supports OpenAI, Anthropic, and Gemini through configuration.
 
-**examples/booking/** - Complete airline booking demo showcasing multi-agent workflows. This is just one example of how the SDK can be used. The example demonstrates:
-- Multi-agent workflow patterns
-- Context sharing between agents
-- Tool usage patterns
-- Interactive CLI and automatic execution modes
-- Proper handoff handling
 
-Note: The airline booking scenario is purely demonstrative. The SDK is not limited to or designed specifically for airline systems.
+### File Structure
 
-### Dependencies and Integration
+```
+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
+```
 
-**RubyLLM Integration** - Built on top of RubyLLM library for LLM communication:
-- Agents SDK configures RubyLLM automatically via `Agents.configure`
-- Tools inherit from `RubyLLM::Tool` but use enhanced `perform` method
-- Conversation history restored using `chat.add_message`
-- Debug mode available via `ENV["RUBYLLM_DEBUG"] = "true"`
+### Configuration
 
-**Provider Support** - Currently supports OpenAI through RubyLLM, extensible to other providers
+The SDK requires at least one LLM provider API key:
 
-### Important Implementation Details
+```ruby
+Agents.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  config.gemini_api_key = ENV['GEMINI_API_KEY']
+  config.default_model = 'gpt-4o-mini'
+  config.debug = true
+end
+```
 
-1. **Conversation History**: Must call `restore_conversation_history(chat)` before each agent execution to maintain conversation state across turns.
+### Basic Usage Pattern
 
-2. **Tool Context Flow**: `RubyLLM.execute()` → `Agents::Tool.execute()` → `Tool.perform(context:, **args)` - the context injection happens in the base `Tool.execute` method.
+```ruby
+# Create agents with handoff relationships
+triage = Agent.new(name: "Triage", instructions: "Route users...")
+billing = Agent.new(name: "Billing", instructions: "Handle billing...")
+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)
+
+# Use for conversations - automatically handles agent selection and persistence
+result = runner.run("I have a billing question")
+result = runner.run("What about technical support?", context: result.context)
+```
 
-3. **Handoff Detection**: Uses context-based detection (`@context[:pending_handoff]`) rather than parsing LLM responses for tool calls.
+### Tool Development
 
-4. **Model Configuration**: Default model is `gpt-4.1-mini` but examples use `gpt-4o` for better performance.
+When creating custom tools:
+- Extend `Agents::Tool`
+- Use `tool_context` parameter for all state
+- Never store execution state in instance variables
+- Follow the thread-safe design pattern shown in examples
 
-5. **Thread Safety**: Agents are designed to be stateless with context passed through execution rather than stored in instance variables.
+### Testing Strategy
 
-6. **Library vs Example Code**: The core library (lib/agents/*) must remain completely generic and free of domain-specific logic. All domain-specific implementations (airline booking, FAQ systems, etc.) belong exclusively in the examples directory.
+- 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/`
 
-### Testing Guidelines
+### Examples
 
-When writing tests, follow the rules: 
-1. Avoid stubbing using allow_any_instance_of`
-2. Each example block `it ... end` should have less than 20 lines
-3. Example group should not have more than 10 memoized helpers, not more than 10 except statements
-4. Never use `receive_message_chain`
-5. When writing tests, always use verifying doubles and never normal doubles
-```
+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

data/README.md

@@ -40,15 +40,18 @@ Agents.configure do |config|
   config.openai_api_key = ENV['OPENAI_API_KEY']
 end
 
-# Create a simple agent
-agent = Agents::Agent.new(
+# Create agents
+weather_agent = Agents::Agent.new(
   name: "Weather Assistant",
   instructions: "Help users get weather information",
   tools: [WeatherTool.new]
 )
 
-# Use the agent with the Runner
-result = Agents::Runner.run(agent, "What's the weather like today?")
+# Create a thread-safe runner (reusable across conversations)
+runner = Agents::Runner.with_agents(weather_agent)
+
+# Use the runner for conversations
+result = runner.run("What's the weather like today?")
 puts result.output
 ```
 
@@ -64,14 +67,14 @@ triage = Agents::Agent.new(
 )
 
 faq = Agents::Agent.new(
-  name: "FAQ Agent",
+  name: "FAQ Agent", 
   instructions: "Answer frequently asked questions",
   tools: [FaqLookupTool.new]
 )
 
 support = Agents::Agent.new(
   name: "Support Agent",
-  instructions: "Handle technical issues",
+  instructions: "Handle technical issues", 
   tools: [TicketTool.new]
 )
 
@@ -80,9 +83,16 @@ triage.register_handoffs(faq, support)
 faq.register_handoffs(triage)     # Can route back to triage
 support.register_handoffs(triage)  # Hub-and-spoke pattern
 
-# Run a conversation with automatic handoffs
-result = Agents::Runner.run(triage, "How many seats are on the plane?")
+# Create runner with all agents (triage is default entry point)
+runner = Agents::Runner.with_agents(triage, faq, support)
+
+# Run conversations with automatic handoffs and persistence
+result = runner.run("How many seats are on the plane?")
 # User gets direct answer from FAQ agent without knowing about the handoff!
+
+# Continue the conversation seamlessly
+result = runner.run("What about technical support?", context: result.context)
+# Context automatically tracks conversation history and current agent
 ```
 
 ## 🏗️ Architecture
@@ -90,8 +100,9 @@ result = Agents::Runner.run(triage, "How many seats are on the plane?")
 ### Core Components
 
 - **Agent**: Individual AI agents with specific roles and capabilities
-- **Runner**: Orchestrates multi-agent conversations with automatic handoffs
-- **Context**: Shared state management across agents
+- **AgentRunner**: Thread-safe execution manager for multi-agent conversations
+- **Runner**: Internal orchestrator that handles conversation turns (used by AgentRunner)
+- **Context**: Shared state management with automatic persistence across agents
 - **Tools**: Custom functions that agents can use
 - **Handoffs**: Seamless transfers between specialized agents
 
@@ -134,11 +145,11 @@ end
 ```ruby
 class EmailTool < Agents::Tool
   description "Send emails to customers"
-  param :to, String, "Email address"
-  param :subject, String, "Email subject"
-  param :body, String, "Email body"
+  param :to, type: "string", desc: "Email address"
+  param :subject, type: "string", desc: "Email subject"
+  param :body, type: "string", desc: "Email body"
 
-  def perform(to:, subject:, body:, context:)
+  def perform(tool_context, to:, subject:, body:)
     # Send email logic here
     "Email sent to #{to}"
   end
@@ -175,16 +186,27 @@ sales.register_handoffs(customer_info)
 customer_info.register_handoffs(sales)
 ```
 
-### Context Management
+### Context Management & Persistence
 
 ```ruby
-# Context is automatically managed by the Runner
-context = {}
-result = Agents::Runner.run(agent, "Hello", context: context)
+# Context is automatically managed and serializable
+runner = Agents::Runner.with_agents(triage, billing, support)
 
-# Access conversation history and agent state
+# Start a conversation
+result = runner.run("I need billing help")
+
+# Context is automatically updated with conversation history and current agent
+context = result.context
 puts context[:conversation_history]
-puts context[:current_agent].name
+puts context[:current_agent]  # Agent name (string), not object!
+
+# Serialize context for persistence (Rails, databases, etc.)
+json_context = JSON.dump(context)  # ✅ Works! No object references
+
+# Later: restore and continue conversation
+restored_context = JSON.parse(json_context, symbolize_names: true)
+result = runner.run("Actually, I need technical support too", context: restored_context)
+# System automatically determines correct agent from conversation history
 ```
 
 ## 📋 Examples

data/examples/isp-support/agents_factory.rb

@@ -48,7 +48,6 @@ module ISPSupport
       )
     end
 
-
     def create_sales_agent
       Agents::Agent.new(
         name: "Sales Agent",
@@ -65,7 +64,7 @@ module ISPSupport
         model: "gpt-4.1-mini",
         tools: [
           ISPSupport::CrmLookupTool.new,
-          ISPSupport::SearchDocsTool.new, 
+          ISPSupport::SearchDocsTool.new,
           ISPSupport::EscalateToHumanTool.new
         ]
       )
@@ -89,7 +88,6 @@ module ISPSupport
       INSTRUCTIONS
     end
 
-
     def sales_instructions
       <<~INSTRUCTIONS
         You are the Sales Agent for an ISP. You handle new customer acquisition, service upgrades,
@@ -101,16 +99,17 @@ module ISPSupport
         - Handoff tools: Route back to triage when needed
 
         **When to hand off:**
-        - Need account verification or billing info → Triage Agent for re-routing
-        - Technical questions → Triage Agent for re-routing
-        - Non-sales requests → Triage Agent
+        - Pure technical support questions → Triage Agent for re-routing
+        - Customer needs to speak with human agent → Triage Agent for re-routing
 
         **Instructions:**
         - Be enthusiastic but not pushy
         - Gather required info: name, email, desired plan for leads
-        - For existing customers wanting upgrades, ask them to verify account first
+        - For account verification, ask customer for their account details directly
+        - For existing customers wanting upgrades, collect account info and proceed
         - Create checkout links for confirmed purchases
         - Always explain next steps after creating leads or checkout links
+        - Handle billing questions yourself - don't hand off for account verification
       INSTRUCTIONS
     end
 
@@ -126,8 +125,8 @@ module ISPSupport
         - Handoff tools: Route back to triage when needed
 
         **When to hand off:**
-        - Customer wants to buy/upgrade plans → Triage Agent to route to Sales
-        - Non-support requests (new purchases) → Triage Agent
+        - Customer wants to buy new service or upgrade plans → Triage Agent to route to Sales
+        - Complex issues requiring human intervention → Use escalate_to_human tool instead
 
         **Instructions:**
         - For account questions: Always ask for account ID and use crm_lookup
@@ -136,6 +135,7 @@ module ISPSupport
         - Be patient and provide step-by-step guidance
         - If customer gets frustrated or issue persists, escalate to human
         - Present account information clearly and protect sensitive data
+        - Handle account verification requests directly - don't hand off back to triage
       INSTRUCTIONS
     end
   end

data/examples/isp-support/interactive.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "json"
 require_relative "../../lib/agents"
 require_relative "agents_factory"
 
@@ -13,8 +14,15 @@ class ISPSupportDemo
     end
 
     # Create agents
-    @agents = ISPSupport::AgentsFactory.create_agents
-    @triage_agent = @agents[:triage]
+    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]
+    )
+
     @context = {}
 
     puts "🏢 Welcome to ISP Customer Support!"
@@ -31,10 +39,8 @@ class ISPSupportDemo
       break if command_result == :exit
       next if command_result == :handled || user_input.empty?
 
-      # Determine which agent to use - either from context or triage agent
-      current_agent = @context[:current_agent] || @triage_agent
-
-      result = Agents::Runner.run(current_agent, user_input, context: @context)
+      # 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
@@ -50,6 +56,7 @@ class ISPSupportDemo
   def handle_command(input)
     case input.downcase
     when "exit", "quit"
+      dump_context_and_quit
       puts "👋 Goodbye!"
       :exit
     when "/help"
@@ -73,6 +80,21 @@ class ISPSupportDemo
     end
   end
 
+  def dump_context_and_quit
+    project_root = File.expand_path("../..", __dir__)
+    tmp_directory = File.join(project_root, "tmp")
+
+    # Ensure tmp directory exists
+    Dir.mkdir(tmp_directory) unless Dir.exist?(tmp_directory)
+
+    timestamp = Time.now.to_i
+    context_filename = File.join(tmp_directory, "context-#{timestamp}.json")
+
+    File.write(context_filename, JSON.pretty_generate(@context))
+
+    puts "💾 Context saved to tmp/context-#{timestamp}.json"
+  end
+
   def show_help
     puts "📋 Available Commands:"
     puts "  /help     - Show this help message"

data/examples/isp-support/tools/create_checkout_tool.rb

@@ -6,7 +6,7 @@ module ISPSupport
   # Tool for creating checkout links for new service subscriptions.
   class CreateCheckoutTool < Agents::Tool
     description "Create a secure checkout link for a service plan"
-    param :plan_name, String, "Name of the plan to purchase"
+    param :plan_name, type: "string", desc: "Name of the plan to purchase"
 
     def perform(_tool_context, plan_name:)
       session_id = SecureRandom.hex(8)

data/examples/isp-support/tools/create_lead_tool.rb

@@ -4,9 +4,9 @@ module ISPSupport
   # Tool for creating sales leads in the CRM system.
   class CreateLeadTool < Agents::Tool
     description "Create a new sales lead with customer information"
-    param :name, String, "Customer's full name"
-    param :email, String, "Customer's email address"
-    param :desired_plan, String, "Plan the customer is interested in"
+    param :name, type: "string", desc: "Customer's full name"
+    param :email, type: "string", desc: "Customer's email address"
+    param :desired_plan, type: "string", desc: "Plan the customer is interested in"
 
     def perform(_tool_context, name:, email:, desired_plan:)
       "Lead created for #{name} (#{email}) interested in #{desired_plan} plan. Sales team will contact within 24 hours."

data/examples/isp-support/tools/crm_lookup_tool.rb

@@ -6,7 +6,7 @@ module ISPSupport
   # Tool for looking up customer information from the CRM system.
   class CrmLookupTool < Agents::Tool
     description "Look up customer account information by account ID"
-    param :account_id, String, "Customer account ID (e.g., CUST001)"
+    param :account_id, type: "string", desc: "Customer account ID (e.g., CUST001)"
 
     def perform(_tool_context, account_id:)
       data_file = File.join(__dir__, "../data/customers.json")

data/examples/isp-support/tools/search_docs_tool.rb

@@ -4,7 +4,7 @@ module ISPSupport
   # Tool for searching the knowledge base documentation.
   class SearchDocsTool < Agents::Tool
     description "Search knowledge base for troubleshooting steps and solutions"
-    param :query, String, "Search terms or description of the issue"
+    param :query, type: "string", desc: "Search terms or description of the issue"
 
     def perform(_tool_context, query:)
       case query.downcase

data/lib/agents/agent_runner.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Agents
+  # Thread-safe agent execution manager that provides a clean API for multi-agent conversations.
+  # This class is designed to be created once and reused across multiple threads safely.
+  #
+  # The key insight here is separating agent registry/configuration (this class) from
+  # execution state (Runner instances). This allows the same AgentRunner to be used
+  # concurrently without thread safety issues.
+  #
+  # ## Usage Pattern
+  #   # Create once (typically at application startup)
+  #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+  #
+  #   # Use safely from multiple threads
+  #   result = runner.run("I need billing help")           # New conversation
+  #   result = runner.run("More help", context: context)   # Continue conversation
+  #
+  # ## Thread Safety Design
+  # - All instance variables are frozen after initialization (immutable state)
+  # - Agent registry is built once and never modified
+  # - Each run() call creates independent execution context
+  # - No shared mutable state between concurrent executions
+  #
+  class AgentRunner
+    # Initialize with a list of agents. The first agent becomes the default entry point.
+    #
+    # @param agents [Array<Agents::Agent>] List of agents, first one is the default entry point
+    def initialize(agents)
+      raise ArgumentError, "At least one agent must be provided" if agents.empty?
+
+      @agents = agents.dup.freeze
+      @default_agent = agents.first
+
+      # Build simple registry from provided agents - developer controls what's available
+      @registry = build_registry(agents).freeze
+    end
+
+    # Execute a conversation turn with automatic agent selection.
+    # For new conversations, uses the default agent (first in the list).
+    # For continuing conversations, determines the appropriate agent from conversation history.
+    #
+    # @param input [String] User's message
+    # @param context [Hash] Conversation context (will be restored if continuing conversation)
+    # @param max_turns [Integer] Maximum turns before stopping (default: 10)
+    # @return [RunResult] Execution result with output, messages, and updated context
+    def run(input, context: {}, max_turns: Runner::DEFAULT_MAX_TURNS)
+      # Determine which agent should handle this conversation
+      # Uses conversation history to maintain continuity across handoffs
+      current_agent = determine_conversation_agent(context)
+
+      # Execute using stateless Runner - each execution is independent and thread-safe
+      Runner.new.run(
+        current_agent,
+        input,
+        context: context,
+        registry: @registry,
+        max_turns: max_turns
+      )
+    end
+
+    private
+
+    # Build agent registry from provided agents only.
+    # Developer explicitly controls which agents are available for handoffs.
+    #
+    # @param agents [Array<Agents::Agent>] Agents to register
+    # @return [Hash<String, Agents::Agent>] Registry mapping agent names to agent instances
+    def build_registry(agents)
+      registry = {}
+      agents.each { |agent| registry[agent.name] = agent }
+      registry
+    end
+
+    # Determine which agent should handle the current conversation.
+    # For new conversations (empty context), uses the default agent.
+    # For continuing conversations, analyzes history to find the last agent that spoke.
+    #
+    # This implements Google ADK-style session continuation logic where the system
+    # automatically maintains conversation continuity without requiring manual agent tracking.
+    #
+    # @param context [Hash] Conversation context with potential history
+    # @return [Agents::Agent] Agent that should handle this conversation turn
+    def determine_conversation_agent(context)
+      history = context[:conversation_history] || []
+
+      # For new conversations, use the default (first) agent
+      return @default_agent if history.empty?
+
+      # Find the last assistant message with agent attribution
+      # We traverse in reverse to find the most recent agent that spoke
+      last_agent_name = history.reverse.find do |msg|
+        msg[:role] == :assistant && msg[:agent_name]
+      end&.dig(:agent_name)
+
+      # Try to resolve from registry, fall back to default if agent not found
+      # This handles cases where agent names in history don't match current registry
+      if last_agent_name && @registry[last_agent_name]
+        @registry[last_agent_name]
+      else
+        @default_agent
+      end
+    end
+  end
+end

data/lib/agents/chat.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "tool_context"
+
+module Agents
+  # Extended chat class that inherits from RubyLLM::Chat but adds proper handoff handling.
+  # This solves the infinite handoff loop problem by treating handoffs as turn-ending
+  # operations rather than allowing auto-continuation.
+  class Chat < RubyLLM::Chat
+    # Response object that indicates a handoff occurred
+    class HandoffResponse
+      attr_reader :target_agent, :response, :handoff_message
+
+      def initialize(target_agent:, response:, handoff_message:)
+        @target_agent = target_agent
+        @response = response
+        @handoff_message = handoff_message
+      end
+
+      def tool_call?
+        true
+      end
+
+      def content
+        @handoff_message
+      end
+    end
+
+    def initialize(model: nil, handoff_tools: [], context_wrapper: nil, **options)
+      super(model: model, **options)
+      @handoff_tools = handoff_tools
+      @context_wrapper = context_wrapper
+
+      # Register handoff tools with RubyLLM for schema generation
+      @handoff_tools.each { |tool| with_tool(tool) }
+    end
+
+    # Override the problematic auto-execution method from RubyLLM::Chat
+    def complete(&block)
+      @on[:new_message]&.call
+      response = @provider.complete(
+        messages,
+        tools: @tools,
+        temperature: @temperature,
+        model: @model.id,
+        connection: @connection,
+        &block
+      )
+      @on[:end_message]&.call(response)
+
+      add_message(response)
+
+      if response.tool_call?
+        handle_tools_with_handoff_detection(response, &block)
+      else
+        response
+      end
+    end
+
+    private
+
+    def handle_tools_with_handoff_detection(response, &block)
+      handoff_calls, regular_calls = classify_tool_calls(response.tool_calls)
+
+      if handoff_calls.any?
+        # Execute first handoff only
+        handoff_result = execute_handoff_tool(handoff_calls.first)
+
+        # Add tool result to conversation
+        add_tool_result(handoff_calls.first.id, handoff_result[:message])
+
+        # Return handoff response to signal agent switch (ends turn)
+        HandoffResponse.new(
+          target_agent: handoff_result[:target_agent],
+          response: response,
+          handoff_message: handoff_result[:message]
+        )
+      else
+        # Use RubyLLM's original tool execution for regular tools
+        execute_regular_tools_and_continue(regular_calls, &block)
+      end
+    end
+
+    def classify_tool_calls(tool_calls)
+      handoff_tool_names = @handoff_tools.map(&:name).map(&:to_s)
+
+      handoff_calls = []
+      regular_calls = []
+
+      tool_calls.each_value do |tool_call|
+        if handoff_tool_names.include?(tool_call.name)
+          handoff_calls << tool_call
+        else
+          regular_calls << tool_call
+        end
+      end
+
+      [handoff_calls, regular_calls]
+    end
+
+    def execute_handoff_tool(tool_call)
+      tool = @handoff_tools.find { |t| t.name.to_s == tool_call.name }
+      raise "Handoff tool not found: #{tool_call.name}" unless tool
+
+      # Execute the handoff tool directly with context
+      tool_context = ToolContext.new(run_context: @context_wrapper)
+      result = tool.execute(tool_context, **{}) # Handoff tools take no additional params
+
+      {
+        target_agent: tool.target_agent,
+        message: result.to_s
+      }
+    end
+
+    def execute_regular_tools_and_continue(tool_calls, &block)
+      # Execute each regular tool call
+      tool_calls.each do |tool_call|
+        @on[:new_message]&.call
+        result = execute_tool(tool_call)
+        message = add_tool_result(tool_call.id, result)
+        @on[:end_message]&.call(message)
+      end
+
+      # Continue conversation after tool execution
+      complete(&block)
+    end
+
+    # Reuse RubyLLM's existing tool execution logic
+    def execute_tool(tool_call)
+      tool = tools[tool_call.name.to_sym]
+      args = tool_call.arguments
+      tool.call(args)
+    end
+
+    def add_tool_result(tool_use_id, result)
+      add_message(
+        role: :tool,
+        content: result.is_a?(Hash) && result[:error] ? result[:error] : result.to_s,
+        tool_call_id: tool_use_id
+      )
+    end
+  end
+end

data/lib/agents/handoff.rb

@@ -95,18 +95,10 @@ module Agents
       @tool_description
     end
 
-    # Handoff tools implement first-call-wins semantics to prevent infinite loops
-    # Multiple handoff calls in a single response are ignored (like OpenAI SDK)
-    def perform(tool_context)
-      # First-call-wins: only set handoff if not already set
-      if tool_context.context[:pending_handoff]
-        return "Transfer request noted (already processing a handoff)."
-      end
-
-      # Set the handoff target
-      tool_context.context[:pending_handoff] = @target_agent
-
-      # Return a message that will be shown to the user
+    # Handoff tools now work with the extended Chat class for proper handoff handling
+    # No longer need context signaling - the Chat class detects handoffs directly
+    def perform(_tool_context)
+      # Simply return the transfer message - Chat class will handle the handoff
       "I'll transfer you to #{@target_agent.name} who can better assist you with this."
     end
 

data/lib/agents/runner.rb

@@ -54,21 +54,33 @@ module Agents
 
     class MaxTurnsExceeded < StandardError; end
 
-    # Convenience class method for running agents
-    def self.run(agent, input, context: {}, max_turns: DEFAULT_MAX_TURNS)
-      new.run(agent, input, context: context, max_turns: max_turns)
+    # Create a thread-safe agent runner for multi-agent conversations.
+    # The first agent becomes the default entry point for new conversations.
+    # All agents must be explicitly provided - no automatic discovery.
+    #
+    # @param agents [Array<Agents::Agent>] All agents that should be available for handoffs
+    # @return [AgentRunner] Thread-safe runner that can be reused across multiple conversations
+    #
+    # @example
+    #   runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
+    #   result = runner.run("I need help")  # Uses triage_agent for new conversation
+    #   result = runner.run("More help", context: stored_context)  # Continues with appropriate agent
+    def self.with_agents(*agents)
+      AgentRunner.new(agents)
     end
 
-    # Execute an agent with the given input and context
+    # Execute an agent with the given input and context.
+    # This is now called internally by AgentRunner and should not be used directly.
     #
-    # @param starting_agent [Agents::Agent] The initial agent to run
+    # @param starting_agent [Agents::Agent] The agent to run
     # @param input [String] The user's input message
     # @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
     # @return [RunResult] The result containing output, messages, and usage
-    def run(starting_agent, input, context: {}, max_turns: DEFAULT_MAX_TURNS)
-      # Determine current agent from context or use starting agent
-      current_agent = context[:current_agent] || starting_agent
+    def run(starting_agent, input, context: {}, registry: {}, max_turns: DEFAULT_MAX_TURNS)
+      # 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)
@@ -83,44 +95,55 @@ module Agents
         current_turn += 1
         raise MaxTurnsExceeded, "Exceeded maximum turns: #{max_turns}" if current_turn > max_turns
 
-        # Get response from LLM (RubyLLM handles tool execution)
-        response = if current_turn == 1
-                     chat.ask(input)
-                   else
-                     chat.complete
-                   end
+        # Get response from LLM (Extended Chat handles tool execution with handoff detection)
+        result = if current_turn == 1
+                   chat.ask(input)
+                 else
+                   chat.complete
+                 end
+        response = result
 
-        # Update usage
-        context_wrapper.usage.add(response.usage) if response.respond_to?(:usage) && response.usage
+        # Check for handoff response from our extended chat
+        if response.is_a?(Agents::Chat::HandoffResponse)
+          next_agent = response.target_agent
 
-        # Check for handoff via context (set by HandoffTool)
-        if context_wrapper.context[:pending_handoff]
-          next_agent = context_wrapper.context[:pending_handoff]
-          puts "[Agents] Handoff from #{current_agent.name} to #{next_agent.name}"
+          # Validate that the target agent is in our registry
+          # This prevents handoffs to agents that weren't explicitly provided
+          unless registry[next_agent.name]
+            puts "[Agents] Warning: Handoff to unregistered agent '#{next_agent.name}', continuing with current agent"
+            next if response.tool_call?
+
+            next
+          end
 
           # Save current conversation state before switching
           save_conversation_state(chat, context_wrapper, current_agent)
 
-          # Switch to new agent
+          # Switch to new agent - store agent name for persistence
           current_agent = next_agent
-          context_wrapper.context[:current_agent] = next_agent
-          context_wrapper.context.delete(:pending_handoff)
+          context_wrapper.context[:current_agent] = next_agent.name
 
           # Create new chat for new agent with restored history
           chat = create_chat(current_agent, context_wrapper)
           restore_conversation_history(chat, context_wrapper)
+
+          # Force the new agent to respond to the conversation context
+          # This ensures the user gets a response from the new agent
+          input = nil
           next
         end
 
-        # If no tools were called, we have our final response
+        # If tools were called, continue the loop to let them execute
         next if response.tool_call?
 
+        # If no tools were called, we have our final response
+
         # Save final state before returning
         save_conversation_state(chat, context_wrapper, current_agent)
 
         return RunResult.new(
           output: response.content,
-          messages: extract_messages(chat),
+          messages: extract_messages(chat, current_agent),
           usage: context_wrapper.usage,
           context: context_wrapper.context
         )
@@ -131,7 +154,7 @@ module Agents
 
       RunResult.new(
         output: "Conversation ended: #{e.message}",
-        messages: chat ? extract_messages(chat) : [],
+        messages: chat ? extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -142,7 +165,7 @@ module Agents
 
       RunResult.new(
         output: nil,
-        messages: chat ? extract_messages(chat) : [],
+        messages: chat ? extract_messages(chat, current_agent) : [],
         usage: context_wrapper.usage,
         error: e,
         context: context_wrapper.context
@@ -185,11 +208,11 @@ module Agents
 
     def save_conversation_state(chat, context_wrapper, current_agent)
       # Extract messages from chat
-      messages = extract_messages(chat)
+      messages = extract_messages(chat, current_agent)
 
       # Update context with latest state
       context_wrapper.context[:conversation_history] = messages
-      context_wrapper.context[:current_agent] = current_agent
+      context_wrapper.context[:current_agent] = current_agent.name
       context_wrapper.context[:turn_count] = (context_wrapper.context[:turn_count] || 0) + 1
       context_wrapper.context[:last_updated] = Time.now
 
@@ -203,19 +226,26 @@ module Agents
       # Get system prompt (may be dynamic)
       system_prompt = agent.get_system_prompt(context_wrapper)
 
-      # Wrap tools with context for thread-safe execution
-      wrapped_tools = agent.all_tools.map do |tool|
-        ToolWrapper.new(tool, context_wrapper)
-      end
+      # Separate handoff tools from regular tools
+      handoff_tools = agent.handoff_agents.map { |target_agent| HandoffTool.new(target_agent) }
+      regular_tools = agent.tools
+
+      # Only wrap regular tools - handoff tools will be handled directly by Chat
+      wrapped_regular_tools = regular_tools.map { |tool| ToolWrapper.new(tool, context_wrapper) }
+
+      # Create extended chat with handoff awareness and context
+      chat = Agents::Chat.new(
+        model: agent.model,
+        handoff_tools: handoff_tools,        # Direct tools, no wrapper
+        context_wrapper: context_wrapper     # Pass context directly
+      )
 
-      # Create chat with proper RubyLLM API
-      chat = RubyLLM.chat(model: agent.model)
       chat.with_instructions(system_prompt) if system_prompt
-      chat.with_tools(*wrapped_tools) if wrapped_tools.any?
+      chat.with_tools(*wrapped_regular_tools) if wrapped_regular_tools.any?
       chat
     end
 
-    def extract_messages(chat)
+    def extract_messages(chat, current_agent)
       return [] unless chat.respond_to?(:messages)
 
       chat.messages.filter_map do |msg|
@@ -223,10 +253,16 @@ module Agents
         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

data/lib/agents/tool.rb

@@ -36,52 +36,8 @@
 #     end
 #   end
 #
-# @example Using the functional tool definition
-#   # Define a calculator tool
-#   calculator = Agents::Tool.tool(
-#     "calculate",
-#     description: "Perform mathematical calculations"
-#   ) do |tool_context, expression:|
-#     begin
-#       result = eval(expression)
-#       result.to_s
-#     rescue => e
-#       "Calculation error: #{e.message}"
-#     end
-#   end
-#
-#   # Use the tool in an agent
-#   agent = Agents::Agent.new(
-#     name: "Math Assistant",
-#     instructions: "You are a helpful math assistant",
-#     tools: [calculator]
-#   )
-#
-#   # During execution, the runner would call it like this:
-#   run_context = Agents::RunContext.new({ user_id: 123 })
-#   tool_context = Agents::ToolContext.new(run_context: run_context)
-#
-#   result = calculator.execute(tool_context, expression: "2 + 2 * 3")
-#   # => "8"
 module Agents
   class Tool < RubyLLM::Tool
-    class << self
-      def param(name, type = String, desc = nil, required: true, **options)
-        # Convert Ruby types to JSON schema types
-        json_type = case type
-                    when String, "string" then "string"
-                    when Integer, "integer" then "integer"
-                    when Float, "number" then "number"
-                    when TrueClass, FalseClass, "boolean" then "boolean"
-                    when Array, "array" then "array"
-                    when Hash, "object" then "object"
-                    else "string"
-                    end
-
-        # Call parent param method
-        super(name, type: json_type, desc: desc, required: required, **options)
-      end
-    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.
@@ -112,42 +68,5 @@ module Agents
     def perform(tool_context, **params)
       raise NotImplementedError, "Tools must implement #perform(tool_context, **params)"
     end
-
-    # Create a tool instance using a functional style definition.
-    # This is an alternative to creating a full class for simple tools.
-    # The block becomes the tool's perform method.
-    #
-    # @param name [String] The tool's name (used in function calling)
-    # @param description [String] Brief description of what the tool does
-    # @yield [tool_context, **params] The block that implements the tool's logic
-    # @return [Agents::Tool] A new tool instance
-    # @example Creating a simple tool functionally
-    #   math_tool = Agents::Tool.tool(
-    #     "add_numbers",
-    #     description: "Add two numbers together"
-    #   ) do |tool_context, a:, b:|
-    #     (a + b).to_s
-    #   end
-    #
-    # @example Tool accessing context with error handling
-    #   greeting_tool = Agents::Tool.tool("greet", description: "Greet a user") do |tool_context, name:|
-    #     language = tool_context.context[:language] || "en"
-    #     case language
-    #     when "es" then "¡Hola, #{name}!"
-    #     when "fr" then "Bonjour, #{name}!"
-    #     else "Hello, #{name}!"
-    #     end
-    #   rescue => e
-    #     "Sorry, I couldn't greet you: #{e.message}"
-    #   end
-    def self.tool(name, description: "", &block)
-      # Create anonymous class that extends Tool
-      Class.new(Tool) do
-        self.name = name
-        self.description = description
-
-        define_method :perform, &block
-      end.new
-    end
   end
 end

data/lib/agents/version.rb

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

data/lib/agents.rb

@@ -11,6 +11,18 @@ require_relative "agents/version"
 module Agents
   class Error < StandardError; end
 
+  # OpenAI's recommended system prompt prefix for multi-agent workflows
+  # This helps agents understand they're part of a coordinated system
+  RECOMMENDED_HANDOFF_PROMPT_PREFIX =
+    "# System context\n" \
+    "You are part of a multi-agent system called the Ruby Agents SDK, designed to make agent " \
+    "coordination and execution easy. Agents uses two primary abstraction: **Agents** and " \
+    "**Handoffs**. An agent encompasses instructions and tools and can hand off a " \
+    "conversation to another agent when appropriate. " \
+    "Handoffs are achieved by calling a handoff function, generally named " \
+    "`handoff_to_<agent_name>`. Transfers between agents are handled seamlessly in the background; " \
+    "do not mention or draw attention to these transfers in your conversation with the user.\n"
+
   class << self
     # Logger for debugging (can be set by users)
     attr_accessor :logger
@@ -66,5 +78,7 @@ require_relative "agents/handoff"
 require_relative "agents/agent"
 
 # Execution components
+require_relative "agents/chat"
 require_relative "agents/tool_wrapper"
+require_relative "agents/agent_runner"
 require_relative "agents/runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Shivam Mishra
@@ -51,6 +51,8 @@ files:
 - examples/isp-support/tools/search_docs_tool.rb
 - lib/agents.rb
 - lib/agents/agent.rb
+- lib/agents/agent_runner.rb
+- lib/agents/chat.rb
 - lib/agents/handoff.rb
 - lib/agents/result.rb
 - lib/agents/run_context.rb