rcrewai 0.10.0 → 0.11.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/CHANGELOG.md +24 -0
- data/README.md +133 -23
- data/ROADMAP.md +1 -1
- data/docs/api/agent.md +5 -2
- data/docs/api/configuration.md +36 -41
- data/docs/api/crew.md +34 -48
- data/docs/api/index.md +7 -0
- data/docs/api/task.md +10 -91
- data/docs/api/tools.md +19 -0
- data/docs/examples/api-integration.md +4 -4
- data/docs/examples/async-execution.md +4 -4
- data/docs/examples/code-review-crew.md +1 -1
- data/docs/examples/content-marketing-pipeline.md +3 -3
- data/docs/examples/custom-tools.md +8 -8
- data/docs/examples/customer-support.md +5 -5
- data/docs/examples/data-analysis-team.md +4 -4
- data/docs/examples/database-operations.md +4 -4
- data/docs/examples/ecommerce-operations.md +4 -4
- data/docs/examples/financial-analysis.md +3 -3
- data/docs/examples/hierarchical-crew.md +3 -2
- data/docs/examples/production-ready-crew.md +16 -10
- data/docs/examples/research-development.md +5 -5
- data/docs/examples/simple-research-crew.md +2 -2
- data/docs/examples/social-media.md +4 -4
- data/docs/examples/task-automation.md +2 -2
- data/docs/examples/tool-composition.md +42 -27
- data/docs/examples/web-scraping.md +6 -6
- data/docs/index.md +61 -44
- data/docs/tutorials/advanced-agents.md +194 -917
- data/docs/tutorials/agent-options.md +1 -1
- data/docs/tutorials/checkpointing.md +65 -0
- data/docs/tutorials/concurrency.md +57 -0
- data/docs/tutorials/custom-tools.md +198 -1143
- data/docs/tutorials/deployment.md +156 -155
- data/docs/tutorials/getting-started.md +69 -81
- data/docs/tutorials/index.md +19 -0
- data/docs/tutorials/interceptors-and-events.md +84 -0
- data/docs/tutorials/live-streaming.md +52 -0
- data/docs/tutorials/multiple-crews.md +70 -51
- data/docs/tutorials/providers.md +115 -0
- data/docs/upgrading-to-0.11.md +55 -0
- data/lib/rcrewai/agent.rb +0 -2
- data/lib/rcrewai/configuration.rb +64 -29
- data/lib/rcrewai/context_window.rb +12 -2
- data/lib/rcrewai/llm_clients/anthropic.rb +60 -9
- data/lib/rcrewai/llm_clients/base.rb +7 -0
- data/lib/rcrewai/llm_clients/bedrock.rb +29 -2
- data/lib/rcrewai/llm_clients/google.rb +36 -4
- data/lib/rcrewai/llm_clients/ollama.rb +17 -3
- data/lib/rcrewai/llm_clients/openai.rb +14 -1
- data/lib/rcrewai/llm_clients/openai_responses.rb +21 -2
- data/lib/rcrewai/pricing.rb +13 -3
- data/lib/rcrewai/tool_runner.rb +5 -1
- data/lib/rcrewai/version.rb +1 -1
- metadata +7 -1
|
@@ -1,1242 +1,297 @@
|
|
|
1
1
|
---
|
|
2
2
|
layout: tutorial
|
|
3
3
|
title: Custom Tools Development
|
|
4
|
-
description:
|
|
4
|
+
description: Build custom tools with the tool DSL, so agents can call your code through native function calling
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Custom Tools Development
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
A tool is a Ruby class the model can call. You declare its name, description, and
|
|
10
|
+
parameters, and write `execute`. RCrewAI turns the declaration into a JSON schema
|
|
11
|
+
for the provider, coerces the model's arguments to the declared types, and sends
|
|
12
|
+
the return value back to the model.
|
|
10
13
|
|
|
11
14
|
## Table of Contents
|
|
12
|
-
1. [
|
|
13
|
-
2. [
|
|
14
|
-
3. [
|
|
15
|
-
4. [
|
|
16
|
-
5. [
|
|
17
|
-
6. [
|
|
18
|
-
7. [
|
|
19
|
-
8. [
|
|
15
|
+
1. [Your First Tool](#your-first-tool)
|
|
16
|
+
2. [Declaring Parameters](#declaring-parameters)
|
|
17
|
+
3. [Configuring a Tool](#configuring-a-tool)
|
|
18
|
+
4. [Calling an API](#calling-an-api)
|
|
19
|
+
5. [Errors](#errors)
|
|
20
|
+
6. [Thread Safety](#thread-safety)
|
|
21
|
+
7. [Security](#security)
|
|
22
|
+
8. [Testing Tools](#testing-tools)
|
|
23
|
+
9. [Tools Without the DSL](#tools-without-the-dsl)
|
|
24
|
+
10. [Best Practices](#best-practices)
|
|
25
|
+
|
|
26
|
+
## Your First Tool
|
|
20
27
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
### Tool Base Class
|
|
28
|
+
```ruby
|
|
29
|
+
require 'rcrewai'
|
|
24
30
|
|
|
25
|
-
|
|
31
|
+
class WordCount < RCrewAI::Tools::Base
|
|
32
|
+
tool_name 'word_count'
|
|
33
|
+
description 'Count the words in a piece of text'
|
|
34
|
+
param :text, type: :string, required: true, description: 'The text to count'
|
|
26
35
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
module Tools
|
|
30
|
-
class Base
|
|
31
|
-
attr_reader :name, :description
|
|
32
|
-
|
|
33
|
-
def initialize(**options)
|
|
34
|
-
@name = self.class.name.split('::').last.downcase
|
|
35
|
-
@description = "Base tool description"
|
|
36
|
-
@options = options
|
|
37
|
-
@logger = Logger.new($stdout)
|
|
38
|
-
end
|
|
39
|
-
|
|
40
|
-
def execute(**params)
|
|
41
|
-
raise NotImplementedError, "Subclasses must implement execute method"
|
|
42
|
-
end
|
|
43
|
-
|
|
44
|
-
def validate_params!(params, required: [], optional: [])
|
|
45
|
-
# Built-in parameter validation
|
|
46
|
-
required.each do |param|
|
|
47
|
-
unless params.key?(param)
|
|
48
|
-
raise ToolError, "Missing required parameter: #{param}"
|
|
49
|
-
end
|
|
50
|
-
end
|
|
51
|
-
|
|
52
|
-
# Check for unknown parameters
|
|
53
|
-
all_params = required + optional
|
|
54
|
-
params.keys.each do |key|
|
|
55
|
-
unless all_params.include?(key)
|
|
56
|
-
raise ToolError, "Unknown parameter: #{key}"
|
|
57
|
-
end
|
|
58
|
-
end
|
|
59
|
-
end
|
|
60
|
-
end
|
|
36
|
+
def execute(text:)
|
|
37
|
+
text.split.length.to_s
|
|
61
38
|
end
|
|
62
39
|
end
|
|
63
|
-
```
|
|
64
40
|
|
|
65
|
-
|
|
41
|
+
agent = RCrewAI::Agent.new(
|
|
42
|
+
name: 'editor',
|
|
43
|
+
role: 'Editor',
|
|
44
|
+
goal: 'Keep articles within their word limits',
|
|
45
|
+
tools: [WordCount.new]
|
|
46
|
+
)
|
|
47
|
+
```
|
|
66
48
|
|
|
67
|
-
|
|
68
|
-
2. **Validation**: Parameters are validated before execution
|
|
69
|
-
3. **Execution**: Tool performs its function
|
|
70
|
-
4. **Result Formatting**: Output is formatted for agent consumption
|
|
71
|
-
5. **Error Handling**: Exceptions are caught and handled
|
|
49
|
+
Three things matter here:
|
|
72
50
|
|
|
73
|
-
|
|
51
|
+
- **The description is for the model.** It decides whether the tool gets called, so
|
|
52
|
+
say what the tool does and when to use it.
|
|
53
|
+
- **`execute` receives keyword arguments**, one for each declared parameter.
|
|
54
|
+
- **Return a string.** Other values are converted with `to_s` before the model sees them.
|
|
74
55
|
|
|
75
|
-
|
|
56
|
+
You can call a tool directly to try it:
|
|
76
57
|
|
|
77
58
|
```ruby
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
@description = 'Performs mathematical calculations'
|
|
83
|
-
@precision = options[:precision] || 2
|
|
84
|
-
end
|
|
85
|
-
|
|
86
|
-
def execute(**params)
|
|
87
|
-
validate_params!(params, required: [:operation, :operands])
|
|
88
|
-
|
|
89
|
-
operation = params[:operation].to_s.downcase
|
|
90
|
-
operands = params[:operands]
|
|
91
|
-
|
|
92
|
-
# Validate operands
|
|
93
|
-
unless operands.is_a?(Array) && operands.all? { |o| o.is_a?(Numeric) }
|
|
94
|
-
raise ToolError, "Operands must be an array of numbers"
|
|
95
|
-
end
|
|
96
|
-
|
|
97
|
-
result = case operation
|
|
98
|
-
when 'add', '+'
|
|
99
|
-
operands.sum
|
|
100
|
-
when 'subtract', '-'
|
|
101
|
-
operands.reduce(&:-)
|
|
102
|
-
when 'multiply', '*'
|
|
103
|
-
operands.reduce(&:*)
|
|
104
|
-
when 'divide', '/'
|
|
105
|
-
divide_with_check(operands)
|
|
106
|
-
when 'power', '^'
|
|
107
|
-
operands[0] ** operands[1]
|
|
108
|
-
when 'sqrt'
|
|
109
|
-
Math.sqrt(operands[0])
|
|
110
|
-
when 'average'
|
|
111
|
-
operands.sum.to_f / operands.length
|
|
112
|
-
else
|
|
113
|
-
raise ToolError, "Unknown operation: #{operation}"
|
|
114
|
-
end
|
|
115
|
-
|
|
116
|
-
format_result(result)
|
|
117
|
-
end
|
|
118
|
-
|
|
119
|
-
private
|
|
120
|
-
|
|
121
|
-
def divide_with_check(operands)
|
|
122
|
-
if operands[1..-1].any? { |o| o == 0 }
|
|
123
|
-
raise ToolError, "Division by zero"
|
|
124
|
-
end
|
|
125
|
-
operands.reduce(&:/)
|
|
126
|
-
end
|
|
127
|
-
|
|
128
|
-
def format_result(result)
|
|
129
|
-
if result.is_a?(Float)
|
|
130
|
-
"Result: #{result.round(@precision)}"
|
|
131
|
-
else
|
|
132
|
-
"Result: #{result}"
|
|
133
|
-
end
|
|
134
|
-
end
|
|
135
|
-
end
|
|
136
|
-
|
|
137
|
-
# Usage with an agent
|
|
138
|
-
calculator = CalculatorTool.new(precision: 4)
|
|
139
|
-
|
|
140
|
-
agent = RCrewAI::Agent.new(
|
|
141
|
-
name: "math_agent",
|
|
142
|
-
role: "Mathematics Specialist",
|
|
143
|
-
goal: "Solve mathematical problems",
|
|
144
|
-
tools: [calculator]
|
|
145
|
-
)
|
|
146
|
-
|
|
147
|
-
# Agent can now use: USE_TOOL[calculator](operation=multiply, operands=[5, 3, 2])
|
|
59
|
+
WordCount.new.execute(text: 'one two three') # => "3"
|
|
60
|
+
WordCount.json_schema
|
|
61
|
+
# => { name: "word_count", description: "Count the words in a piece of text",
|
|
62
|
+
# parameters: { type: "object", properties: { text: { ... } }, required: ["text"] } }
|
|
148
63
|
```
|
|
149
64
|
|
|
150
|
-
|
|
65
|
+
## Declaring Parameters
|
|
151
66
|
|
|
152
67
|
```ruby
|
|
153
|
-
|
|
154
|
-
|
|
68
|
+
class SearchOrders < RCrewAI::Tools::Base
|
|
69
|
+
tool_name 'search_orders'
|
|
70
|
+
description 'Search customer orders'
|
|
155
71
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
def execute(**params)
|
|
167
|
-
validate_params!(params, required: [:location], optional: [:forecast])
|
|
168
|
-
|
|
169
|
-
location = params[:location]
|
|
170
|
-
forecast = params[:forecast] || false
|
|
171
|
-
|
|
172
|
-
begin
|
|
173
|
-
if forecast
|
|
174
|
-
get_forecast(location)
|
|
175
|
-
else
|
|
176
|
-
get_current_weather(location)
|
|
177
|
-
end
|
|
178
|
-
rescue => e
|
|
179
|
-
"Weather service error: #{e.message}"
|
|
180
|
-
end
|
|
181
|
-
end
|
|
182
|
-
|
|
183
|
-
private
|
|
184
|
-
|
|
185
|
-
def get_current_weather(location)
|
|
186
|
-
endpoint = "#{@base_url}/weather"
|
|
187
|
-
params = {
|
|
188
|
-
q: location,
|
|
189
|
-
appid: @api_key,
|
|
190
|
-
units: @units
|
|
191
|
-
}
|
|
192
|
-
|
|
193
|
-
response = make_api_request(endpoint, params)
|
|
194
|
-
format_weather_response(response)
|
|
195
|
-
end
|
|
196
|
-
|
|
197
|
-
def get_forecast(location)
|
|
198
|
-
endpoint = "#{@base_url}/forecast"
|
|
199
|
-
params = {
|
|
200
|
-
q: location,
|
|
201
|
-
appid: @api_key,
|
|
202
|
-
units: @units,
|
|
203
|
-
cnt: 5 # 5 day forecast
|
|
204
|
-
}
|
|
205
|
-
|
|
206
|
-
response = make_api_request(endpoint, params)
|
|
207
|
-
format_forecast_response(response)
|
|
208
|
-
end
|
|
209
|
-
|
|
210
|
-
def make_api_request(endpoint, params)
|
|
211
|
-
uri = URI(endpoint)
|
|
212
|
-
uri.query = URI.encode_www_form(params)
|
|
213
|
-
|
|
214
|
-
http = Net::HTTP.new(uri.host, uri.port)
|
|
215
|
-
http.use_ssl = true
|
|
216
|
-
http.read_timeout = 10
|
|
217
|
-
|
|
218
|
-
request = Net::HTTP::Get.new(uri)
|
|
219
|
-
response = http.request(request)
|
|
220
|
-
|
|
221
|
-
if response.code == '200'
|
|
222
|
-
JSON.parse(response.body)
|
|
223
|
-
else
|
|
224
|
-
raise "API error: #{response.code} - #{response.body}"
|
|
225
|
-
end
|
|
226
|
-
end
|
|
227
|
-
|
|
228
|
-
def format_weather_response(data)
|
|
229
|
-
temp = data['main']['temp']
|
|
230
|
-
feels_like = data['main']['feels_like']
|
|
231
|
-
description = data['weather'][0]['description']
|
|
232
|
-
humidity = data['main']['humidity']
|
|
233
|
-
wind_speed = data['wind']['speed']
|
|
234
|
-
|
|
235
|
-
unit_label = @units == 'metric' ? '°C' : '°F'
|
|
236
|
-
|
|
237
|
-
<<~WEATHER
|
|
238
|
-
Weather in #{data['name']}, #{data['sys']['country']}:
|
|
239
|
-
Temperature: #{temp}#{unit_label} (feels like #{feels_like}#{unit_label})
|
|
240
|
-
Conditions: #{description}
|
|
241
|
-
Humidity: #{humidity}%
|
|
242
|
-
Wind Speed: #{wind_speed} #{@units == 'metric' ? 'm/s' : 'mph'}
|
|
243
|
-
WEATHER
|
|
244
|
-
end
|
|
245
|
-
|
|
246
|
-
def format_forecast_response(data)
|
|
247
|
-
forecasts = data['list'].map do |item|
|
|
248
|
-
time = Time.at(item['dt']).strftime('%Y-%m-%d %H:%M')
|
|
249
|
-
temp = item['main']['temp']
|
|
250
|
-
desc = item['weather'][0]['description']
|
|
251
|
-
"#{time}: #{temp}°, #{desc}"
|
|
252
|
-
end
|
|
253
|
-
|
|
254
|
-
"5-Day Forecast for #{data['city']['name']}:\n" + forecasts.join("\n")
|
|
72
|
+
param :query, type: :string, required: true, description: 'Customer name or order number'
|
|
73
|
+
param :limit, type: :integer, default: 10, description: 'Maximum results to return'
|
|
74
|
+
param :status, type: :enum, values: %w[open shipped cancelled]
|
|
75
|
+
param :tags, type: :array, items: { type: :string }
|
|
76
|
+
param :open_only, type: :boolean
|
|
77
|
+
param :filters, type: :object, properties: { min_total: { type: 'number' } }
|
|
78
|
+
|
|
79
|
+
def execute(query:, limit: 10, status: nil, tags: [], open_only: false, filters: {})
|
|
80
|
+
"Found 0 orders for #{query} (limit #{limit}, status #{status.inspect})"
|
|
255
81
|
end
|
|
256
82
|
end
|
|
257
83
|
```
|
|
258
84
|
|
|
259
|
-
|
|
85
|
+
The supported types are `:string`, `:integer`, `:number`, `:boolean`, `:array`,
|
|
86
|
+
`:object`, and `:enum`.
|
|
260
87
|
|
|
261
|
-
|
|
88
|
+
**`default:` only informs the model.** It appears in the schema, but RCrewAI doesn't
|
|
89
|
+
fill it in when the model leaves the argument out, so also give the keyword a default
|
|
90
|
+
in `execute`, as `limit: 10` does above. Every parameter that isn't `required: true`
|
|
91
|
+
needs one.
|
|
262
92
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
@memory_store = {}
|
|
270
|
-
@max_entries = options[:max_entries] || 100
|
|
271
|
-
@ttl = options[:ttl] || 3600 # 1 hour default
|
|
272
|
-
end
|
|
273
|
-
|
|
274
|
-
def execute(**params)
|
|
275
|
-
validate_params!(params,
|
|
276
|
-
required: [:action],
|
|
277
|
-
optional: [:key, :value, :pattern]
|
|
278
|
-
)
|
|
279
|
-
|
|
280
|
-
action = params[:action].to_sym
|
|
281
|
-
|
|
282
|
-
case action
|
|
283
|
-
when :store
|
|
284
|
-
store_value(params[:key], params[:value])
|
|
285
|
-
when :retrieve
|
|
286
|
-
retrieve_value(params[:key])
|
|
287
|
-
when :delete
|
|
288
|
-
delete_value(params[:key])
|
|
289
|
-
when :list
|
|
290
|
-
list_keys(params[:pattern])
|
|
291
|
-
when :clear
|
|
292
|
-
clear_all
|
|
293
|
-
else
|
|
294
|
-
raise ToolError, "Unknown action: #{action}"
|
|
295
|
-
end
|
|
296
|
-
end
|
|
297
|
-
|
|
298
|
-
private
|
|
299
|
-
|
|
300
|
-
def store_value(key, value)
|
|
301
|
-
raise ToolError, "Key and value required for store action" unless key && value
|
|
302
|
-
|
|
303
|
-
# Enforce size limit
|
|
304
|
-
if @memory_store.size >= @max_entries && !@memory_store.key?(key)
|
|
305
|
-
evict_oldest
|
|
306
|
-
end
|
|
307
|
-
|
|
308
|
-
@memory_store[key] = {
|
|
309
|
-
value: value,
|
|
310
|
-
timestamp: Time.now,
|
|
311
|
-
access_count: 0
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
"Stored: #{key} = #{value}"
|
|
315
|
-
end
|
|
316
|
-
|
|
317
|
-
def retrieve_value(key)
|
|
318
|
-
raise ToolError, "Key required for retrieve action" unless key
|
|
319
|
-
|
|
320
|
-
if entry = @memory_store[key]
|
|
321
|
-
# Check TTL
|
|
322
|
-
if Time.now - entry[:timestamp] > @ttl
|
|
323
|
-
@memory_store.delete(key)
|
|
324
|
-
return "Key expired: #{key}"
|
|
325
|
-
end
|
|
326
|
-
|
|
327
|
-
entry[:access_count] += 1
|
|
328
|
-
entry[:last_accessed] = Time.now
|
|
329
|
-
|
|
330
|
-
"Retrieved: #{key} = #{entry[:value]} (accessed #{entry[:access_count]} times)"
|
|
331
|
-
else
|
|
332
|
-
"Key not found: #{key}"
|
|
333
|
-
end
|
|
334
|
-
end
|
|
335
|
-
|
|
336
|
-
def delete_value(key)
|
|
337
|
-
if @memory_store.delete(key)
|
|
338
|
-
"Deleted: #{key}"
|
|
339
|
-
else
|
|
340
|
-
"Key not found: #{key}"
|
|
341
|
-
end
|
|
342
|
-
end
|
|
343
|
-
|
|
344
|
-
def list_keys(pattern = nil)
|
|
345
|
-
keys = @memory_store.keys
|
|
346
|
-
|
|
347
|
-
if pattern
|
|
348
|
-
regex = Regexp.new(pattern)
|
|
349
|
-
keys = keys.select { |k| k.match?(regex) }
|
|
350
|
-
end
|
|
351
|
-
|
|
352
|
-
"Keys (#{keys.length}): #{keys.join(', ')}"
|
|
353
|
-
end
|
|
354
|
-
|
|
355
|
-
def clear_all
|
|
356
|
-
count = @memory_store.size
|
|
357
|
-
@memory_store.clear
|
|
358
|
-
"Cleared #{count} entries"
|
|
359
|
-
end
|
|
360
|
-
|
|
361
|
-
def evict_oldest
|
|
362
|
-
oldest = @memory_store.min_by { |k, v| v[:last_accessed] || v[:timestamp] }
|
|
363
|
-
@memory_store.delete(oldest[0]) if oldest
|
|
364
|
-
end
|
|
365
|
-
end
|
|
366
|
-
```
|
|
93
|
+
Arguments are coerced before `execute` runs, so `"5"` becomes `5` for an `:integer`.
|
|
94
|
+
A value that can't be coerced, or a missing required parameter, raises
|
|
95
|
+
`RCrewAI::Tools::ToolError`.
|
|
96
|
+
|
|
97
|
+
The tool name defaults to the class name in snake case, so `tool_name` is optional
|
|
98
|
+
for `SearchOrders`.
|
|
367
99
|
|
|
368
|
-
|
|
100
|
+
## Configuring a Tool
|
|
101
|
+
|
|
102
|
+
Put setup such as credentials and limits in `initialize`, not in parameters the
|
|
103
|
+
model can see. Call `super()` with empty parentheses, because the base class takes
|
|
104
|
+
no arguments:
|
|
369
105
|
|
|
370
106
|
```ruby
|
|
371
|
-
class
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
@
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
def execute(**params)
|
|
382
|
-
validate_params!(params,
|
|
383
|
-
required: [:task_type, :data],
|
|
384
|
-
optional: [:priority, :timeout]
|
|
385
|
-
)
|
|
386
|
-
|
|
387
|
-
task_id = SecureRandom.uuid
|
|
388
|
-
priority = params[:priority] || :normal
|
|
389
|
-
timeout = params[:timeout] || 60
|
|
390
|
-
|
|
391
|
-
# Start async processing
|
|
392
|
-
thread = Thread.new do
|
|
393
|
-
begin
|
|
394
|
-
process_async(task_id, params[:task_type], params[:data], timeout)
|
|
395
|
-
rescue => e
|
|
396
|
-
handle_async_error(task_id, e)
|
|
397
|
-
end
|
|
398
|
-
end
|
|
399
|
-
|
|
400
|
-
# Manage thread pool
|
|
401
|
-
@thread_pool << thread
|
|
402
|
-
cleanup_threads
|
|
403
|
-
|
|
404
|
-
"Task queued: #{task_id} (priority: #{priority})"
|
|
405
|
-
end
|
|
406
|
-
|
|
407
|
-
def get_status(task_id)
|
|
408
|
-
# Check task status
|
|
409
|
-
if result = check_result(task_id)
|
|
410
|
-
"Task #{task_id}: #{result[:status]} - #{result[:message]}"
|
|
411
|
-
else
|
|
412
|
-
"Task #{task_id}: Unknown or not started"
|
|
413
|
-
end
|
|
414
|
-
end
|
|
415
|
-
|
|
416
|
-
private
|
|
417
|
-
|
|
418
|
-
def process_async(task_id, task_type, data, timeout)
|
|
419
|
-
update_status(task_id, :processing, "Started at #{Time.now}")
|
|
420
|
-
|
|
421
|
-
result = Timeout::timeout(timeout) do
|
|
422
|
-
case task_type
|
|
423
|
-
when 'analysis'
|
|
424
|
-
perform_analysis(data)
|
|
425
|
-
when 'transformation'
|
|
426
|
-
perform_transformation(data)
|
|
427
|
-
when 'validation'
|
|
428
|
-
perform_validation(data)
|
|
429
|
-
else
|
|
430
|
-
raise "Unknown task type: #{task_type}"
|
|
431
|
-
end
|
|
432
|
-
end
|
|
433
|
-
|
|
434
|
-
update_status(task_id, :completed, result)
|
|
435
|
-
|
|
436
|
-
# Execute callback if provided
|
|
437
|
-
@callback.call(task_id, result) if @callback
|
|
438
|
-
|
|
439
|
-
rescue Timeout::Error
|
|
440
|
-
update_status(task_id, :timeout, "Task exceeded #{timeout}s limit")
|
|
441
|
-
end
|
|
442
|
-
|
|
443
|
-
def cleanup_threads
|
|
444
|
-
@thread_pool.reject!(&:alive?)
|
|
445
|
-
|
|
446
|
-
# Limit thread pool size
|
|
447
|
-
while @thread_pool.size > @max_threads
|
|
448
|
-
oldest = @thread_pool.shift
|
|
449
|
-
oldest.join(1) # Wait 1 second then continue
|
|
450
|
-
end
|
|
451
|
-
end
|
|
452
|
-
|
|
453
|
-
def update_status(task_id, status, message)
|
|
454
|
-
@status_store ||= {}
|
|
455
|
-
@status_store[task_id] = {
|
|
456
|
-
status: status,
|
|
457
|
-
message: message,
|
|
458
|
-
timestamp: Time.now
|
|
459
|
-
}
|
|
107
|
+
class InvoiceLookup < RCrewAI::Tools::Base
|
|
108
|
+
tool_name 'invoice_lookup'
|
|
109
|
+
description 'Look up an invoice by its number'
|
|
110
|
+
param :number, type: :string, required: true
|
|
111
|
+
|
|
112
|
+
def initialize(client:, max_age_days: 90)
|
|
113
|
+
super()
|
|
114
|
+
@client = client
|
|
115
|
+
@max_age_days = max_age_days
|
|
460
116
|
end
|
|
461
|
-
|
|
462
|
-
def
|
|
463
|
-
@
|
|
117
|
+
|
|
118
|
+
def execute(number:)
|
|
119
|
+
@client.find_invoice(number, max_age_days: @max_age_days).to_s
|
|
464
120
|
end
|
|
465
121
|
end
|
|
466
122
|
```
|
|
467
123
|
|
|
468
|
-
##
|
|
124
|
+
## Calling an API
|
|
469
125
|
|
|
470
|
-
|
|
126
|
+
Tools can use any HTTP client. Faraday is already a dependency of the gem:
|
|
471
127
|
|
|
472
128
|
```ruby
|
|
473
129
|
require 'faraday'
|
|
474
130
|
require 'json'
|
|
475
131
|
|
|
476
|
-
class
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
@
|
|
484
|
-
@
|
|
485
|
-
|
|
486
|
-
setup_client
|
|
487
|
-
end
|
|
488
|
-
|
|
489
|
-
def execute(**params)
|
|
490
|
-
validate_params!(params,
|
|
491
|
-
required: [:method, :endpoint],
|
|
492
|
-
optional: [:data, :headers, :query]
|
|
493
|
-
)
|
|
494
|
-
|
|
495
|
-
method = params[:method].to_s.downcase.to_sym
|
|
496
|
-
endpoint = params[:endpoint]
|
|
497
|
-
data = params[:data]
|
|
498
|
-
headers = params[:headers] || {}
|
|
499
|
-
query = params[:query] || {}
|
|
500
|
-
|
|
501
|
-
# Add authentication
|
|
502
|
-
headers, query = add_authentication(headers, query)
|
|
503
|
-
|
|
504
|
-
# Make request
|
|
505
|
-
response = make_request(method, endpoint, data, headers, query)
|
|
506
|
-
|
|
507
|
-
# Format response
|
|
508
|
-
format_api_response(response)
|
|
509
|
-
rescue Faraday::Error => e
|
|
510
|
-
handle_api_error(e)
|
|
511
|
-
end
|
|
512
|
-
|
|
513
|
-
private
|
|
514
|
-
|
|
515
|
-
def setup_client
|
|
516
|
-
@client = Faraday.new(url: @base_url) do |f|
|
|
517
|
-
f.request :json
|
|
518
|
-
f.response :json
|
|
519
|
-
f.adapter Faraday.default_adapter
|
|
520
|
-
f.options.timeout = @timeout
|
|
521
|
-
|
|
522
|
-
# Add middleware for logging
|
|
523
|
-
f.response :logger if @options[:debug]
|
|
524
|
-
|
|
525
|
-
# Add retry logic
|
|
526
|
-
f.request :retry, {
|
|
527
|
-
max: 3,
|
|
528
|
-
interval: 0.5,
|
|
529
|
-
interval_randomness: 0.5,
|
|
530
|
-
backoff_factor: 2
|
|
531
|
-
}
|
|
532
|
-
end
|
|
533
|
-
end
|
|
534
|
-
|
|
535
|
-
def add_authentication(headers, query)
|
|
536
|
-
case @auth_type
|
|
537
|
-
when :header
|
|
538
|
-
headers['Authorization'] = "Bearer #{@api_key}" if @api_key
|
|
539
|
-
when :query
|
|
540
|
-
query['api_key'] = @api_key if @api_key
|
|
541
|
-
when :basic
|
|
542
|
-
headers['Authorization'] = "Basic #{Base64.encode64(@api_key)}" if @api_key
|
|
543
|
-
end
|
|
544
|
-
|
|
545
|
-
[headers, query]
|
|
546
|
-
end
|
|
547
|
-
|
|
548
|
-
def make_request(method, endpoint, data, headers, query)
|
|
549
|
-
case method
|
|
550
|
-
when :get
|
|
551
|
-
@client.get(endpoint, query, headers)
|
|
552
|
-
when :post
|
|
553
|
-
@client.post(endpoint, data, headers) do |req|
|
|
554
|
-
req.params = query
|
|
555
|
-
end
|
|
556
|
-
when :put
|
|
557
|
-
@client.put(endpoint, data, headers) do |req|
|
|
558
|
-
req.params = query
|
|
559
|
-
end
|
|
560
|
-
when :patch
|
|
561
|
-
@client.patch(endpoint, data, headers) do |req|
|
|
562
|
-
req.params = query
|
|
563
|
-
end
|
|
564
|
-
when :delete
|
|
565
|
-
@client.delete(endpoint, query, headers)
|
|
566
|
-
else
|
|
567
|
-
raise ToolError, "Unsupported HTTP method: #{method}"
|
|
568
|
-
end
|
|
569
|
-
end
|
|
570
|
-
|
|
571
|
-
def format_api_response(response)
|
|
572
|
-
status = response.status
|
|
573
|
-
body = response.body
|
|
574
|
-
|
|
575
|
-
if status >= 200 && status < 300
|
|
576
|
-
if body.is_a?(Hash) || body.is_a?(Array)
|
|
577
|
-
JSON.pretty_generate(body)
|
|
578
|
-
else
|
|
579
|
-
body.to_s
|
|
580
|
-
end
|
|
581
|
-
else
|
|
582
|
-
"API Error (#{status}): #{body}"
|
|
583
|
-
end
|
|
132
|
+
class Weather < RCrewAI::Tools::Base
|
|
133
|
+
tool_name 'weather'
|
|
134
|
+
description 'Get the current weather for a city'
|
|
135
|
+
param :city, type: :string, required: true, description: 'City name, e.g. "Brussels"'
|
|
136
|
+
|
|
137
|
+
def initialize(api_key:, base_url: 'https://api.openweathermap.org')
|
|
138
|
+
super()
|
|
139
|
+
@http = Faraday.new(url: base_url, request: { timeout: 10 })
|
|
140
|
+
@api_key = api_key
|
|
584
141
|
end
|
|
585
|
-
|
|
586
|
-
def
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
else
|
|
593
|
-
"API error: #{error.class} - #{error.message}"
|
|
594
|
-
end
|
|
142
|
+
|
|
143
|
+
def execute(city:)
|
|
144
|
+
response = @http.get('/data/2.5/weather', { q: city, appid: @api_key, units: 'metric' })
|
|
145
|
+
raise RCrewAI::Tools::ToolError, "Weather API returned #{response.status}" unless response.success?
|
|
146
|
+
|
|
147
|
+
data = JSON.parse(response.body)
|
|
148
|
+
"#{data['name']}: #{data.dig('main', 'temp')}°C, #{data.dig('weather', 0, 'description')}"
|
|
595
149
|
end
|
|
596
150
|
end
|
|
151
|
+
```
|
|
597
152
|
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
base_url: 'https://api.github.com',
|
|
601
|
-
api_key: ENV['GITHUB_TOKEN'],
|
|
602
|
-
auth_type: :header
|
|
603
|
-
)
|
|
153
|
+
To use tools that someone else already hosts, connect to an MCP server instead of
|
|
154
|
+
writing a wrapper. See the [MCP guide]({{ site.baseurl }}/mcp).
|
|
604
155
|
|
|
605
|
-
|
|
606
|
-
```
|
|
156
|
+
## Errors
|
|
607
157
|
|
|
608
|
-
|
|
158
|
+
Raise an error when a tool can't do its job. Under native function calling, the
|
|
159
|
+
exception doesn't fail the task: the model receives `ERROR: <message>` as the tool's
|
|
160
|
+
result and can correct itself. Write messages it can act on:
|
|
609
161
|
|
|
610
162
|
```ruby
|
|
611
|
-
class
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
def execute(**params)
|
|
622
|
-
validate_params!(params,
|
|
623
|
-
required: [:query],
|
|
624
|
-
optional: [:variables, :operation_name]
|
|
625
|
-
)
|
|
626
|
-
|
|
627
|
-
query = params[:query]
|
|
628
|
-
variables = params[:variables] || {}
|
|
629
|
-
operation_name = params[:operation_name]
|
|
630
|
-
|
|
631
|
-
response = @client.execute(
|
|
632
|
-
query,
|
|
633
|
-
variables: variables,
|
|
634
|
-
operation_name: operation_name
|
|
635
|
-
)
|
|
636
|
-
|
|
637
|
-
format_graphql_response(response)
|
|
638
|
-
rescue => e
|
|
639
|
-
"GraphQL error: #{e.message}"
|
|
640
|
-
end
|
|
641
|
-
|
|
642
|
-
private
|
|
643
|
-
|
|
644
|
-
def setup_graphql_client
|
|
645
|
-
Faraday.new(url: @endpoint) do |f|
|
|
646
|
-
f.request :json
|
|
647
|
-
f.response :json
|
|
648
|
-
f.adapter Faraday.default_adapter
|
|
649
|
-
|
|
650
|
-
# Add authentication
|
|
651
|
-
f.headers['Authorization'] = "Bearer #{@api_key}" if @api_key
|
|
652
|
-
end
|
|
653
|
-
end
|
|
654
|
-
|
|
655
|
-
def format_graphql_response(response)
|
|
656
|
-
if response['errors']
|
|
657
|
-
errors = response['errors'].map { |e| e['message'] }.join(', ')
|
|
658
|
-
"GraphQL errors: #{errors}"
|
|
659
|
-
elsif response['data']
|
|
660
|
-
JSON.pretty_generate(response['data'])
|
|
661
|
-
else
|
|
662
|
-
"Empty response"
|
|
163
|
+
class ReadReport < RCrewAI::Tools::Base
|
|
164
|
+
tool_name 'read_report'
|
|
165
|
+
description 'Read a report by its id'
|
|
166
|
+
param :id, type: :string, required: true
|
|
167
|
+
|
|
168
|
+
REPORTS = { 'q1' => 'Revenue grew 4%.' }.freeze
|
|
169
|
+
|
|
170
|
+
def execute(id:)
|
|
171
|
+
REPORTS.fetch(id) do
|
|
172
|
+
raise RCrewAI::Tools::ToolError, "No report '#{id}'. Available: #{REPORTS.keys.join(', ')}"
|
|
663
173
|
end
|
|
664
174
|
end
|
|
665
175
|
end
|
|
666
176
|
```
|
|
667
177
|
|
|
668
|
-
##
|
|
178
|
+
## Thread Safety
|
|
669
179
|
|
|
670
|
-
|
|
180
|
+
When a model requests several tools in one turn, they run concurrently on the same
|
|
181
|
+
tool instances. A tool with mutable state must protect it:
|
|
671
182
|
|
|
672
183
|
```ruby
|
|
673
|
-
|
|
184
|
+
class Counter < RCrewAI::Tools::Base
|
|
185
|
+
tool_name 'counter'
|
|
186
|
+
description 'Increment a shared counter and return its value'
|
|
187
|
+
param :by, type: :integer, required: true
|
|
674
188
|
|
|
675
|
-
|
|
676
|
-
def initialize(**options)
|
|
189
|
+
def initialize
|
|
677
190
|
super
|
|
678
|
-
@
|
|
679
|
-
@
|
|
680
|
-
@connection_string = options[:connection_string]
|
|
681
|
-
@read_only = options[:read_only] || true
|
|
682
|
-
@max_rows = options[:max_rows] || 100
|
|
683
|
-
@timeout = options[:timeout] || 30
|
|
684
|
-
|
|
685
|
-
setup_connection
|
|
686
|
-
end
|
|
687
|
-
|
|
688
|
-
def execute(**params)
|
|
689
|
-
validate_params!(params, required: [:query], optional: [:params])
|
|
690
|
-
|
|
691
|
-
query = params[:query]
|
|
692
|
-
query_params = params[:params] || []
|
|
693
|
-
|
|
694
|
-
# Safety checks
|
|
695
|
-
validate_query_safety(query) if @read_only
|
|
696
|
-
|
|
697
|
-
# Execute query
|
|
698
|
-
result = execute_query(query, query_params)
|
|
699
|
-
|
|
700
|
-
# Format result
|
|
701
|
-
format_query_result(result)
|
|
702
|
-
rescue => e
|
|
703
|
-
"Database error: #{e.message}"
|
|
704
|
-
end
|
|
705
|
-
|
|
706
|
-
private
|
|
707
|
-
|
|
708
|
-
def setup_connection
|
|
709
|
-
@db = Sequel.connect(@connection_string)
|
|
710
|
-
@db.extension :pg_json if @connection_string.include?('postgres')
|
|
711
|
-
|
|
712
|
-
# Set connection options
|
|
713
|
-
@db.pool.connection_validation_timeout = -1
|
|
714
|
-
@db.pool.max_connections = 5
|
|
191
|
+
@count = 0
|
|
192
|
+
@lock = Mutex.new
|
|
715
193
|
end
|
|
716
|
-
|
|
717
|
-
def
|
|
718
|
-
|
|
719
|
-
INSERT UPDATE DELETE DROP CREATE ALTER TRUNCATE
|
|
720
|
-
EXEC EXECUTE GRANT REVOKE
|
|
721
|
-
]
|
|
722
|
-
|
|
723
|
-
query_upper = query.upcase
|
|
724
|
-
unsafe_keywords.each do |keyword|
|
|
725
|
-
if query_upper.include?(keyword)
|
|
726
|
-
raise ToolError, "Unsafe operation '#{keyword}' not allowed in read-only mode"
|
|
727
|
-
end
|
|
728
|
-
end
|
|
729
|
-
end
|
|
730
|
-
|
|
731
|
-
def execute_query(query, params)
|
|
732
|
-
Timeout::timeout(@timeout) do
|
|
733
|
-
dataset = @db[query, *params]
|
|
734
|
-
|
|
735
|
-
# Limit results
|
|
736
|
-
dataset = dataset.limit(@max_rows) if dataset.respond_to?(:limit)
|
|
737
|
-
|
|
738
|
-
# Execute and fetch
|
|
739
|
-
if query.upcase.start_with?('SELECT')
|
|
740
|
-
dataset.all
|
|
741
|
-
else
|
|
742
|
-
rows_affected = dataset
|
|
743
|
-
{ rows_affected: rows_affected }
|
|
744
|
-
end
|
|
745
|
-
end
|
|
746
|
-
end
|
|
747
|
-
|
|
748
|
-
def format_query_result(result)
|
|
749
|
-
if result.is_a?(Array)
|
|
750
|
-
# Format as table
|
|
751
|
-
return "No results" if result.empty?
|
|
752
|
-
|
|
753
|
-
headers = result.first.keys
|
|
754
|
-
rows = result.map { |r| r.values }
|
|
755
|
-
|
|
756
|
-
format_table(headers, rows)
|
|
757
|
-
elsif result.is_a?(Hash)
|
|
758
|
-
"Query executed: #{result[:rows_affected]} rows affected"
|
|
759
|
-
else
|
|
760
|
-
result.to_s
|
|
761
|
-
end
|
|
762
|
-
end
|
|
763
|
-
|
|
764
|
-
def format_table(headers, rows)
|
|
765
|
-
# Calculate column widths
|
|
766
|
-
widths = headers.map(&:to_s).map(&:length)
|
|
767
|
-
rows.each do |row|
|
|
768
|
-
row.each_with_index do |cell, i|
|
|
769
|
-
widths[i] = [widths[i], cell.to_s.length].max
|
|
770
|
-
end
|
|
771
|
-
end
|
|
772
|
-
|
|
773
|
-
# Build table
|
|
774
|
-
separator = "+" + widths.map { |w| "-" * (w + 2) }.join("+") + "+"
|
|
775
|
-
header_row = "|" + headers.each_with_index.map { |h, i|
|
|
776
|
-
" #{h.to_s.ljust(widths[i])} "
|
|
777
|
-
}.join("|") + "|"
|
|
778
|
-
|
|
779
|
-
table = [separator, header_row, separator]
|
|
780
|
-
|
|
781
|
-
rows.each do |row|
|
|
782
|
-
row_str = "|" + row.each_with_index.map { |cell, i|
|
|
783
|
-
" #{cell.to_s.ljust(widths[i])} "
|
|
784
|
-
}.join("|") + "|"
|
|
785
|
-
table << row_str
|
|
786
|
-
end
|
|
787
|
-
|
|
788
|
-
table << separator
|
|
789
|
-
table.join("\n")
|
|
194
|
+
|
|
195
|
+
def execute(by:)
|
|
196
|
+
@lock.synchronize { @count += by }.to_s
|
|
790
197
|
end
|
|
791
198
|
end
|
|
792
199
|
```
|
|
793
200
|
|
|
794
|
-
|
|
201
|
+
If that isn't practical, set `parallel_tools: false` on the agent using the tool.
|
|
202
|
+
|
|
203
|
+
## Security
|
|
795
204
|
|
|
796
|
-
|
|
205
|
+
Treat tool arguments as untrusted input. They come from the model, and the model's
|
|
206
|
+
input may include content from web pages, documents, or users.
|
|
797
207
|
|
|
798
208
|
```ruby
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
super
|
|
808
|
-
@name = 'document_processor'
|
|
809
|
-
@description = 'Extract and process content from various document formats'
|
|
810
|
-
@max_file_size = options[:max_file_size] || 10_000_000 # 10MB
|
|
811
|
-
end
|
|
812
|
-
|
|
813
|
-
def execute(**params)
|
|
814
|
-
validate_params!(params,
|
|
815
|
-
required: [:file_path],
|
|
816
|
-
optional: [:operation, :options]
|
|
817
|
-
)
|
|
818
|
-
|
|
819
|
-
file_path = params[:file_path]
|
|
820
|
-
operation = params[:operation] || :extract_text
|
|
821
|
-
options = params[:options] || {}
|
|
822
|
-
|
|
823
|
-
# Validate file
|
|
824
|
-
validate_file(file_path)
|
|
825
|
-
|
|
826
|
-
# Process based on operation
|
|
827
|
-
case operation.to_sym
|
|
828
|
-
when :extract_text
|
|
829
|
-
extract_text(file_path, options)
|
|
830
|
-
when :extract_metadata
|
|
831
|
-
extract_metadata(file_path)
|
|
832
|
-
when :convert
|
|
833
|
-
convert_document(file_path, options)
|
|
834
|
-
when :analyze
|
|
835
|
-
analyze_document(file_path, options)
|
|
836
|
-
else
|
|
837
|
-
raise ToolError, "Unknown operation: #{operation}"
|
|
838
|
-
end
|
|
839
|
-
end
|
|
840
|
-
|
|
841
|
-
private
|
|
842
|
-
|
|
843
|
-
def validate_file(file_path)
|
|
844
|
-
unless File.exist?(file_path)
|
|
845
|
-
raise ToolError, "File not found: #{file_path}"
|
|
846
|
-
end
|
|
847
|
-
|
|
848
|
-
if File.size(file_path) > @max_file_size
|
|
849
|
-
raise ToolError, "File too large: #{File.size(file_path)} bytes"
|
|
850
|
-
end
|
|
851
|
-
|
|
852
|
-
ext = File.extname(file_path).downcase
|
|
853
|
-
unless SUPPORTED_FORMATS.include?(ext)
|
|
854
|
-
raise ToolError, "Unsupported format: #{ext}"
|
|
855
|
-
end
|
|
856
|
-
end
|
|
857
|
-
|
|
858
|
-
def extract_text(file_path, options)
|
|
859
|
-
ext = File.extname(file_path).downcase
|
|
860
|
-
|
|
861
|
-
text = case ext
|
|
862
|
-
when '.pdf'
|
|
863
|
-
extract_pdf_text(file_path, options)
|
|
864
|
-
when '.docx'
|
|
865
|
-
extract_docx_text(file_path)
|
|
866
|
-
when '.txt'
|
|
867
|
-
File.read(file_path)
|
|
868
|
-
when '.csv'
|
|
869
|
-
extract_csv_text(file_path, options)
|
|
870
|
-
when '.json'
|
|
871
|
-
JSON.pretty_generate(JSON.parse(File.read(file_path)))
|
|
872
|
-
end
|
|
873
|
-
|
|
874
|
-
# Apply options
|
|
875
|
-
if options[:max_length]
|
|
876
|
-
text = text[0...options[:max_length]]
|
|
877
|
-
end
|
|
878
|
-
|
|
879
|
-
if options[:clean]
|
|
880
|
-
text = clean_text(text)
|
|
881
|
-
end
|
|
882
|
-
|
|
883
|
-
text
|
|
884
|
-
end
|
|
885
|
-
|
|
886
|
-
def extract_pdf_text(file_path, options)
|
|
887
|
-
reader = PDF::Reader.new(file_path)
|
|
888
|
-
|
|
889
|
-
if options[:page]
|
|
890
|
-
# Extract specific page
|
|
891
|
-
page = reader.pages[options[:page] - 1]
|
|
892
|
-
page&.text || ""
|
|
893
|
-
else
|
|
894
|
-
# Extract all pages
|
|
895
|
-
reader.pages.map(&:text).join("\n\n")
|
|
896
|
-
end
|
|
897
|
-
end
|
|
898
|
-
|
|
899
|
-
def extract_docx_text(file_path)
|
|
900
|
-
doc = Docx::Document.open(file_path)
|
|
901
|
-
doc.paragraphs.map(&:text).join("\n")
|
|
902
|
-
end
|
|
903
|
-
|
|
904
|
-
def extract_csv_text(file_path, options)
|
|
905
|
-
csv_options = {
|
|
906
|
-
headers: options[:headers] != false,
|
|
907
|
-
encoding: options[:encoding] || 'UTF-8'
|
|
908
|
-
}
|
|
909
|
-
|
|
910
|
-
rows = CSV.read(file_path, csv_options)
|
|
911
|
-
|
|
912
|
-
if options[:as_json]
|
|
913
|
-
JSON.pretty_generate(rows.map(&:to_h))
|
|
914
|
-
else
|
|
915
|
-
CSV.generate do |csv|
|
|
916
|
-
rows.each { |row| csv << row }
|
|
917
|
-
end
|
|
918
|
-
end
|
|
919
|
-
end
|
|
920
|
-
|
|
921
|
-
def extract_metadata(file_path)
|
|
922
|
-
metadata = {
|
|
923
|
-
filename: File.basename(file_path),
|
|
924
|
-
size: File.size(file_path),
|
|
925
|
-
modified: File.mtime(file_path),
|
|
926
|
-
format: File.extname(file_path)
|
|
927
|
-
}
|
|
928
|
-
|
|
929
|
-
ext = File.extname(file_path).downcase
|
|
930
|
-
|
|
931
|
-
case ext
|
|
932
|
-
when '.pdf'
|
|
933
|
-
reader = PDF::Reader.new(file_path)
|
|
934
|
-
metadata[:pages] = reader.page_count
|
|
935
|
-
metadata[:info] = reader.info
|
|
936
|
-
when '.docx'
|
|
937
|
-
doc = Docx::Document.open(file_path)
|
|
938
|
-
metadata[:paragraphs] = doc.paragraphs.count
|
|
939
|
-
metadata[:tables] = doc.tables.count
|
|
940
|
-
end
|
|
941
|
-
|
|
942
|
-
JSON.pretty_generate(metadata)
|
|
943
|
-
end
|
|
944
|
-
|
|
945
|
-
def analyze_document(file_path, options)
|
|
946
|
-
text = extract_text(file_path, {})
|
|
947
|
-
|
|
948
|
-
analysis = {
|
|
949
|
-
character_count: text.length,
|
|
950
|
-
word_count: text.split.length,
|
|
951
|
-
line_count: text.lines.count,
|
|
952
|
-
paragraph_count: text.split(/\n\n+/).length
|
|
953
|
-
}
|
|
954
|
-
|
|
955
|
-
if options[:keywords]
|
|
956
|
-
keywords = options[:keywords]
|
|
957
|
-
analysis[:keyword_frequency] = {}
|
|
958
|
-
|
|
959
|
-
keywords.each do |keyword|
|
|
960
|
-
count = text.scan(/#{Regexp.escape(keyword)}/i).length
|
|
961
|
-
analysis[:keyword_frequency][keyword] = count
|
|
962
|
-
end
|
|
963
|
-
end
|
|
964
|
-
|
|
965
|
-
JSON.pretty_generate(analysis)
|
|
209
|
+
class ReadDoc < RCrewAI::Tools::Base
|
|
210
|
+
tool_name 'read_doc'
|
|
211
|
+
description 'Read a document from the docs folder'
|
|
212
|
+
param :path, type: :string, required: true, description: 'Path relative to the docs folder'
|
|
213
|
+
|
|
214
|
+
def initialize(root:)
|
|
215
|
+
super()
|
|
216
|
+
@root = File.realpath(root)
|
|
966
217
|
end
|
|
967
|
-
|
|
968
|
-
def
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
# Normalize line endings
|
|
976
|
-
text = text.gsub(/\r\n/, "\n")
|
|
977
|
-
|
|
978
|
-
text.strip
|
|
218
|
+
|
|
219
|
+
def execute(path:)
|
|
220
|
+
full = File.realpath(File.join(@root, path))
|
|
221
|
+
raise RCrewAI::Tools::ToolError, 'Path is outside the docs folder' unless full.start_with?("#{@root}/")
|
|
222
|
+
|
|
223
|
+
File.read(full)
|
|
224
|
+
rescue Errno::ENOENT
|
|
225
|
+
raise RCrewAI::Tools::ToolError, "No such document: #{path}"
|
|
979
226
|
end
|
|
980
227
|
end
|
|
981
228
|
```
|
|
982
229
|
|
|
983
|
-
|
|
230
|
+
- Resolve paths before checking them, as above, so `../` and symlinks can't escape.
|
|
231
|
+
- Use parameterized queries, and allowlists for commands, hosts, and table names.
|
|
232
|
+
- Keep secrets in `initialize`, and leave them out of return values and error messages.
|
|
233
|
+
- For risky actions, require a person to approve them with `require_approval_for_tools: true`.
|
|
234
|
+
|
|
235
|
+
## Testing Tools
|
|
984
236
|
|
|
985
|
-
|
|
237
|
+
Test `execute_with_validation` with string keys, since that's how the runner calls
|
|
238
|
+
your tool, with arguments shaped like the model's JSON:
|
|
986
239
|
|
|
987
240
|
```ruby
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
RSpec.describe CalculatorTool do
|
|
991
|
-
let(:tool) { CalculatorTool.new(precision: 2) }
|
|
992
|
-
|
|
993
|
-
describe '#execute' do
|
|
994
|
-
context 'with addition' do
|
|
995
|
-
it 'adds numbers correctly' do
|
|
996
|
-
result = tool.execute(
|
|
997
|
-
operation: 'add',
|
|
998
|
-
operands: [5, 3, 2]
|
|
999
|
-
)
|
|
1000
|
-
expect(result).to eq('Result: 10')
|
|
1001
|
-
end
|
|
1002
|
-
end
|
|
1003
|
-
|
|
1004
|
-
context 'with division' do
|
|
1005
|
-
it 'divides numbers correctly' do
|
|
1006
|
-
result = tool.execute(
|
|
1007
|
-
operation: 'divide',
|
|
1008
|
-
operands: [10, 2]
|
|
1009
|
-
)
|
|
1010
|
-
expect(result).to eq('Result: 5')
|
|
1011
|
-
end
|
|
1012
|
-
|
|
1013
|
-
it 'raises error for division by zero' do
|
|
1014
|
-
expect {
|
|
1015
|
-
tool.execute(
|
|
1016
|
-
operation: 'divide',
|
|
1017
|
-
operands: [10, 0]
|
|
1018
|
-
)
|
|
1019
|
-
}.to raise_error(RCrewAI::Tools::ToolError, /Division by zero/)
|
|
1020
|
-
end
|
|
1021
|
-
end
|
|
1022
|
-
|
|
1023
|
-
context 'with invalid parameters' do
|
|
1024
|
-
it 'raises error for missing required parameters' do
|
|
1025
|
-
expect {
|
|
1026
|
-
tool.execute(operation: 'add')
|
|
1027
|
-
}.to raise_error(RCrewAI::Tools::ToolError, /Missing required parameter/)
|
|
1028
|
-
end
|
|
1029
|
-
|
|
1030
|
-
it 'raises error for invalid operands' do
|
|
1031
|
-
expect {
|
|
1032
|
-
tool.execute(
|
|
1033
|
-
operation: 'add',
|
|
1034
|
-
operands: 'not an array'
|
|
1035
|
-
)
|
|
1036
|
-
}.to raise_error(RCrewAI::Tools::ToolError, /must be an array/)
|
|
1037
|
-
end
|
|
1038
|
-
end
|
|
1039
|
-
end
|
|
1040
|
-
end
|
|
1041
|
-
```
|
|
241
|
+
RSpec.describe WordCount do
|
|
242
|
+
subject(:tool) { described_class.new }
|
|
1042
243
|
|
|
1043
|
-
|
|
244
|
+
it 'counts words' do
|
|
245
|
+
expect(tool.execute_with_validation('text' => 'one two three')).to eq('3')
|
|
246
|
+
end
|
|
1044
247
|
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
let(:agent) do
|
|
1048
|
-
RCrewAI::Agent.new(
|
|
1049
|
-
name: 'test_agent',
|
|
1050
|
-
role: 'Tool Tester',
|
|
1051
|
-
goal: 'Test tool integration',
|
|
1052
|
-
tools: [
|
|
1053
|
-
CalculatorTool.new,
|
|
1054
|
-
WeatherTool.new(api_key: 'test_key'),
|
|
1055
|
-
SessionMemoryTool.new
|
|
1056
|
-
]
|
|
1057
|
-
)
|
|
248
|
+
it 'requires text' do
|
|
249
|
+
expect { tool.execute_with_validation({}) }.to raise_error(RCrewAI::Tools::ToolError, /missing required param/)
|
|
1058
250
|
end
|
|
1059
|
-
|
|
1060
|
-
it '
|
|
1061
|
-
|
|
1062
|
-
name: 'complex_calculation',
|
|
1063
|
-
description: 'Calculate 5 * 3, store result, then add 10',
|
|
1064
|
-
agent: agent
|
|
1065
|
-
)
|
|
1066
|
-
|
|
1067
|
-
# Mock the reasoning loop to use tools
|
|
1068
|
-
allow(agent).to receive(:reasoning_loop) do |task, context|
|
|
1069
|
-
# Step 1: Multiply
|
|
1070
|
-
result1 = agent.use_tool('calculator',
|
|
1071
|
-
operation: 'multiply',
|
|
1072
|
-
operands: [5, 3]
|
|
1073
|
-
)
|
|
1074
|
-
|
|
1075
|
-
# Step 2: Store result
|
|
1076
|
-
agent.use_tool('session_memory',
|
|
1077
|
-
action: 'store',
|
|
1078
|
-
key: 'multiply_result',
|
|
1079
|
-
value: 15
|
|
1080
|
-
)
|
|
1081
|
-
|
|
1082
|
-
# Step 3: Add
|
|
1083
|
-
result2 = agent.use_tool('calculator',
|
|
1084
|
-
operation: 'add',
|
|
1085
|
-
operands: [15, 10]
|
|
1086
|
-
)
|
|
1087
|
-
|
|
1088
|
-
"Final result: 25"
|
|
1089
|
-
end
|
|
1090
|
-
|
|
1091
|
-
result = task.execute
|
|
1092
|
-
expect(result).to include('25')
|
|
251
|
+
|
|
252
|
+
it 'publishes its schema' do
|
|
253
|
+
expect(described_class.json_schema[:parameters][:required]).to eq(['text'])
|
|
1093
254
|
end
|
|
1094
255
|
end
|
|
1095
256
|
```
|
|
1096
257
|
|
|
1097
|
-
|
|
258
|
+
To test an agent using a tool without calling a real API, pass a fake client through
|
|
259
|
+
`llm:`. Anything that responds to `chat` works.
|
|
260
|
+
|
|
261
|
+
## Tools Without the DSL
|
|
1098
262
|
|
|
1099
|
-
|
|
263
|
+
Tools written before the DSL still work:
|
|
1100
264
|
|
|
1101
265
|
```ruby
|
|
1102
|
-
class
|
|
1103
|
-
def
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
# Rate limiting
|
|
1108
|
-
check_rate_limit
|
|
1109
|
-
|
|
1110
|
-
# Execute with timeout
|
|
1111
|
-
Timeout::timeout(execution_timeout) do
|
|
1112
|
-
# Audit logging
|
|
1113
|
-
log_execution(sanitized_params)
|
|
1114
|
-
|
|
1115
|
-
# Execute tool logic
|
|
1116
|
-
result = perform_execution(sanitized_params)
|
|
1117
|
-
|
|
1118
|
-
# Output validation
|
|
1119
|
-
validate_output(result)
|
|
1120
|
-
|
|
1121
|
-
result
|
|
1122
|
-
end
|
|
1123
|
-
rescue Timeout::Error
|
|
1124
|
-
handle_timeout
|
|
1125
|
-
rescue => e
|
|
1126
|
-
handle_error(e)
|
|
1127
|
-
end
|
|
1128
|
-
|
|
1129
|
-
private
|
|
1130
|
-
|
|
1131
|
-
def sanitize_inputs(params)
|
|
1132
|
-
params.transform_values do |value|
|
|
1133
|
-
case value
|
|
1134
|
-
when String
|
|
1135
|
-
# Remove potentially dangerous characters
|
|
1136
|
-
value.gsub(/[<>'\"&]/, '')
|
|
1137
|
-
when Array
|
|
1138
|
-
value.map { |v| sanitize_inputs(v) if v.is_a?(String) || v.is_a?(Hash) }
|
|
1139
|
-
when Hash
|
|
1140
|
-
sanitize_inputs(value)
|
|
1141
|
-
else
|
|
1142
|
-
value
|
|
1143
|
-
end
|
|
1144
|
-
end
|
|
1145
|
-
end
|
|
1146
|
-
|
|
1147
|
-
def check_rate_limit
|
|
1148
|
-
@last_execution ||= {}
|
|
1149
|
-
key = "#{self.class.name}_#{Thread.current.object_id}"
|
|
1150
|
-
|
|
1151
|
-
if @last_execution[key] && Time.now - @last_execution[key] < 1
|
|
1152
|
-
raise ToolError, "Rate limit exceeded - please wait"
|
|
1153
|
-
end
|
|
1154
|
-
|
|
1155
|
-
@last_execution[key] = Time.now
|
|
1156
|
-
end
|
|
1157
|
-
|
|
1158
|
-
def validate_output(result)
|
|
1159
|
-
# Check output size
|
|
1160
|
-
if result.to_s.length > 1_000_000
|
|
1161
|
-
raise ToolError, "Output too large"
|
|
1162
|
-
end
|
|
1163
|
-
|
|
1164
|
-
# Check for sensitive data
|
|
1165
|
-
if contains_sensitive_data?(result)
|
|
1166
|
-
raise ToolError, "Output contains sensitive information"
|
|
1167
|
-
end
|
|
1168
|
-
end
|
|
1169
|
-
|
|
1170
|
-
def contains_sensitive_data?(text)
|
|
1171
|
-
patterns = [
|
|
1172
|
-
/\b\d{3}-\d{2}-\d{4}\b/, # SSN
|
|
1173
|
-
/\b\d{16}\b/, # Credit card
|
|
1174
|
-
/api[_-]?key/i, # API keys
|
|
1175
|
-
/password/i, # Passwords
|
|
1176
|
-
/secret/i # Secrets
|
|
1177
|
-
]
|
|
1178
|
-
|
|
1179
|
-
text_str = text.to_s
|
|
1180
|
-
patterns.any? { |pattern| text_str.match?(pattern) }
|
|
1181
|
-
end
|
|
1182
|
-
|
|
1183
|
-
def log_execution(params)
|
|
1184
|
-
@logger.info "Tool execution: #{@name}"
|
|
1185
|
-
@logger.debug "Parameters: #{params.inspect}"
|
|
266
|
+
class LegacyTool < RCrewAI::Tools::Base
|
|
267
|
+
def initialize
|
|
268
|
+
super
|
|
269
|
+
@name = 'legacy'
|
|
270
|
+
@description = 'A tool that sets its name in initialize'
|
|
1186
271
|
end
|
|
1187
|
-
|
|
1188
|
-
def
|
|
1189
|
-
|
|
272
|
+
|
|
273
|
+
def execute(**params)
|
|
274
|
+
validate_params!(params, required: [:input])
|
|
275
|
+
"Got #{params[:input]}"
|
|
1190
276
|
end
|
|
1191
277
|
end
|
|
1192
278
|
```
|
|
1193
279
|
|
|
280
|
+
A tool like this has no declared parameters, so it prints a warning and gets a
|
|
281
|
+
permissive schema: `Tool LegacyTool has no DSL declarations; using permissive schema`.
|
|
282
|
+
The model then has no description of its arguments, so add `param` declarations when
|
|
283
|
+
you next touch it.
|
|
284
|
+
|
|
1194
285
|
## Best Practices
|
|
1195
286
|
|
|
1196
|
-
|
|
1197
|
-
-
|
|
1198
|
-
-
|
|
1199
|
-
-
|
|
1200
|
-
-
|
|
1201
|
-
- Consistent output formatting
|
|
1202
|
-
|
|
1203
|
-
### 2. **Security Considerations**
|
|
1204
|
-
- Always sanitize inputs
|
|
1205
|
-
- Implement rate limiting
|
|
1206
|
-
- Use timeouts to prevent hanging
|
|
1207
|
-
- Validate output size and content
|
|
1208
|
-
- Audit log all executions
|
|
1209
|
-
- Never expose sensitive data
|
|
1210
|
-
|
|
1211
|
-
### 3. **Performance Optimization**
|
|
1212
|
-
- Cache expensive operations
|
|
1213
|
-
- Use connection pooling for databases/APIs
|
|
1214
|
-
- Implement retry logic with backoff
|
|
1215
|
-
- Stream large files instead of loading entirely
|
|
1216
|
-
- Clean up resources after use
|
|
1217
|
-
|
|
1218
|
-
### 4. **Error Handling**
|
|
1219
|
-
- Provide clear error messages
|
|
1220
|
-
- Distinguish between recoverable and fatal errors
|
|
1221
|
-
- Log errors with context
|
|
1222
|
-
- Implement graceful degradation
|
|
1223
|
-
- Return partial results when possible
|
|
1224
|
-
|
|
1225
|
-
### 5. **Testing Strategy**
|
|
1226
|
-
- Unit test all tool methods
|
|
1227
|
-
- Test parameter validation thoroughly
|
|
1228
|
-
- Mock external dependencies
|
|
1229
|
-
- Test error conditions
|
|
1230
|
-
- Integration test with agents
|
|
1231
|
-
- Performance test with large inputs
|
|
287
|
+
- **Do one thing per tool.** Several small tools are easier for a model to choose between.
|
|
288
|
+
- **Write descriptions for the model.** Include when to use the tool and what each parameter means.
|
|
289
|
+
- **Return only what's useful.** Tool output goes into the conversation and costs tokens.
|
|
290
|
+
- **Set timeouts on network calls.** A hung tool holds up the whole turn.
|
|
291
|
+
- **Make retried actions safe.** A model may call a tool again after an error.
|
|
1232
292
|
|
|
1233
293
|
## Next Steps
|
|
1234
294
|
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
2. Explore [Production Deployment]({{ site.baseurl }}/tutorials/deployment) strategies
|
|
1239
|
-
3. Review the [Tools API Documentation]({{ site.baseurl }}/api/tools)
|
|
1240
|
-
4. Check out [Example Custom Tools]({{ site.baseurl }}/examples/) in production
|
|
1241
|
-
|
|
1242
|
-
Custom tools are essential for extending RCrewAI to handle specialized tasks and integrate with your existing systems.
|
|
295
|
+
- [Tools API reference]({{ site.baseurl }}/api/tools)
|
|
296
|
+
- [Advanced Agent Configuration]({{ site.baseurl }}/tutorials/advanced-agents)
|
|
297
|
+
- [MCP guide]({{ site.baseurl }}/mcp)
|