ai-agents 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 004f33c8652e5b8c4d8be7bd84e959c55f6926411d3cac8bd3b3d029b7b21690
-  data.tar.gz: 6592c590cd91809ee47865a25adcf734370695bd4c697b1926aabc95c6e2d574
+  metadata.gz: 63e05456e057d627b1b3a3f75bfbbf5753b7dc7521fc429376681d6ffe222e54
+  data.tar.gz: 354528a7d4eae51c5598b41ad7fbfb77ec715e9354469c827074a974cb1e43c4
 SHA512:
-  metadata.gz: 0baadd9d0771c8e2bdd345a0a8e00bc792c6a607ec78b8796a6718e4695dc5e92b2fdc2ec11b4384c77ad409af4660be5288b020c6404750a2db5a66d1cf094c
-  data.tar.gz: de6edbb743e8b01634aaa12c656bc7cfa618de8086aa4e4e6add08683e8383b611856b4b9fa452c2e2e2bbd3efa2a74edefcc17af8188d2605babfc5067ecaf2
+  metadata.gz: 1d6ff99299ba88e2fba47cff1fb13f686e30bf4826014da7bec95b7363609f8b6acc2bb69a86393786d048bd693d4b1efb2697cd6a7376abe0a81f6ea347da0d
+  data.tar.gz: 43fb8db36d106caff7220bcdc4f6dba063a0b82b208baf757a7ffa578d7dde8dd917cff408cfa897037c0a2c6efbe004685399bbe93dce92958575f1181112f8

data/README.md

@@ -2,14 +2,16 @@
 <br>
 <br>
 <p>
-  <img src="./.github/ruby-agent.png" width="200px"/>
-  <h1>Ruby Agents</h1>
+  <img src="./.github/ruby-agents.png" height="80px"/>
+  <h1>
+    AI 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.
+A delightful provider agnostic Ruby SDK for building multi-agent AI workflows with seamless handoffs tool calling, and shared context.
 
 ## ✨ Features
 
@@ -17,7 +19,6 @@ A Ruby SDK for building multi-agent AI workflows with seamless handoffs, inspire
 - **🔄 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
@@ -66,32 +67,32 @@ triage = Agents::Agent.new(
   instructions: "Route customers to the right specialist"
 )
 
-faq = Agents::Agent.new(
-  name: "FAQ Agent", 
-  instructions: "Answer frequently asked questions",
-  tools: [FaqLookupTool.new]
+sales = Agents::Agent.new(
+  name: "Sales Agent",
+  instructions: "Answer details about plans",
+  tools: [CreateLeadTool.new, CRMLookupTool.new]
 )
 
 support = Agents::Agent.new(
   name: "Support Agent",
-  instructions: "Handle technical issues", 
-  tools: [TicketTool.new]
+  instructions: "Handle account realted and technical issues",
+  tools: [FaqLookupTool.new, 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
+triage.register_handoffs(sales, support)
+sales.register_handoffs(triage)     # Can route back to triage
+support.register_handoffs(triage)   # Hub-and-spoke pattern
 
 # Create runner with all agents (triage is default entry point)
-runner = Agents::Runner.with_agents(triage, faq, support)
+runner = Agents::Runner.with_agents(triage, sales, 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!
+result = runner.run("Do you have special plans for businesses?")
+# User gets direct answer from sales agent without knowing about the handoff!
 
 # Continue the conversation seamlessly
-result = runner.run("What about technical support?", context: result.context)
+result = runner.run("What is the pricing for the premium fibre plan?", context: result.context)
 # Context automatically tracks conversation history and current agent
 ```
 
@@ -99,19 +100,15 @@ result = runner.run("What about technical support?", context: result.context)
 
 ### Core Components
 
-- **Agent**: Individual AI agents with specific roles and capabilities
-- **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
+- **Agent**: Individual AI assistants configured with specific instructions, tools, and handoff relationships. Agents are immutable and thread-safe.
+- **AgentRunner**: Thread-safe execution manager that coordinates multi-agent conversations. Create once and reuse across multiple threads safely.
+- **Runner**: Internal orchestrator that handles individual conversation turns and manages the execution loop (used internally by AgentRunner).
+- **Context & State**: Shared conversation state that persists across agent handoffs. Fully serializable for database storage and session management.
+- **Tools**: Custom functions that agents can execute to interact with external systems (APIs, databases, etc.).
+- **Handoffs**: Automatic transfers between specialized agents based on conversation context, completely transparent to users.
 
 ### Agent Definition
 
-Agents can be created in two ways:
-
-#### Instance-based (Recommended for dynamic agents)
-
 ```ruby
 # Create agents as instances
 agent = Agents::Agent.new(
@@ -125,21 +122,6 @@ agent = Agents::Agent.new(
 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
@@ -158,10 +140,8 @@ end
 
 ### Handoff Patterns
 
-#### Hub-and-Spoke Pattern (Recommended)
-
 ```ruby
-# Central triage agent routes to specialists
+# Central triage agent routes to specialists (hub-and-spoke pattern)
 triage = Agents::Agent.new(name: "Triage")
 billing = Agents::Agent.new(name: "Billing")
 support = Agents::Agent.new(name: "Support")
@@ -174,18 +154,6 @@ 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 & Persistence
 
 ```ruby
@@ -201,7 +169,7 @@ puts context[:conversation_history]
 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
+json_context = JSON.dump(context)
 
 # Later: restore and continue conversation
 restored_context = JSON.parse(json_context, symbolize_names: true)
@@ -211,53 +179,13 @@ result = runner.run("Actually, I need technical support too", context: restored_
 
 ## 📋 Examples
 
-### ISP Customer Support
-
-See the complete ISP support example in `examples/isp-support/`:
+Check out the `examples/` folder for complete working demos showcasing multi-agent workflows.
 
-```ruby
-# Run the interactive demo
+```bash
+# Run the ISP support 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
@@ -298,8 +226,3 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 - 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/docs/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "jekyll"
+gem "just-the-docs"
+gem "webrick"
+
+# GitHub Pages plugins
+group :jekyll_plugins do
+  gem "jekyll-remote-theme"
+  gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
+end

data/docs/Gemfile.lock

@@ -0,0 +1,183 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    base64 (0.3.0)
+    bigdecimal (3.2.2)
+    colorator (1.1.0)
+    concurrent-ruby (1.3.5)
+    csv (3.3.5)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.31.1)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-aarch64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-aarch64-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-x86-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-x86-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-x86_64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.31.1-x86_64-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    http_parser.rb (0.8.0)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.4.1)
+      addressable (~> 2.4)
+      base64 (~> 0.2)
+      colorator (~> 1.0)
+      csv (~> 3.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.3, >= 0.3.6)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-remote-theme (0.4.3)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
+      rubyzip (>= 1.3.0, < 3.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    json (2.12.2)
+    just-the-docs (0.10.1)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (6.0.2)
+    rake (13.3.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.4.1)
+    rouge (4.5.2)
+    rubyzip (2.4.1)
+    safe_yaml (1.0.5)
+    sass-embedded (1.89.2)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.89.2-aarch64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-aarch64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-aarch64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-arm-linux-androideabi)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-arm-linux-gnueabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-arm-linux-musleabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-arm64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-riscv64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-riscv64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-riscv64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-x86_64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-x86_64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.89.2-x86_64-linux-musl)
+      google-protobuf (~> 4.31)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
+    webrick (1.9.1)
+
+PLATFORMS
+  aarch64-linux-android
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-androideabi
+  arm-linux-gnu
+  arm-linux-gnueabihf
+  arm-linux-musl
+  arm-linux-musleabihf
+  arm64-darwin
+  riscv64-linux-android
+  riscv64-linux-gnu
+  riscv64-linux-musl
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-android
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  jekyll
+  jekyll-remote-theme
+  jekyll-seo-tag
+  jekyll-sitemap
+  just-the-docs
+  webrick
+
+BUNDLED WITH
+   2.6.9

data/docs/_config.yml

@@ -0,0 +1,53 @@
+title: AI Agents
+description: A Ruby SDK for building multi-agent AI workflows
+baseurl: ""
+url: ""
+
+# Theme
+theme: just-the-docs
+
+# Color scheme
+color_scheme: ruby
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Navigation
+nav_sort: case_insensitive
+nav_external_links:
+  - title: GitHub
+    url: https://github.com/chatwoot/ai-agents
+
+# Footer
+footer_content: "Copyright © 2025 Chatwoot Inc."
+
+# Plugins
+plugins:
+  - jekyll-remote-theme
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Markdown
+markdown: kramdown
+highlighter: rouge
+
+# Exclude from processing
+exclude:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - node_modules/
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/

data/docs/_sass/color_schemes/ruby.scss

@@ -0,0 +1,72 @@
+// Ruby red color scheme for AI Agents documentation
+// Inspired by Ruby's signature red color
+
+// Define red color variables
+$red-000: #fff5f5;
+$red-100: #fed7d7;
+$red-200: #feb2b2;
+$red-300: #fc8181;
+$red-400: #e53e3e;
+$red-500: #d30001; // Primary Ruby red
+$red-600: #b30001;
+$red-700: #930001;
+$red-800: #730001;
+$red-900: #530001;
+
+// Grey colors with subtle reddish tint for text and backgrounds
+$grey-dk-000: #959396;
+$grey-dk-100: #5c5962;
+$grey-dk-200: #44434d;
+$grey-dk-250: #302d36;
+$grey-dk-300: #27262b;
+
+$grey-lt-000: #faf6f6; // Very slightly reddish background
+$grey-lt-100: #f7f2f2; // Very subtle reddish tint
+$grey-lt-200: #f4efef; // Very subtle reddish tint
+$grey-lt-300: #f0e8e8; // Very subtle reddish tint
+
+// Override theme variables
+$link-color: $red-500;
+$btn-primary-color: $red-500;
+$base-button-color: #f7f7f7;
+
+// Navigation
+$nav-child-link-color: $grey-dk-100;
+$nav-list-item-color: $grey-dk-100;
+$nav-list-item-active-color: $red-500;
+
+// Sidebar background
+$sidebar-color: $grey-lt-100; // Subtle reddish tint for sidebar
+
+// Search
+$search-active-color: $red-500;
+$search-background-color: $grey-lt-000;
+
+// Code
+$code-background-color: $grey-lt-000;
+$code-border-color: $grey-lt-300;
+
+// Tables
+$table-background-color: $grey-lt-000;
+$border-color: $grey-lt-300;
+
+// Buttons
+$btn-outline-color: $red-500;
+
+// Focus states
+$focus-color: $red-400;
+
+// Feedback states
+$feedback-color: $grey-lt-300;
+
+// Headings
+$h1-color: $grey-dk-300;
+$h2-color: $grey-dk-300;
+$h3-color: $grey-dk-200;
+$h4-color: $grey-dk-200;
+$h5-color: $grey-dk-200;
+$h6-color: $grey-dk-200;
+
+// Body text
+$body-text-color: $grey-dk-100;
+$body-heading-color: $grey-dk-300;

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,93 @@
+// Self-hosted Inter Variable font
+@font-face {
+  font-family: "Inter";
+  src: url("/assets/fonts/InterVariable.woff2") format("woff2-variations");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+  font-named-instance: "Regular";
+}
+
+// Override font variables
+$body-font-family:
+  "Inter",
+  -apple-system,
+  BlinkMacSystemFont,
+  "Segoe UI",
+  Helvetica,
+  Arial,
+  sans-serif;
+$mono-font-family: "SF Mono", Monaco, Inconsolata, "Roboto Mono", monospace;
+
+// Apply Inter to all text elements
+body {
+  font-family: $body-font-family;
+  font-feature-settings:
+    "cv02", "cv03", "cv04", "cv11"; // Display-like features
+}
+
+// Ensure headings use Inter as well
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: $body-font-family;
+}
+
+// Custom logo styling
+.site-logo {
+  padding: 1rem;
+  border-bottom: 1px solid var(--border-color);
+
+  .site-logo-link {
+    display: flex;
+    align-items: center;
+    text-decoration: none;
+    color: inherit;
+
+    &:hover {
+      text-decoration: none;
+    }
+  }
+
+  .site-logo-image {
+    width: 32px;
+    height: 32px;
+    margin-right: 0.75rem;
+    border-radius: 6px;
+  }
+
+  .site-title {
+    font-weight: 600;
+    font-size: 1.1rem;
+    color: var(--body-heading-color);
+  }
+}
+
+// Note callout styling
+.note {
+  padding: 1rem;
+  margin: 1rem 0;
+  background-color: #faf6f6;
+  border: 1px solid #f0e8e8;
+  border-left: 4px solid #d30001;
+  border-radius: 6px;
+  position: relative;
+
+  &::before {
+    content: "NOTE";
+    font-weight: 600;
+    font-size: 0.75rem;
+    color: #d30001;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    display: block;
+    margin-bottom: 0.5rem;
+  }
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+}