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.
- checksums.yaml +4 -4
- data/.claude/commands/bump-version.md +44 -0
- data/CHANGELOG.md +35 -0
- data/CLAUDE.md +59 -15
- data/README.md +29 -106
- data/docs/Gemfile +14 -0
- data/docs/Gemfile.lock +183 -0
- data/docs/_config.yml +53 -0
- data/docs/_sass/color_schemes/ruby.scss +72 -0
- data/docs/_sass/custom/custom.scss +93 -0
- data/docs/architecture.md +353 -0
- data/docs/assets/fonts/InterVariable.woff2 +0 -0
- data/docs/concepts/agent-tool.md +166 -0
- data/docs/concepts/agents.md +43 -0
- data/docs/concepts/callbacks.md +42 -0
- data/docs/concepts/context.md +110 -0
- data/docs/concepts/handoffs.md +81 -0
- data/docs/concepts/runner.md +87 -0
- data/docs/concepts/tools.md +62 -0
- data/docs/concepts.md +22 -0
- data/docs/guides/agent-as-tool-pattern.md +242 -0
- data/docs/guides/multi-agent-systems.md +261 -0
- data/docs/guides/rails-integration.md +440 -0
- data/docs/guides/state-persistence.md +451 -0
- data/docs/guides.md +18 -0
- data/docs/index.md +97 -0
- data/examples/collaborative-copilot/README.md +169 -0
- data/examples/collaborative-copilot/agents/analysis_agent.rb +48 -0
- data/examples/collaborative-copilot/agents/answer_suggestion_agent.rb +50 -0
- data/examples/collaborative-copilot/agents/copilot_orchestrator.rb +85 -0
- data/examples/collaborative-copilot/agents/integrations_agent.rb +58 -0
- data/examples/collaborative-copilot/agents/research_agent.rb +52 -0
- data/examples/collaborative-copilot/data/contacts.json +47 -0
- data/examples/collaborative-copilot/data/conversations.json +170 -0
- data/examples/collaborative-copilot/data/knowledge_base.json +58 -0
- data/examples/collaborative-copilot/data/linear_issues.json +83 -0
- data/examples/collaborative-copilot/data/stripe_billing.json +71 -0
- data/examples/collaborative-copilot/interactive.rb +90 -0
- data/examples/collaborative-copilot/tools/create_linear_ticket_tool.rb +58 -0
- data/examples/collaborative-copilot/tools/get_article_tool.rb +41 -0
- data/examples/collaborative-copilot/tools/get_contact_tool.rb +51 -0
- data/examples/collaborative-copilot/tools/get_conversation_tool.rb +53 -0
- data/examples/collaborative-copilot/tools/get_stripe_billing_tool.rb +44 -0
- data/examples/collaborative-copilot/tools/search_contacts_tool.rb +57 -0
- data/examples/collaborative-copilot/tools/search_conversations_tool.rb +54 -0
- data/examples/collaborative-copilot/tools/search_knowledge_base_tool.rb +55 -0
- data/examples/collaborative-copilot/tools/search_linear_issues_tool.rb +60 -0
- data/examples/isp-support/interactive.rb +43 -4
- data/lib/agents/agent.rb +34 -0
- data/lib/agents/agent_runner.rb +66 -1
- data/lib/agents/agent_tool.rb +113 -0
- data/lib/agents/callback_manager.rb +54 -0
- data/lib/agents/handoff.rb +8 -34
- data/lib/agents/message_extractor.rb +82 -0
- data/lib/agents/run_context.rb +5 -2
- data/lib/agents/runner.rb +16 -27
- data/lib/agents/tool_wrapper.rb +11 -1
- data/lib/agents/version.rb +1 -1
- data/lib/agents.rb +3 -0
- metadata +48 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: b2d0dbff300d9f3bd08da74d39e1fbf2eecbfa0b293558af01b5ecfcc765d58c
|
4
|
+
data.tar.gz: 84a94feb4a5faea46ec658159f1266d315ba8175ad8b4c62915745c6e430c741
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
133
|
-
├── agent_runner.rb
|
134
|
-
├── runner.rb
|
135
|
-
├── tool.rb
|
136
|
-
├── handoff.rb
|
137
|
-
├── chat.rb
|
138
|
-
├── result.rb
|
139
|
-
├── run_context.rb
|
140
|
-
├── tool_context.rb
|
141
|
-
├── tool_wrapper.rb
|
142
|
-
|
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::
|
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
|
-
-
|
189
|
-
-
|
190
|
-
-
|
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-
|
6
|
-
<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
|
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
|
-
|
70
|
-
name: "
|
71
|
-
instructions: "Answer
|
72
|
-
tools: [
|
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(
|
83
|
-
|
84
|
-
support.register_handoffs(triage)
|
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,
|
88
|
+
runner = Agents::Runner.with_agents(triage, sales, support)
|
88
89
|
|
89
90
|
# Run conversations with automatic handoffs and persistence
|
90
|
-
result = runner.run("
|
91
|
-
# User gets direct answer from
|
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
|
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
|
103
|
-
- **AgentRunner**: Thread-safe execution manager
|
104
|
-
- **Runner**: Internal orchestrator that handles conversation turns (used by AgentRunner)
|
105
|
-
- **Context**: Shared state
|
106
|
-
- **Tools**: Custom functions that agents can
|
107
|
-
- **Handoffs**:
|
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)
|
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
|
-
|
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
|
-
```
|
219
|
-
# Run the
|
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
|