ai-agents 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d23007ce65c6dae4c20025ad5cacb683652452a973472fa3c9fba1166606e57
-  data.tar.gz: 39b4522bd4ee7e329285a3806a4e06e5e312526e9139d4369bb7a12f4ede2d06
+  metadata.gz: 004f33c8652e5b8c4d8be7bd84e959c55f6926411d3cac8bd3b3d029b7b21690
+  data.tar.gz: 6592c590cd91809ee47865a25adcf734370695bd4c697b1926aabc95c6e2d574
 SHA512:
-  metadata.gz: bc45c4328b0ec188abb77249ee3da9de9515251f2c872b8468c1704d49ea3765cb1dae285cad84c6fd1b644d6adde35073ddf09a6071c82b8ae7671ebbc67d52
-  data.tar.gz: 354a10db6fab8d2885c1bdd6e20e72086a9cd87e1a16b99c1b744f0c35b962b19b07aafcf7c0ca0301f30bccc0a8e3ba00de13807178e7d02ec16466ba002a79
+  metadata.gz: 0baadd9d0771c8e2bdd345a0a8e00bc792c6a607ec78b8796a6718e4695dc5e92b2fdc2ec11b4384c77ad409af4660be5288b020c6404750a2db5a66d1cf094c
+  data.tar.gz: de6edbb743e8b01634aaa12c656bc7cfa618de8086aa4e4e6add08683e8383b611856b4b9fa452c2e2e2bbd3efa2a74edefcc17af8188d2605babfc5067ecaf2

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,11 +48,10 @@ module ISPSupport
       )
     end
 
-
     def create_sales_agent
       Agents::Agent.new(
         name: "Sales Agent",
-        instructions: sales_instructions,
+        instructions: sales_instructions_with_state,
         model: "gpt-4.1-mini",
         tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new]
       )
@@ -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,19 +99,76 @@ 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
 
+    def sales_instructions_with_state
+      lambda { |context|
+        state = context.context[:state] || {}
+
+        base_instructions = <<~INSTRUCTIONS
+          You are the Sales Agent for an ISP. You handle new customer acquisition, service upgrades,
+          and plan changes.
+
+          **Your tools:**
+          - `create_lead`: Create sales leads with customer information
+          - `create_checkout`: Generate secure checkout links for purchases
+          - Handoff tools: Route back to triage when needed
+
+          **When to hand off:**
+          - Pure technical support questions → Triage Agent for re-routing
+          - Customer needs to speak with human agent → Triage Agent for re-routing
+        INSTRUCTIONS
+
+        # Add customer context if available from previous agent interactions
+        if state[:customer_name] && state[:customer_id]
+          base_instructions += <<~CONTEXT
+
+            **Customer Context Available:**
+            - Customer Name: #{state[:customer_name]}
+            - Customer ID: #{state[:customer_id]}
+            - Email: #{state[:customer_email]}
+            - Phone: #{state[:customer_phone]}
+            - Address: #{state[:customer_address]}
+            #{state[:current_plan] ? "- Current Plan: #{state[:current_plan]}" : ""}
+            #{state[:account_status] ? "- Account Status: #{state[:account_status]}" : ""}
+            #{state[:monthly_usage] ? "- Monthly Usage: #{state[:monthly_usage]}GB" : ""}
+
+            **IMPORTANT:**#{" "}
+            - Use this existing customer information when creating leads or providing service
+            - Do NOT ask for name, email, phone, or address - you already have these details
+            - For new connections, use the existing customer details and only ask for the desired plan
+            - Provide personalized recommendations based on their current information
+          CONTEXT
+        end
+
+        base_instructions += <<~FINAL_INSTRUCTIONS
+
+          **Instructions:**
+          - Be enthusiastic but not pushy
+          - Gather required info: name, email, desired plan for leads
+          - 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
+        FINAL_INSTRUCTIONS
+
+        base_instructions
+      }
+    end
+
     def support_instructions
       <<~INSTRUCTIONS
         You are the Support Agent for an ISP. You handle technical support, troubleshooting,
@@ -126,8 +181,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 +191,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