ai-agents 0.4.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3f2287a007ce187c91546ee4ef723cadcde40e7102454d4d432c2c2c72e4e45
-  data.tar.gz: 4c9b810362d923c0fb821491a63fa8647c926e2666e6902383200ca8f988cf10
+  metadata.gz: 7f8fa7ec73784bc0fb1e9e6bd4852c6d0295160c4ca28d435c895cba28f5cd58
+  data.tar.gz: 3e489f11ae2a5c93b4232ec78e3c7385c83f303c28039ed35fa082669fedaf4b
 SHA512:
-  metadata.gz: aaa5ba1612a2551b83d3f779a10301c806f9a95eb082b4c6ab6db56fdc90487093b0a5edd0c5edc16c2a4888e1ada2abc66433bab73c569886b3b66f0c41d528
-  data.tar.gz: 2669853cd34f497d696fba2ccf02ed384057ea144b7ffdd0c390aa28c1c4bf830929723f181a0bfd130e206707fc80f9c2a0e12259da53099ef8ab92c5f681d8
+  metadata.gz: ba5050ba743466993826d888673d90696d27f422df3d3972027fa141de05d6436c45cd44dba0836dc6350ad83c0ff1628ba43bbce6d93e5e49e8efc450554e91
+  data.tar.gz: efed7a181a6f52c4c8feb8b84e1bbb2309b5216a85569dae69dd4038cde0cdad7a283e066181414e50657aee063e79935573799fdc24abc6253b02bcb8e5d09f

data/.rubocop.yml

@@ -10,20 +10,18 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
+Metrics/MethodLength:
+  Max: 20
+Metrics/ClassLength:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
 RSpec/MultipleExpectations:
   Max: 10
-
 RSpec/ExampleLength:
   Max: 20
-
 RSpec/MultipleMemoizedHelpers:
   Max: 15
-
 RSpec/SpecFilePathFormat:
   Enabled: false
-
-Metrics/MethodLength:
-  Max: 20
-
-RSpec/MultipleDescribes:
-  Enabled: false

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.6.0] - 2025-10-16
+
+### Added
+- **Custom HTTP Headers Support**: Agents can now specify custom HTTP headers for LLM requests
+  - Added `headers` parameter to `Agent#initialize` for setting agent-level default headers
+  - Runtime headers can be passed via `headers` parameter in `AgentRunner#run` method
+  - Runtime headers take precedence over agent-level headers when keys overlap
+  - Headers are automatically normalized (symbolized keys) and validated
+  - Full support for headers across agent handoffs with proper merging logic
+  - New `Agents::Helpers::Headers` module for header normalization and merging
+  - Comprehensive test coverage for header functionality
+
+### Changed
+- **Code Organization**: Refactored internal helpers into dedicated module structure
+  - Moved `MessageExtractor` to `Agents::Helpers::MessageExtractor` module
+  - Converted `MessageExtractor` from class-based to module-function pattern
+  - Created `lib/agents/helpers/` directory for helper modules
+  - All helper modules now use consistent flat naming convention (`Agents::Helpers::ModuleName`)
+
+## [0.5.0] - 2025-08-20
+
+### Added
+- Tool halting functionality for enhanced agent control
+
+### Removed
+- Removed chat.rb component that made the codebase brittle
+
 ## [0.4.3] - 2025-08-04
 
 ### Fixed

data/CLAUDE.md

@@ -63,7 +63,6 @@ This will start a command-line interface where you can interact with the multi-a
 -   **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.
 -   **Callbacks**: Event hooks for monitoring agent execution, including agent thinking, tool start/complete, and handoffs.
@@ -114,7 +113,6 @@ 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
@@ -174,7 +172,7 @@ 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::AgentRunner.with_agents(triage, billing, support)
+runner = Agents::Runner.with_agents(triage, billing, support)
 
 # Add real-time callbacks for monitoring
 runner.on_agent_thinking { |agent_name, input| puts "🧠 #{agent_name} is thinking..." }

data/docs/concepts/callbacks.md

@@ -26,7 +26,7 @@ The SDK provides four types of callbacks that give you visibility into different
 Callbacks are registered on the AgentRunner using chainable methods:
 
 ```ruby
-runner = Agents::AgentRunner.with_agents(triage, support)
+runner = Agents::Runner.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" }

data/docs/guides/multi-agent-systems.md

@@ -23,7 +23,7 @@ billing_agent = Agents::Agent.new(
 )
 
 support_agent = Agents::Agent.new(
-  name: "Support", 
+  name: "Support",
   instructions: "Provide technical troubleshooting and product support."
 )
 
@@ -37,7 +37,7 @@ triage_agent = Agents::Agent.new(
 triage_agent.register_handoffs(billing_agent, support_agent)
 
 # Create runner with triage as entry point
-runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
 ```
 
 ### Dynamic Instructions
@@ -52,7 +52,7 @@ support_agent = Agents::Agent.new(
     <<~INSTRUCTIONS
       You are a technical support specialist for #{customer_tier} tier customers.
       #{customer_tier == "premium" ? "Provide priority white-glove service." : ""}
-      
+
       Available tools: diagnostics, escalation
     INSTRUCTIONS
   }
@@ -73,7 +73,7 @@ sales_agent = Agents::Agent.new(
 )
 
 support_agent = Agents::Agent.new(
-  name: "Support", 
+  name: "Support",
   instructions: "Handle technical issues and product troubleshooting. Transfer sales questions to sales team."
 )
 ```
@@ -108,7 +108,7 @@ The first agent in `AgentRunner.with_agents()` becomes the default entry point:
 
 ```ruby
 # Triage agent handles all initial conversations
-runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+runner = Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
 
 # Start conversation
 result = runner.run("I need help with my account")
@@ -168,9 +168,9 @@ triage_agent = Agents::Agent.new(
   name: "Triage",
   instructions: ->(context) {
     business_hours = context[:business_hours] || false
-    
+
     base_instructions = "Route users to appropriate departments."
-    
+
     if business_hours
       base_instructions + " All departments are available."
     else
@@ -189,8 +189,8 @@ Test each agent in isolation:
 ```ruby
 RSpec.describe "BillingAgent" do
   let(:agent) { create_billing_agent }
-  let(:runner) { Agents::AgentRunner.with_agents(agent) }
-  
+  let(:runner) { Agents::Runner.with_agents(agent) }
+
   it "handles payment inquiries" do
     result = runner.run("What payment methods do you accept?")
     expect(result.output).to include("credit card", "bank transfer")
@@ -205,13 +205,13 @@ Test complete workflows:
 ```ruby
 RSpec.describe "Customer Support Workflow" do
   let(:runner) { create_support_runner } # Creates triage + specialists
-  
+
   it "routes billing questions correctly" do
     result = runner.run("I have a billing question")
-    
+
     # Verify handoff occurred
     expect(result.context[:current_agent]).to eq("Billing")
-    
+
     # Test continued conversation
     followup = runner.run("What are your payment terms?", context: result.context)
     expect(followup.output).to include("payment terms")
@@ -258,4 +258,4 @@ threads = users.map do |user|
     # Handle result...
   end
 end
-```
+```

data/docs/guides/rails-integration.md

@@ -49,7 +49,7 @@ class CreateConversations < ActiveRecord::Migration[7.0]
       t.string :current_agent
       t.timestamps
     end
-    
+
     add_index :conversations, [:user_id, :created_at]
   end
 end
@@ -61,25 +61,25 @@ Define the Conversation model:
 # app/models/conversation.rb
 class Conversation < ApplicationRecord
   belongs_to :user
-  
+
   # Serialize context as JSON
   serialize :context, JSON
-  
+
   validates :context, presence: true
-  
+
   def self.for_user(user)
     where(user: user).order(:created_at)
   end
-  
+
   def self.latest_for_user(user)
     for_user(user).last
   end
-  
+
   # Convert to agent context hash
   def to_agent_context
     context.deep_symbolize_keys
   end
-  
+
   # Create from agent result
   def self.from_agent_result(user, result)
     create!(
@@ -102,26 +102,26 @@ class AgentConversationService
     @user = user
     @runner = create_agent_runner
   end
-  
+
   def send_message(message)
     # Get existing conversation context
     context = load_conversation_context
-    
+
     # Run agent with message
     result = @runner.run(message, context: context)
-    
+
     # Persist updated conversation
     save_conversation(result)
-    
+
     result
   end
-  
+
   def reset_conversation
     Conversation.where(user: @user).destroy_all
   end
-  
+
   private
-  
+
   def create_agent_runner
     # Create your agents here
     triage_agent = Agents::Agent.new(
@@ -129,52 +129,52 @@ class AgentConversationService
       instructions: build_triage_instructions,
       tools: [CustomerLookupTool.new]
     )
-    
+
     billing_agent = Agents::Agent.new(
       name: "Billing",
       instructions: "Handle billing and payment inquiries.",
       tools: [BillingTool.new, PaymentTool.new]
     )
-    
+
     support_agent = Agents::Agent.new(
       name: "Support",
       instructions: "Provide technical support and troubleshooting.",
       tools: [TechnicalTool.new]
     )
-    
+
     triage_agent.register_handoffs(billing_agent, support_agent)
-    
-    Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+
+    Agents::Runner.with_agents(triage_agent, billing_agent, support_agent)
   end
-  
+
   def build_triage_instructions
     ->(context) {
       user_info = context[:user_info] || {}
-      
+
       <<~INSTRUCTIONS
         You are a customer service triage agent for #{@user.name}.
-        
+
         Customer Details:
         - Name: #{@user.name}
         - Email: #{@user.email}
         - Account Type: #{user_info[:account_type] || 'standard'}
-        
+
         Route customers to the appropriate department:
         - Billing: Payment issues, account billing, refunds
         - Support: Technical problems, product questions
-        
+
         Always be professional and helpful.
       INSTRUCTIONS
     }
   end
-  
+
   def load_conversation_context
     latest_conversation = Conversation.latest_for_user(@user)
     return initial_context unless latest_conversation
-    
+
     latest_conversation.to_agent_context
   end
-  
+
   def initial_context
     {
       user_id: @user.id,
@@ -185,7 +185,7 @@ class AgentConversationService
       }
     }
   end
-  
+
   def save_conversation(result)
     Conversation.from_agent_result(@user, result)
   end
@@ -200,13 +200,13 @@ Create a controller for handling agent conversations:
 # app/controllers/agent_conversations_controller.rb
 class AgentConversationsController < ApplicationController
   before_action :authenticate_user!
-  
+
   def create
     service = AgentConversationService.new(current_user)
-    
+
     begin
       result = service.send_message(params[:message])
-      
+
       render json: {
         response: result.output,
         agent: result.context[:current_agent],
@@ -217,19 +217,19 @@ class AgentConversationsController < ApplicationController
       render json: { error: "Unable to process your request" }, status: 500
     end
   end
-  
+
   def reset
     service = AgentConversationService.new(current_user)
     service.reset_conversation
-    
+
     render json: { message: "Conversation reset successfully" }
   end
-  
+
   def history
     conversations = Conversation.for_user(current_user)
                                .includes(:user)
                                .limit(50)
-    
+
     render json: conversations.map do |conv|
       {
         id: conv.id,
@@ -252,13 +252,13 @@ class CustomerLookupTool < Agents::Tool
   name "lookup_customer"
   description "Look up customer information by email or ID"
   param :identifier, type: "string", desc: "Email address or customer ID"
-  
+
   def perform(tool_context, identifier:)
     # Access Rails models safely
     customer = User.find_by(email: identifier) || User.find_by(id: identifier)
-    
+
     return "Customer not found" unless customer
-    
+
     {
       name: customer.name,
       email: customer.email,
@@ -274,13 +274,13 @@ class BillingTool < Agents::Tool
   name "get_billing_info"
   description "Retrieve billing information for a customer"
   param :user_id, type: "integer", desc: "Customer user ID"
-  
+
   def perform(tool_context, user_id:)
     user = User.find(user_id)
     billing_info = user.billing_profile
-    
+
     return "No billing information found" unless billing_info
-    
+
     {
       plan: billing_info.plan_name,
       status: billing_info.status,
@@ -301,13 +301,13 @@ For longer conversations, use background jobs:
 # app/jobs/agent_conversation_job.rb
 class AgentConversationJob < ApplicationJob
   queue_as :default
-  
+
   def perform(user_id, message, conversation_id = nil)
     user = User.find(user_id)
     service = AgentConversationService.new(user)
-    
+
     result = service.send_message(message)
-    
+
     # Broadcast result via ActionCable
     ActionCable.server.broadcast(
       "agent_conversation_#{user_id}",
@@ -327,7 +327,7 @@ def create_async
     params[:message],
     params[:conversation_id]
   )
-  
+
   render json: { job_id: job_id }
 end
 ```
@@ -341,12 +341,12 @@ Implement comprehensive error handling:
 class AgentConversationService
   class AgentError < StandardError; end
   class ContextError < StandardError; end
-  
+
   def send_message(message)
     validate_message(message)
-    
+
     context = load_conversation_context
-    
+
     begin
       result = @runner.run(message, context: context)
       save_conversation(result)
@@ -359,9 +359,9 @@ class AgentConversationService
       raise ContextError, "Conversation context corrupted"
     end
   end
-  
+
   private
-  
+
   def validate_message(message)
     raise ArgumentError, "Message cannot be blank" if message.blank?
     raise ArgumentError, "Message too long" if message.length > 5000
@@ -378,26 +378,26 @@ Test Rails integration with RSpec:
 RSpec.describe AgentConversationService do
   let(:user) { create(:user) }
   let(:service) { described_class.new(user) }
-  
+
   describe '#send_message' do
     it 'creates a conversation record' do
       expect {
         service.send_message("Hello")
       }.to change(Conversation, :count).by(1)
     end
-    
+
     it 'persists context correctly' do
       result = service.send_message("Hello")
       conversation = Conversation.last
-      
+
       expect(conversation.user).to eq(user)
       expect(conversation.context).to include('user_id' => user.id)
     end
   end
-  
+
   describe '#reset_conversation' do
     before { service.send_message("Hello") }
-    
+
     it 'destroys all conversations for user' do
       expect {
         service.reset_conversation
@@ -437,4 +437,4 @@ add_index :conversations, :created_at
 every 1.day, at: '2:00 am' do
   runner "Conversation.where('created_at < ?', 30.days.ago).destroy_all"
 end
-```
+```

data/docs/guides/request-headers.md

@@ -0,0 +1,91 @@
+---
+layout: default
+title: Custom Request Headers
+parent: Guides
+nav_order: 6
+---
+
+# Custom Request Headers
+
+Custom HTTP headers allow you to pass additional metadata with your LLM API requests. This is useful for authentication, request tracking, A/B testing, and provider-specific features.
+
+## Basic Usage
+
+### Agent-Level Headers
+
+Set default headers when creating an agent that will be applied to all requests:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant",
+  headers: {
+    "X-Custom-ID" => "agent-123",
+    "X-Environment" => "production"
+  }
+)
+
+runner = Agents::Runner.with_agents(agent)
+result = runner.run("Hello!")
+# All requests will include the custom headers
+```
+
+### Runtime Headers
+
+Override or add headers for specific requests:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant"
+)
+
+runner = Agents::Runner.with_agents(agent)
+
+# Pass headers at runtime
+result = runner.run(
+  "What's the weather?",
+  headers: {
+    "X-Request-ID" => "req-456",
+    "X-User-ID" => "user-789"
+  }
+)
+```
+
+### Header precedence
+
+When both agent-level and runtime headers are provided, **runtime headers take precedence**:
+
+```ruby
+agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant",
+  headers: {
+    "X-Environment" => "staging",
+    "X-Agent-ID" => "agent-001"
+  }
+)
+
+runner = Agents::Runner.with_agents(agent)
+
+result = runner.run(
+  "Hello!",
+  headers: {
+    "X-Environment" => "production",  # Overrides agent's staging value
+    "X-Request-ID" => "req-123"       # Additional header
+  }
+)
+
+# Final headers sent to LLM API:
+# {
+#   "X-Environment" => "production",  # Runtime value wins
+#   "X-Agent-ID" => "agent-001",      # From agent
+#   "X-Request-ID" => "req-123"       # From runtime
+# }
+```
+
+## See Also
+
+- [Multi-Agent Systems](multi-agent-systems.html) - Using headers across agent handoffs
+- [Rails Integration](rails-integration.html) - Request tracking in Rails applications
+- [State Persistence](state-persistence.html) - Combining headers with conversation state

data/docs/guides/structured-output.md

@@ -30,7 +30,7 @@ extraction_agent = Agents::Agent.new(
   }
 )
 
-runner = Agents::AgentRunner.with_agents(extraction_agent)
+runner = Agents::Runner.with_agents(extraction_agent)
 result = runner.run("I love the new product features, especially the API and dashboard!")
 
 # Response will be valid JSON matching the schema:
@@ -62,7 +62,7 @@ contact_agent = Agents::Agent.new(
   response_schema: ContactSchema
 )
 
-runner = Agents::AgentRunner.with_agents(contact_agent)
+runner = Agents::Runner.with_agents(contact_agent)
 result = runner.run("Hi, I'm Sarah Johnson from TechCorp. You can reach me at sarah@techcorp.com or 555-0123. I'm interested in AI and automation solutions.")
 
 # Returns structured contact data:

data/docs/guides.md

@@ -17,3 +17,4 @@ Practical guides for building real-world applications with the AI Agents library
 - **[Rails Integration](guides/rails-integration.html)** - Integrating agents with Ruby on Rails applications and ActiveRecord persistence
 - **[State Persistence](guides/state-persistence.html)** - Managing conversation state and context across sessions and processes
 - **[Structured Output](guides/structured-output.html)** - Enforcing JSON schema validation for reliable agent responses
+- **[Custom Request Headers](guides/request-headers.html)** - Adding custom HTTP headers for authentication, tracking, and provider-specific features

data/docs/index.md

@@ -81,7 +81,7 @@ support = Agents::Agent.new(
 triage.register_handoffs(support)
 
 # Create runner and start conversation
-runner = Agents::AgentRunner.with_agents(triage, support)
+runner = Agents::Runner.with_agents(triage, support)
 result = runner.run("I need help with a technical issue")
 
 puts result.output