ai-agents 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d23007ce65c6dae4c20025ad5cacb683652452a973472fa3c9fba1166606e57
+  data.tar.gz: 39b4522bd4ee7e329285a3806a4e06e5e312526e9139d4369bb7a12f4ede2d06
+SHA512:
+  metadata.gz: bc45c4328b0ec188abb77249ee3da9de9515251f2c872b8468c1704d49ea3765cb1dae285cad84c6fd1b644d6adde35073ddf09a6071c82b8ae7671ebbc67d52
+  data.tar.gz: 354a10db6fab8d2885c1bdd6e20e72086a9cd87e1a16b99c1b744f0c35b962b19b07aafcf7c0ca0301f30bccc0a8e3ba00de13807178e7d02ec16466ba002a79

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,26 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 15
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20

data/CLAUDE.md

@@ -0,0 +1,188 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+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.
+
+**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
+
+## Development Commands
+
+### Building and Testing
+```bash
+# Install dependencies
+bundle install
+
+# Run tests with RSpec
+rake spec
+# OR
+bundle exec rspec
+
+# Run specific spec file
+bundle exec rspec spec/agents/agent_spec.rb
+
+# Run tests with coverage report
+bundle exec rspec  # SimpleCov will generate coverage/index.html
+
+# Lint code (includes RSpec cops)
+rake rubocop
+# OR
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Run all checks (spec + lint)
+rake
+```
+
+### 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
+```
+
+## Architecture and Code Structure
+
+### Core Components (Generic Library)
+
+**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.
+
+**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
+
+**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
+
+**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
+
+**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.
+
+**lib/agents/runner.rb** - Execution engine for orchestrating multi-agent workflows (future implementation).
+
+### Key Design Patterns
+
+#### 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
+```
+
+#### 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
+```
+
+#### 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
+
+#### 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
+
+### Configuration Rules
+
+#### Class Naming
+- Use flat naming like `class Agents::Tool` instead of nested declarations
+- Follow Ruby naming conventions for agent and tool classes
+
+#### 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
+
+#### 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
+
+### Examples Structure
+
+**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.
+
+### Dependencies and Integration
+
+**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"`
+
+**Provider Support** - Currently supports OpenAI through RubyLLM, extensible to other providers
+
+### Important Implementation Details
+
+1. **Conversation History**: Must call `restore_conversation_history(chat)` before each agent execution to maintain conversation state across turns.
+
+2. **Tool Context Flow**: `RubyLLM.execute()` → `Agents::Tool.execute()` → `Tool.perform(context:, **args)` - the context injection happens in the base `Tool.execute` method.
+
+3. **Handoff Detection**: Uses context-based detection (`@context[:pending_handoff]`) rather than parsing LLM responses for tool calls.
+
+4. **Model Configuration**: Default model is `gpt-4.1-mini` but examples use `gpt-4o` for better performance.
+
+5. **Thread Safety**: Agents are designed to be stateless with context passed through execution rather than stored in instance variables.
+
+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.
+
+### Testing Guidelines
+
+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
+```

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chatwoot Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,283 @@
+<div align="center">
+<br>
+<br>
+<p>
+  <img src="./.github/ruby-agent.png" width="200px"/>
+  <h1>Ruby Agents</h1>
+</p>
+<br>
+<br>
+</div>
+
+A Ruby SDK for building multi-agent AI workflows with seamless handoffs, inspired by OpenAI's Agents SDK but built specifically for Ruby developers.
+
+## ✨ Features
+
+- **🤖 Multi-Agent Orchestration**: Create specialized AI agents that work together
+- **🔄 Seamless Handoffs**: Transparent agent-to-agent transfers (users never know!)
+- **🛠️ Tool Integration**: Agents can use custom tools and functions
+- **💾 Shared Context**: State management across agent interactions
+- **🚀 Simple API**: One method call handles everything including handoffs
+- **🔌 Provider Agnostic**: Works with OpenAI, Anthropic, and other LLM providers
+
+## 🚀 Quick Start
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'ai-agents'
+```
+
+### Basic Usage
+
+```ruby
+require 'agents'
+
+# Configure with your API key
+Agents.configure do |config|
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+end
+
+# Create a simple agent
+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?")
+puts result.output
+```
+
+### Multi-Agent Workflows with Handoffs
+
+The real power comes from multi-agent workflows with automatic handoffs:
+
+```ruby
+# Create specialized agents
+triage = Agents::Agent.new(
+  name: "Triage Agent",
+  instructions: "Route customers to the right specialist"
+)
+
+faq = Agents::Agent.new(
+  name: "FAQ Agent",
+  instructions: "Answer frequently asked questions",
+  tools: [FaqLookupTool.new]
+)
+
+support = Agents::Agent.new(
+  name: "Support Agent",
+  instructions: "Handle technical issues",
+  tools: [TicketTool.new]
+)
+
+# Wire up handoff relationships - clean and simple!
+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?")
+# User gets direct answer from FAQ agent without knowing about the handoff!
+```
+
+## 🏗️ Architecture
+
+### 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
+- **Tools**: Custom functions that agents can use
+- **Handoffs**: Seamless transfers between specialized agents
+
+### Agent Definition
+
+Agents can be created in two ways:
+
+#### Instance-based (Recommended for dynamic agents)
+
+```ruby
+# Create agents as instances
+agent = Agents::Agent.new(
+  name: "Customer Service",
+  instructions: "You are a helpful customer service agent.",
+  model: "gpt-4o",
+  tools: [EmailTool.new, TicketTool.new]
+)
+
+# Register handoffs after creation
+agent.register_handoffs(technical_support, billing)
+```
+
+#### Class-based (Coming soon)
+
+```ruby
+class CustomerServiceAgent < Agents::Agent
+  name "Customer Service"
+  instructions <<~PROMPT
+    You are a helpful customer service agent.
+    Always be polite and professional.
+  PROMPT
+
+  model "gpt-4o"
+  uses EmailTool, TicketTool
+end
+```
+
+### Custom Tools
+
+```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"
+
+  def perform(to:, subject:, body:, context:)
+    # Send email logic here
+    "Email sent to #{to}"
+  end
+end
+```
+
+### Handoff Patterns
+
+#### Hub-and-Spoke Pattern (Recommended)
+
+```ruby
+# Central triage agent routes to specialists
+triage = Agents::Agent.new(name: "Triage")
+billing = Agents::Agent.new(name: "Billing")
+support = Agents::Agent.new(name: "Support")
+
+# Triage can route to any specialist
+triage.register_handoffs(billing, support)
+
+# Specialists only route back to triage
+billing.register_handoffs(triage)
+support.register_handoffs(triage)
+```
+
+#### Circular Handoffs
+
+```ruby
+# Agents can hand off to each other
+sales = Agents::Agent.new(name: "Sales")
+customer_info = Agents::Agent.new(name: "Customer Info")
+
+# Both agents can transfer to each other
+sales.register_handoffs(customer_info)
+customer_info.register_handoffs(sales)
+```
+
+### Context Management
+
+```ruby
+# Context is automatically managed by the Runner
+context = {}
+result = Agents::Runner.run(agent, "Hello", context: context)
+
+# Access conversation history and agent state
+puts context[:conversation_history]
+puts context[:current_agent].name
+```
+
+## 📋 Examples
+
+### ISP Customer Support
+
+See the complete ISP support example in `examples/isp-support/`:
+
+```ruby
+# Run the interactive demo
+ruby examples/isp-support/interactive.rb
+```
+
+This showcases:
+- **Triage Agent**: Routes customers to appropriate specialists
+- **Customer Info Agent**: Handles account info and billing inquiries
+- **Sales Agent**: Manages new connections and upgrades
+- **Support Agent**: Provides technical troubleshooting
+- **Hub-and-Spoke Handoffs**: Clean architecture pattern
+
+### Airline Customer Service
+
+See the airline booking example in `examples/booking/`:
+
+```ruby
+# Run the interactive demo
+ruby examples/booking/interactive.rb
+```
+
+This showcases:
+- **Triage Agent**: Routes questions to specialists
+- **FAQ Agent**: Answers questions about policies, seats, baggage
+- **Seat Booking Agent**: Handles seat changes and updates
+- **Seamless Handoffs**: Users never repeat their questions
+
+### Sample Conversation
+
+```
+You: How many seats are on the plane?
+
+Agent: The plane has a total of 120 seats, which includes 22 business
+class seats and 98 economy seats. Exit rows are located at rows 4 and
+16, and rows 5-8 are designated as Economy Plus, offering extra legroom.
+```
+
+Behind the scenes:
+1. Triage Agent receives question
+2. Automatically transfers to FAQ Agent
+3. FAQ Agent processes original question and responds
+4. User sees seamless experience!
+
+## 🔧 Configuration
+
+```ruby
+Agents.configure do |config|
+  # Provider API keys
+  config.openai_api_key = ENV['OPENAI_API_KEY']
+  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  config.gemini_api_key = ENV['GEMINI_API_KEY']
+
+  # Defaults
+  config.default_provider = :openai
+  config.default_model = 'gpt-4o'
+
+  # Performance
+  config.request_timeout = 120
+  config.max_turns = 10
+
+  # Debugging
+  config.debug = true
+end
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`rake test`)
+4. Run linter (`rake rubocop`)
+5. Commit your changes (`git commit -am 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by [OpenAI's Agents SDK](https://github.com/openai/agents)
+- Built on top of [RubyLLM](https://rubyllm.com) for LLM integration
+- Thanks to the Ruby community for continuous inspiration
+
+---
+
+**Built with ❤️ by the Chatwoot Team**

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/README.md

@@ -0,0 +1,64 @@
+# Examples
+
+This directory contains examples demonstrating how to use the Ruby Agents SDK.
+
+## Prerequisites
+
+1. **Set up your API key:**
+   ```bash
+   export OPENAI_API_KEY=your_api_key_here
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   bundle install
+   ```
+
+## Running Examples
+
+### Basic Usage
+```bash
+ruby examples/basic_usage.rb
+```
+
+This example demonstrates:
+- Configuring the Agents gem
+- Creating a simple tool with parameters
+- Creating an agent that uses the tool
+- Testing both tool and agent functionality
+- Viewing conversation history
+
+### Expected Output
+
+The example will show:
+- ✅ Configuration success message
+- 🔧 Direct tool testing with different greeting styles
+- 🤖 Agent conversations using the tool
+- 📝 Conversation history with timestamps
+
+## What You'll Learn
+
+- How to configure the gem with `Agents.configure`
+- How to create tools that extend `Agents::Tool`
+- How to create agents that extend `Agents::Agent`
+- How to use tools within agents
+- How tools and agents integrate with RubyLLM
+
+## Troubleshooting
+
+### "No API keys configured" Error
+Make sure you've set the `OPENAI_API_KEY` environment variable:
+```bash
+export OPENAI_API_KEY=sk-your-key-here
+```
+
+### Connection Errors
+- Check your internet connection
+- Verify your API key is valid
+- Ensure you have sufficient API credits
+
+### Ruby Version
+Make sure you're using Ruby 3.1 or later:
+```bash
+ruby --version
+```