ai-agents 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/commands/bump-version.md +44 -0
  3. data/CHANGELOG.md +35 -0
  4. data/CLAUDE.md +59 -15
  5. data/README.md +29 -106
  6. data/docs/Gemfile +14 -0
  7. data/docs/Gemfile.lock +183 -0
  8. data/docs/_config.yml +53 -0
  9. data/docs/_sass/color_schemes/ruby.scss +72 -0
  10. data/docs/_sass/custom/custom.scss +93 -0
  11. data/docs/architecture.md +353 -0
  12. data/docs/assets/fonts/InterVariable.woff2 +0 -0
  13. data/docs/concepts/agent-tool.md +166 -0
  14. data/docs/concepts/agents.md +43 -0
  15. data/docs/concepts/callbacks.md +42 -0
  16. data/docs/concepts/context.md +110 -0
  17. data/docs/concepts/handoffs.md +81 -0
  18. data/docs/concepts/runner.md +87 -0
  19. data/docs/concepts/tools.md +62 -0
  20. data/docs/concepts.md +22 -0
  21. data/docs/guides/agent-as-tool-pattern.md +242 -0
  22. data/docs/guides/multi-agent-systems.md +261 -0
  23. data/docs/guides/rails-integration.md +440 -0
  24. data/docs/guides/state-persistence.md +451 -0
  25. data/docs/guides.md +18 -0
  26. data/docs/index.md +97 -0
  27. data/examples/collaborative-copilot/README.md +169 -0
  28. data/examples/collaborative-copilot/agents/analysis_agent.rb +48 -0
  29. data/examples/collaborative-copilot/agents/answer_suggestion_agent.rb +50 -0
  30. data/examples/collaborative-copilot/agents/copilot_orchestrator.rb +85 -0
  31. data/examples/collaborative-copilot/agents/integrations_agent.rb +58 -0
  32. data/examples/collaborative-copilot/agents/research_agent.rb +52 -0
  33. data/examples/collaborative-copilot/data/contacts.json +47 -0
  34. data/examples/collaborative-copilot/data/conversations.json +170 -0
  35. data/examples/collaborative-copilot/data/knowledge_base.json +58 -0
  36. data/examples/collaborative-copilot/data/linear_issues.json +83 -0
  37. data/examples/collaborative-copilot/data/stripe_billing.json +71 -0
  38. data/examples/collaborative-copilot/interactive.rb +90 -0
  39. data/examples/collaborative-copilot/tools/create_linear_ticket_tool.rb +58 -0
  40. data/examples/collaborative-copilot/tools/get_article_tool.rb +41 -0
  41. data/examples/collaborative-copilot/tools/get_contact_tool.rb +51 -0
  42. data/examples/collaborative-copilot/tools/get_conversation_tool.rb +53 -0
  43. data/examples/collaborative-copilot/tools/get_stripe_billing_tool.rb +44 -0
  44. data/examples/collaborative-copilot/tools/search_contacts_tool.rb +57 -0
  45. data/examples/collaborative-copilot/tools/search_conversations_tool.rb +54 -0
  46. data/examples/collaborative-copilot/tools/search_knowledge_base_tool.rb +55 -0
  47. data/examples/collaborative-copilot/tools/search_linear_issues_tool.rb +60 -0
  48. data/examples/isp-support/interactive.rb +43 -4
  49. data/lib/agents/agent.rb +34 -0
  50. data/lib/agents/agent_runner.rb +66 -1
  51. data/lib/agents/agent_tool.rb +113 -0
  52. data/lib/agents/callback_manager.rb +54 -0
  53. data/lib/agents/handoff.rb +8 -34
  54. data/lib/agents/message_extractor.rb +82 -0
  55. data/lib/agents/run_context.rb +5 -2
  56. data/lib/agents/runner.rb +16 -27
  57. data/lib/agents/tool_wrapper.rb +11 -1
  58. data/lib/agents/version.rb +1 -1
  59. data/lib/agents.rb +3 -0
  60. metadata +48 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 004f33c8652e5b8c4d8be7bd84e959c55f6926411d3cac8bd3b3d029b7b21690
4
- data.tar.gz: 6592c590cd91809ee47865a25adcf734370695bd4c697b1926aabc95c6e2d574
3
+ metadata.gz: b2d0dbff300d9f3bd08da74d39e1fbf2eecbfa0b293558af01b5ecfcc765d58c
4
+ data.tar.gz: 84a94feb4a5faea46ec658159f1266d315ba8175ad8b4c62915745c6e430c741
5
5
  SHA512:
6
- metadata.gz: 0baadd9d0771c8e2bdd345a0a8e00bc792c6a607ec78b8796a6718e4695dc5e92b2fdc2ec11b4384c77ad409af4660be5288b020c6404750a2db5a66d1cf094c
7
- data.tar.gz: de6edbb743e8b01634aaa12c656bc7cfa618de8086aa4e4e6add08683e8383b611856b4b9fa452c2e2e2bbd3efa2a74edefcc17af8188d2605babfc5067ecaf2
6
+ metadata.gz: 7bb4ab502f7c3362a3bc6f3549c30166f5e8e19d5f9aee7c3bf1fe17af334ae765122ecbff8c6b045aa28d5fac6e639dd5f56002ab7b24626ed0b2aae36eba48
7
+ data.tar.gz: 185d68208135a2f24b5ad8f5bbc075cdf06bcd54bad1b99f7910050224439bb8aacdec7a5c64f9768f7ec9cebdea9efa9e33734db4a650dd97bb16de901a00b5
@@ -0,0 +1,44 @@
1
+ ---
2
+ allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
3
+ description: Bump version, update changelog and commit changes
4
+ ---
5
+
6
+ You need to bump the version of the ruby gem and update the CHANGELOG. We need a #$ARGUMENTS version bump.
7
+
8
+ The types of version jumps are
9
+
10
+ - patch: Increment the third number in the version number.
11
+ - minor: Increment the second number in the version number.
12
+ - major: Increment the first number in the version number.
13
+
14
+ To bump up the version, follow these steps:
15
+
16
+ 1. Update the version number in the `lib/agents/version.rb` file.
17
+ 2. Run `bundle install` to ensure the lock file picks up the new version.
18
+
19
+ To update the changelog.
20
+
21
+ 1. Find the changelog file in `CHANGELOG.md`.
22
+ 2. Add a new section for the new version number.
23
+ 3. List the changes made in the new version.
24
+
25
+ We follow the `keepachangelog.com` guide for writing these changelogs and follow semantic versioning.
26
+
27
+ Here's what makes a good changelog.
28
+
29
+ **Guiding Principles**
30
+ - Changelogs are for humans, not machines.
31
+ - There should be an entry for every single version.
32
+ - The same types of changes should be grouped.
33
+ - Versions and sections should be linkable.
34
+ - The latest version comes first.
35
+
36
+ **Types of changes**
37
+ `Added` for new features.
38
+ `Changed` for changes in existing functionality.
39
+ `Deprecated` for soon-to-be removed features.
40
+ `Removed` for now removed features.
41
+ `Fixed` for any bug fixes.
42
+ `Security` in case of vulnerabilities
43
+
44
+ Once done, commit the changes with a message like "chore: bump version to <new-version>".
data/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.0] - 2025-07-08
9
+
10
+ ### Added
11
+ - Real-time callback system for monitoring agent execution
12
+ - `on_agent_thinking` callback for when agents are processing
13
+ - `on_tool_start` callback for when tools begin execution
14
+ - `on_tool_complete` callback for when tools finish execution
15
+ - `on_agent_handoff` callback for when control transfers between agents
16
+ - Enhanced conversation history with complete tool call audit trail
17
+ - Tool calls now captured in assistant messages with arguments
18
+ - Tool result messages linked to original calls via `tool_call_id`
19
+ - Full conversation replay capability for debugging
20
+ - CallbackManager for centralized event handling
21
+ - MessageExtractor service for clean conversation history processing
22
+
23
+ ### Changed
24
+ - RunContext now includes callback management capabilities
25
+ - Improved thread safety for callback execution
26
+ - Enhanced error handling for callback failures (non-blocking)
27
+
28
+ ## [0.1.3] - Previous Release
29
+
30
+ ### Added
31
+ - Multi-agent orchestration with seamless handoffs
32
+ - Thread-safe agent execution architecture
33
+ - Tool integration system
34
+ - Shared context management
35
+ - Provider support for OpenAI, Anthropic, and Gemini
data/CLAUDE.md CHANGED
@@ -9,6 +9,7 @@ This project is a Ruby SDK for building multi-agent AI workflows. It allows deve
9
9
  - **Multi-Agent Orchestration**: Defining and managing multiple AI agents with distinct roles.
10
10
  - **Seamless Handoffs**: Transferring conversations between agents without the user's knowledge.
11
11
  - **Tool Integration**: Allowing agents to use custom tools to interact with external systems.
12
+ - **Real-time Callbacks**: Event-driven system for monitoring agent execution, tool usage, and handoffs.
12
13
  - **Shared Context**: Maintaining state and conversation history across agent interactions with full persistence support.
13
14
  - **Thread-Safe Architecture**: Reusable agent runners that work safely across multiple threads.
14
15
  - **Provider Agnostic**: Supporting various LLM providers like OpenAI, Anthropic, and Gemini.
@@ -52,6 +53,7 @@ ruby examples/isp-support/interactive.rb
52
53
 
53
54
  This will start a command-line interface where you can interact with the multi-agent system. The example demonstrates:
54
55
  - Thread-safe agent runner creation
56
+ - Real-time callback system with UI feedback
55
57
  - Automatic agent selection based on conversation history
56
58
  - Context persistence that works across process boundaries
57
59
  - Seamless handoffs between triage, sales, and support agents
@@ -64,6 +66,7 @@ This will start a command-line interface where you can interact with the multi-a
64
66
  - **AgentRunner**: The thread-safe execution manager that coordinates multi-agent conversations and provides the main API.
65
67
  - **Runner**: Internal component that manages individual conversation turns (used by AgentRunner).
66
68
  - **Context**: A shared state object that stores conversation history and agent information, fully serializable for persistence.
69
+ - **Callbacks**: Event hooks for monitoring agent execution, including agent thinking, tool start/complete, and handoffs.
67
70
 
68
71
  ## Development Commands
69
72
 
@@ -111,10 +114,12 @@ ruby examples/isp-support/interactive.rb
111
114
  ### Core Components
112
115
 
113
116
  - **Agents::Agent**: Individual AI agents with specific roles, instructions, and tools
117
+ - **Agents::AgentRunner**: Thread-safe execution manager with callback support
114
118
  - **Agents::Runner**: Orchestrates multi-agent conversations with automatic handoffs
115
119
  - **Agents::Tool**: Base class for custom tools that agents can execute
116
120
  - **Agents::Context**: Shared state management across agent interactions
117
121
  - **Agents::Handoff**: Manages seamless transfers between agents
122
+ - **Agents::CallbackManager**: Centralized event handling for real-time monitoring
118
123
 
119
124
  ### Key Design Principles
120
125
 
@@ -129,17 +134,19 @@ ruby examples/isp-support/interactive.rb
129
134
 
130
135
  ```
131
136
  lib/agents/
132
- ├── agent.rb # Core agent definition and configuration
133
- ├── agent_runner.rb # Thread-safe execution manager (main API)
134
- ├── runner.rb # Internal execution engine for conversation turns
135
- ├── tool.rb # Base class for custom tools
136
- ├── handoff.rb # Agent handoff management
137
- ├── chat.rb # Chat message handling
138
- ├── result.rb # Result object for agent responses
139
- ├── run_context.rb # Execution context management
140
- ├── tool_context.rb # Tool execution context
141
- ├── tool_wrapper.rb # Thread-safe tool wrapping
142
- └── version.rb # Gem version
137
+ ├── agent.rb # Core agent definition and configuration
138
+ ├── agent_runner.rb # Thread-safe execution manager (main API)
139
+ ├── runner.rb # Internal execution engine for conversation turns
140
+ ├── tool.rb # Base class for custom tools
141
+ ├── handoff.rb # Agent handoff management
142
+ ├── chat.rb # Chat message handling
143
+ ├── result.rb # Result object for agent responses
144
+ ├── run_context.rb # Execution context management
145
+ ├── tool_context.rb # Tool execution context
146
+ ├── tool_wrapper.rb # Thread-safe tool wrapping
147
+ ├── callback_manager.rb # Centralized callback event handling
148
+ ├── message_extractor.rb # Conversation history processing
149
+ └── version.rb # Gem version
143
150
  ```
144
151
 
145
152
  ### Configuration
@@ -167,7 +174,13 @@ support = Agent.new(name: "Support", instructions: "Technical support...")
167
174
  triage.register_handoffs(billing, support)
168
175
 
169
176
  # Create thread-safe runner (first agent is default entry point)
170
- runner = Agents::Runner.with_agents(triage, billing, support)
177
+ runner = Agents::AgentRunner.with_agents(triage, billing, support)
178
+
179
+ # Add real-time callbacks for monitoring
180
+ runner.on_agent_thinking { |agent_name, input| puts "🧠 #{agent_name} is thinking..." }
181
+ runner.on_tool_start { |tool_name, args| puts "🔧 Using #{tool_name}..." }
182
+ runner.on_tool_complete { |tool_name, result| puts "✅ #{tool_name} completed" }
183
+ runner.on_agent_handoff { |from, to, reason| puts "🔄 Handoff: #{from} → #{to}" }
171
184
 
172
185
  # Use for conversations - automatically handles agent selection and persistence
173
186
  result = runner.run("I have a billing question")
@@ -184,10 +197,18 @@ When creating custom tools:
184
197
 
185
198
  ### Testing Strategy
186
199
 
200
+ The codebase follows comprehensive testing patterns with strong emphasis on thread safety and isolation, here's some points to note
201
+
187
202
  - SimpleCov tracks coverage with 50% minimum overall, 40% per file
188
- - WebMock is used for HTTP mocking in tests
189
- - RSpec is the testing framework with standard configuration
190
- - Tests are organized by component in `spec/agents/`
203
+ - RSpec testing framework with descriptive context blocks
204
+ - Tests organized by component in `spec/agents/` mirroring lib structure
205
+ - **Instance Doubles**: Extensive use of `instance_double` for clean dependency mocking, never use generic `double` or `stub`
206
+ - **WebMock**: HTTP call stubbing with network isolation (`WebMock.disable_net_connect!`)
207
+ - Unit tests for individual components
208
+ - Integration tests for complex workflows
209
+ - Thread-safety tests for concurrent scenarios
210
+ - Clear separation of setup, execution, and assertion phases
211
+ - Context description should always match /^when\b/, /^with\b/, or /^without\b/.
191
212
 
192
213
  ### Examples
193
214
 
@@ -195,3 +216,26 @@ The `examples/` directory contains complete working examples:
195
216
  - `isp-support/`: Multi-agent ISP customer support system
196
217
  - Shows hub-and-spoke architecture patterns
197
218
  - Demonstrates tool integration and handoff workflows
219
+ - Includes real-time callback implementation for UI feedback
220
+
221
+ ## Callback System
222
+
223
+ The SDK includes a comprehensive callback system for monitoring agent execution in real-time. This is particularly useful for:
224
+
225
+ - **UI Feedback**: Show users what's happening during agent execution
226
+ - **Debugging**: Track tool usage and agent handoffs
227
+ - **Analytics**: Monitor system performance and usage patterns
228
+ - **Rails Integration**: Stream updates via ActionCable
229
+
230
+ ### Available Callbacks
231
+
232
+ - `on_agent_thinking`: Triggered when an agent starts processing
233
+ - `on_tool_start`: Triggered when a tool begins execution
234
+ - `on_tool_complete`: Triggered when a tool finishes execution
235
+ - `on_agent_handoff`: Triggered when control transfers between agents
236
+
237
+ ### Callback Integration
238
+
239
+ Callbacks are thread-safe and non-blocking. If a callback raises an exception, it won't interrupt agent execution. The system uses a centralized CallbackManager for efficient event handling.
240
+
241
+ For detailed callback documentation, see `docs/concepts/callbacks.md`.
data/README.md CHANGED
@@ -2,14 +2,16 @@
2
2
  <br>
3
3
  <br>
4
4
  <p>
5
- <img src="./.github/ruby-agent.png" width="200px"/>
6
- <h1>Ruby Agents</h1>
5
+ <img src="./.github/ruby-agents.png" height="80px"/>
6
+ <h1>
7
+ AI Agents
8
+ </h1>
7
9
  </p>
8
10
  <br>
9
11
  <br>
10
12
  </div>
11
13
 
12
- A Ruby SDK for building multi-agent AI workflows with seamless handoffs, inspired by OpenAI's Agents SDK but built specifically for Ruby developers.
14
+ A delightful provider agnostic Ruby SDK for building multi-agent AI workflows with seamless handoffs tool calling, and shared context.
13
15
 
14
16
  ## ✨ Features
15
17
 
@@ -17,7 +19,6 @@ A Ruby SDK for building multi-agent AI workflows with seamless handoffs, inspire
17
19
  - **🔄 Seamless Handoffs**: Transparent agent-to-agent transfers (users never know!)
18
20
  - **🛠️ Tool Integration**: Agents can use custom tools and functions
19
21
  - **💾 Shared Context**: State management across agent interactions
20
- - **🚀 Simple API**: One method call handles everything including handoffs
21
22
  - **🔌 Provider Agnostic**: Works with OpenAI, Anthropic, and other LLM providers
22
23
 
23
24
  ## 🚀 Quick Start
@@ -66,32 +67,32 @@ triage = Agents::Agent.new(
66
67
  instructions: "Route customers to the right specialist"
67
68
  )
68
69
 
69
- faq = Agents::Agent.new(
70
- name: "FAQ Agent",
71
- instructions: "Answer frequently asked questions",
72
- tools: [FaqLookupTool.new]
70
+ sales = Agents::Agent.new(
71
+ name: "Sales Agent",
72
+ instructions: "Answer details about plans",
73
+ tools: [CreateLeadTool.new, CRMLookupTool.new]
73
74
  )
74
75
 
75
76
  support = Agents::Agent.new(
76
77
  name: "Support Agent",
77
- instructions: "Handle technical issues",
78
- tools: [TicketTool.new]
78
+ instructions: "Handle account realted and technical issues",
79
+ tools: [FaqLookupTool.new, TicketTool.new]
79
80
  )
80
81
 
81
82
  # Wire up handoff relationships - clean and simple!
82
- triage.register_handoffs(faq, support)
83
- faq.register_handoffs(triage) # Can route back to triage
84
- support.register_handoffs(triage) # Hub-and-spoke pattern
83
+ triage.register_handoffs(sales, support)
84
+ sales.register_handoffs(triage) # Can route back to triage
85
+ support.register_handoffs(triage) # Hub-and-spoke pattern
85
86
 
86
87
  # Create runner with all agents (triage is default entry point)
87
- runner = Agents::Runner.with_agents(triage, faq, support)
88
+ runner = Agents::Runner.with_agents(triage, sales, support)
88
89
 
89
90
  # Run conversations with automatic handoffs and persistence
90
- result = runner.run("How many seats are on the plane?")
91
- # User gets direct answer from FAQ agent without knowing about the handoff!
91
+ result = runner.run("Do you have special plans for businesses?")
92
+ # User gets direct answer from sales agent without knowing about the handoff!
92
93
 
93
94
  # Continue the conversation seamlessly
94
- result = runner.run("What about technical support?", context: result.context)
95
+ result = runner.run("What is the pricing for the premium fibre plan?", context: result.context)
95
96
  # Context automatically tracks conversation history and current agent
96
97
  ```
97
98
 
@@ -99,19 +100,15 @@ result = runner.run("What about technical support?", context: result.context)
99
100
 
100
101
  ### Core Components
101
102
 
102
- - **Agent**: Individual AI agents with specific roles and capabilities
103
- - **AgentRunner**: Thread-safe execution manager for multi-agent conversations
104
- - **Runner**: Internal orchestrator that handles conversation turns (used by AgentRunner)
105
- - **Context**: Shared state management with automatic persistence across agents
106
- - **Tools**: Custom functions that agents can use
107
- - **Handoffs**: Seamless transfers between specialized agents
103
+ - **Agent**: Individual AI assistants configured with specific instructions, tools, and handoff relationships. Agents are immutable and thread-safe.
104
+ - **AgentRunner**: Thread-safe execution manager that coordinates multi-agent conversations. Create once and reuse across multiple threads safely.
105
+ - **Runner**: Internal orchestrator that handles individual conversation turns and manages the execution loop (used internally by AgentRunner).
106
+ - **Context & State**: Shared conversation state that persists across agent handoffs. Fully serializable for database storage and session management.
107
+ - **Tools**: Custom functions that agents can execute to interact with external systems (APIs, databases, etc.).
108
+ - **Handoffs**: Automatic transfers between specialized agents based on conversation context, completely transparent to users.
108
109
 
109
110
  ### Agent Definition
110
111
 
111
- Agents can be created in two ways:
112
-
113
- #### Instance-based (Recommended for dynamic agents)
114
-
115
112
  ```ruby
116
113
  # Create agents as instances
117
114
  agent = Agents::Agent.new(
@@ -125,21 +122,6 @@ agent = Agents::Agent.new(
125
122
  agent.register_handoffs(technical_support, billing)
126
123
  ```
127
124
 
128
- #### Class-based (Coming soon)
129
-
130
- ```ruby
131
- class CustomerServiceAgent < Agents::Agent
132
- name "Customer Service"
133
- instructions <<~PROMPT
134
- You are a helpful customer service agent.
135
- Always be polite and professional.
136
- PROMPT
137
-
138
- model "gpt-4o"
139
- uses EmailTool, TicketTool
140
- end
141
- ```
142
-
143
125
  ### Custom Tools
144
126
 
145
127
  ```ruby
@@ -158,10 +140,8 @@ end
158
140
 
159
141
  ### Handoff Patterns
160
142
 
161
- #### Hub-and-Spoke Pattern (Recommended)
162
-
163
143
  ```ruby
164
- # Central triage agent routes to specialists
144
+ # Central triage agent routes to specialists (hub-and-spoke pattern)
165
145
  triage = Agents::Agent.new(name: "Triage")
166
146
  billing = Agents::Agent.new(name: "Billing")
167
147
  support = Agents::Agent.new(name: "Support")
@@ -174,18 +154,6 @@ billing.register_handoffs(triage)
174
154
  support.register_handoffs(triage)
175
155
  ```
176
156
 
177
- #### Circular Handoffs
178
-
179
- ```ruby
180
- # Agents can hand off to each other
181
- sales = Agents::Agent.new(name: "Sales")
182
- customer_info = Agents::Agent.new(name: "Customer Info")
183
-
184
- # Both agents can transfer to each other
185
- sales.register_handoffs(customer_info)
186
- customer_info.register_handoffs(sales)
187
- ```
188
-
189
157
  ### Context Management & Persistence
190
158
 
191
159
  ```ruby
@@ -201,7 +169,7 @@ puts context[:conversation_history]
201
169
  puts context[:current_agent] # Agent name (string), not object!
202
170
 
203
171
  # Serialize context for persistence (Rails, databases, etc.)
204
- json_context = JSON.dump(context) # ✅ Works! No object references
172
+ json_context = JSON.dump(context)
205
173
 
206
174
  # Later: restore and continue conversation
207
175
  restored_context = JSON.parse(json_context, symbolize_names: true)
@@ -211,53 +179,13 @@ result = runner.run("Actually, I need technical support too", context: restored_
211
179
 
212
180
  ## 📋 Examples
213
181
 
214
- ### ISP Customer Support
215
-
216
- See the complete ISP support example in `examples/isp-support/`:
182
+ Check out the `examples/` folder for complete working demos showcasing multi-agent workflows.
217
183
 
218
- ```ruby
219
- # Run the interactive demo
184
+ ```bash
185
+ # Run the ISP support demo
220
186
  ruby examples/isp-support/interactive.rb
221
187
  ```
222
188
 
223
- This showcases:
224
- - **Triage Agent**: Routes customers to appropriate specialists
225
- - **Customer Info Agent**: Handles account info and billing inquiries
226
- - **Sales Agent**: Manages new connections and upgrades
227
- - **Support Agent**: Provides technical troubleshooting
228
- - **Hub-and-Spoke Handoffs**: Clean architecture pattern
229
-
230
- ### Airline Customer Service
231
-
232
- See the airline booking example in `examples/booking/`:
233
-
234
- ```ruby
235
- # Run the interactive demo
236
- ruby examples/booking/interactive.rb
237
- ```
238
-
239
- This showcases:
240
- - **Triage Agent**: Routes questions to specialists
241
- - **FAQ Agent**: Answers questions about policies, seats, baggage
242
- - **Seat Booking Agent**: Handles seat changes and updates
243
- - **Seamless Handoffs**: Users never repeat their questions
244
-
245
- ### Sample Conversation
246
-
247
- ```
248
- You: How many seats are on the plane?
249
-
250
- Agent: The plane has a total of 120 seats, which includes 22 business
251
- class seats and 98 economy seats. Exit rows are located at rows 4 and
252
- 16, and rows 5-8 are designated as Economy Plus, offering extra legroom.
253
- ```
254
-
255
- Behind the scenes:
256
- 1. Triage Agent receives question
257
- 2. Automatically transfers to FAQ Agent
258
- 3. FAQ Agent processes original question and responds
259
- 4. User sees seamless experience!
260
-
261
189
  ## 🔧 Configuration
262
190
 
263
191
  ```ruby
@@ -298,8 +226,3 @@ This project is licensed under the MIT License - see the LICENSE file for detail
298
226
 
299
227
  - Inspired by [OpenAI's Agents SDK](https://github.com/openai/agents)
300
228
  - Built on top of [RubyLLM](https://rubyllm.com) for LLM integration
301
- - Thanks to the Ruby community for continuous inspiration
302
-
303
- ---
304
-
305
- **Built with ❤️ by the Chatwoot Team**
data/docs/Gemfile ADDED
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ source "https://rubygems.org"
4
+
5
+ gem "jekyll"
6
+ gem "just-the-docs"
7
+ gem "webrick"
8
+
9
+ # GitHub Pages plugins
10
+ group :jekyll_plugins do
11
+ gem "jekyll-remote-theme"
12
+ gem "jekyll-seo-tag"
13
+ gem "jekyll-sitemap"
14
+ end
data/docs/Gemfile.lock ADDED
@@ -0,0 +1,183 @@
1
+ GEM
2
+ remote: https://rubygems.org/
3
+ specs:
4
+ addressable (2.8.7)
5
+ public_suffix (>= 2.0.2, < 7.0)
6
+ base64 (0.3.0)
7
+ bigdecimal (3.2.2)
8
+ colorator (1.1.0)
9
+ concurrent-ruby (1.3.5)
10
+ csv (3.3.5)
11
+ em-websocket (0.5.3)
12
+ eventmachine (>= 0.12.9)
13
+ http_parser.rb (~> 0)
14
+ eventmachine (1.2.7)
15
+ ffi (1.17.2)
16
+ ffi (1.17.2-aarch64-linux-gnu)
17
+ ffi (1.17.2-aarch64-linux-musl)
18
+ ffi (1.17.2-arm-linux-gnu)
19
+ ffi (1.17.2-arm-linux-musl)
20
+ ffi (1.17.2-arm64-darwin)
21
+ ffi (1.17.2-x86-linux-gnu)
22
+ ffi (1.17.2-x86-linux-musl)
23
+ ffi (1.17.2-x86_64-darwin)
24
+ ffi (1.17.2-x86_64-linux-gnu)
25
+ ffi (1.17.2-x86_64-linux-musl)
26
+ forwardable-extended (2.6.0)
27
+ google-protobuf (4.31.1)
28
+ bigdecimal
29
+ rake (>= 13)
30
+ google-protobuf (4.31.1-aarch64-linux-gnu)
31
+ bigdecimal
32
+ rake (>= 13)
33
+ google-protobuf (4.31.1-aarch64-linux-musl)
34
+ bigdecimal
35
+ rake (>= 13)
36
+ google-protobuf (4.31.1-arm64-darwin)
37
+ bigdecimal
38
+ rake (>= 13)
39
+ google-protobuf (4.31.1-x86-linux-gnu)
40
+ bigdecimal
41
+ rake (>= 13)
42
+ google-protobuf (4.31.1-x86-linux-musl)
43
+ bigdecimal
44
+ rake (>= 13)
45
+ google-protobuf (4.31.1-x86_64-darwin)
46
+ bigdecimal
47
+ rake (>= 13)
48
+ google-protobuf (4.31.1-x86_64-linux-gnu)
49
+ bigdecimal
50
+ rake (>= 13)
51
+ google-protobuf (4.31.1-x86_64-linux-musl)
52
+ bigdecimal
53
+ rake (>= 13)
54
+ http_parser.rb (0.8.0)
55
+ i18n (1.14.7)
56
+ concurrent-ruby (~> 1.0)
57
+ jekyll (4.4.1)
58
+ addressable (~> 2.4)
59
+ base64 (~> 0.2)
60
+ colorator (~> 1.0)
61
+ csv (~> 3.0)
62
+ em-websocket (~> 0.5)
63
+ i18n (~> 1.0)
64
+ jekyll-sass-converter (>= 2.0, < 4.0)
65
+ jekyll-watch (~> 2.0)
66
+ json (~> 2.6)
67
+ kramdown (~> 2.3, >= 2.3.1)
68
+ kramdown-parser-gfm (~> 1.0)
69
+ liquid (~> 4.0)
70
+ mercenary (~> 0.3, >= 0.3.6)
71
+ pathutil (~> 0.9)
72
+ rouge (>= 3.0, < 5.0)
73
+ safe_yaml (~> 1.0)
74
+ terminal-table (>= 1.8, < 4.0)
75
+ webrick (~> 1.7)
76
+ jekyll-include-cache (0.2.1)
77
+ jekyll (>= 3.7, < 5.0)
78
+ jekyll-remote-theme (0.4.3)
79
+ addressable (~> 2.0)
80
+ jekyll (>= 3.5, < 5.0)
81
+ jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
82
+ rubyzip (>= 1.3.0, < 3.0)
83
+ jekyll-sass-converter (3.0.0)
84
+ sass-embedded (~> 1.54)
85
+ jekyll-seo-tag (2.8.0)
86
+ jekyll (>= 3.8, < 5.0)
87
+ jekyll-sitemap (1.4.0)
88
+ jekyll (>= 3.7, < 5.0)
89
+ jekyll-watch (2.2.1)
90
+ listen (~> 3.0)
91
+ json (2.12.2)
92
+ just-the-docs (0.10.1)
93
+ jekyll (>= 3.8.5)
94
+ jekyll-include-cache
95
+ jekyll-seo-tag (>= 2.0)
96
+ rake (>= 12.3.1)
97
+ kramdown (2.5.1)
98
+ rexml (>= 3.3.9)
99
+ kramdown-parser-gfm (1.1.0)
100
+ kramdown (~> 2.0)
101
+ liquid (4.0.4)
102
+ listen (3.9.0)
103
+ rb-fsevent (~> 0.10, >= 0.10.3)
104
+ rb-inotify (~> 0.9, >= 0.9.10)
105
+ mercenary (0.4.0)
106
+ pathutil (0.16.2)
107
+ forwardable-extended (~> 2.6)
108
+ public_suffix (6.0.2)
109
+ rake (13.3.0)
110
+ rb-fsevent (0.11.2)
111
+ rb-inotify (0.11.1)
112
+ ffi (~> 1.0)
113
+ rexml (3.4.1)
114
+ rouge (4.5.2)
115
+ rubyzip (2.4.1)
116
+ safe_yaml (1.0.5)
117
+ sass-embedded (1.89.2)
118
+ google-protobuf (~> 4.31)
119
+ rake (>= 13)
120
+ sass-embedded (1.89.2-aarch64-linux-android)
121
+ google-protobuf (~> 4.31)
122
+ sass-embedded (1.89.2-aarch64-linux-gnu)
123
+ google-protobuf (~> 4.31)
124
+ sass-embedded (1.89.2-aarch64-linux-musl)
125
+ google-protobuf (~> 4.31)
126
+ sass-embedded (1.89.2-arm-linux-androideabi)
127
+ google-protobuf (~> 4.31)
128
+ sass-embedded (1.89.2-arm-linux-gnueabihf)
129
+ google-protobuf (~> 4.31)
130
+ sass-embedded (1.89.2-arm-linux-musleabihf)
131
+ google-protobuf (~> 4.31)
132
+ sass-embedded (1.89.2-arm64-darwin)
133
+ google-protobuf (~> 4.31)
134
+ sass-embedded (1.89.2-riscv64-linux-android)
135
+ google-protobuf (~> 4.31)
136
+ sass-embedded (1.89.2-riscv64-linux-gnu)
137
+ google-protobuf (~> 4.31)
138
+ sass-embedded (1.89.2-riscv64-linux-musl)
139
+ google-protobuf (~> 4.31)
140
+ sass-embedded (1.89.2-x86_64-darwin)
141
+ google-protobuf (~> 4.31)
142
+ sass-embedded (1.89.2-x86_64-linux-android)
143
+ google-protobuf (~> 4.31)
144
+ sass-embedded (1.89.2-x86_64-linux-gnu)
145
+ google-protobuf (~> 4.31)
146
+ sass-embedded (1.89.2-x86_64-linux-musl)
147
+ google-protobuf (~> 4.31)
148
+ terminal-table (3.0.2)
149
+ unicode-display_width (>= 1.1.1, < 3)
150
+ unicode-display_width (2.6.0)
151
+ webrick (1.9.1)
152
+
153
+ PLATFORMS
154
+ aarch64-linux-android
155
+ aarch64-linux-gnu
156
+ aarch64-linux-musl
157
+ arm-linux-androideabi
158
+ arm-linux-gnu
159
+ arm-linux-gnueabihf
160
+ arm-linux-musl
161
+ arm-linux-musleabihf
162
+ arm64-darwin
163
+ riscv64-linux-android
164
+ riscv64-linux-gnu
165
+ riscv64-linux-musl
166
+ ruby
167
+ x86-linux-gnu
168
+ x86-linux-musl
169
+ x86_64-darwin
170
+ x86_64-linux-android
171
+ x86_64-linux-gnu
172
+ x86_64-linux-musl
173
+
174
+ DEPENDENCIES
175
+ jekyll
176
+ jekyll-remote-theme
177
+ jekyll-seo-tag
178
+ jekyll-sitemap
179
+ just-the-docs
180
+ webrick
181
+
182
+ BUNDLED WITH
183
+ 2.6.9