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.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +24 -0
  3. data/README.md +133 -23
  4. data/ROADMAP.md +1 -1
  5. data/docs/api/agent.md +5 -2
  6. data/docs/api/configuration.md +36 -41
  7. data/docs/api/crew.md +34 -48
  8. data/docs/api/index.md +7 -0
  9. data/docs/api/task.md +10 -91
  10. data/docs/api/tools.md +19 -0
  11. data/docs/examples/api-integration.md +4 -4
  12. data/docs/examples/async-execution.md +4 -4
  13. data/docs/examples/code-review-crew.md +1 -1
  14. data/docs/examples/content-marketing-pipeline.md +3 -3
  15. data/docs/examples/custom-tools.md +8 -8
  16. data/docs/examples/customer-support.md +5 -5
  17. data/docs/examples/data-analysis-team.md +4 -4
  18. data/docs/examples/database-operations.md +4 -4
  19. data/docs/examples/ecommerce-operations.md +4 -4
  20. data/docs/examples/financial-analysis.md +3 -3
  21. data/docs/examples/hierarchical-crew.md +3 -2
  22. data/docs/examples/production-ready-crew.md +16 -10
  23. data/docs/examples/research-development.md +5 -5
  24. data/docs/examples/simple-research-crew.md +2 -2
  25. data/docs/examples/social-media.md +4 -4
  26. data/docs/examples/task-automation.md +2 -2
  27. data/docs/examples/tool-composition.md +42 -27
  28. data/docs/examples/web-scraping.md +6 -6
  29. data/docs/index.md +61 -44
  30. data/docs/tutorials/advanced-agents.md +194 -917
  31. data/docs/tutorials/agent-options.md +1 -1
  32. data/docs/tutorials/checkpointing.md +65 -0
  33. data/docs/tutorials/concurrency.md +57 -0
  34. data/docs/tutorials/custom-tools.md +198 -1143
  35. data/docs/tutorials/deployment.md +156 -155
  36. data/docs/tutorials/getting-started.md +69 -81
  37. data/docs/tutorials/index.md +19 -0
  38. data/docs/tutorials/interceptors-and-events.md +84 -0
  39. data/docs/tutorials/live-streaming.md +52 -0
  40. data/docs/tutorials/multiple-crews.md +70 -51
  41. data/docs/tutorials/providers.md +115 -0
  42. data/docs/upgrading-to-0.11.md +55 -0
  43. data/lib/rcrewai/agent.rb +0 -2
  44. data/lib/rcrewai/configuration.rb +64 -29
  45. data/lib/rcrewai/context_window.rb +12 -2
  46. data/lib/rcrewai/llm_clients/anthropic.rb +60 -9
  47. data/lib/rcrewai/llm_clients/base.rb +7 -0
  48. data/lib/rcrewai/llm_clients/bedrock.rb +29 -2
  49. data/lib/rcrewai/llm_clients/google.rb +36 -4
  50. data/lib/rcrewai/llm_clients/ollama.rb +17 -3
  51. data/lib/rcrewai/llm_clients/openai.rb +14 -1
  52. data/lib/rcrewai/llm_clients/openai_responses.rb +21 -2
  53. data/lib/rcrewai/pricing.rb +13 -3
  54. data/lib/rcrewai/tool_runner.rb +5 -1
  55. data/lib/rcrewai/version.rb +1 -1
  56. metadata +7 -1
@@ -1,1014 +1,291 @@
1
1
  ---
2
2
  layout: tutorial
3
3
  title: Advanced Agent Configuration
4
- description: Master advanced agent features including memory, custom reasoning, delegation, and performance optimization
4
+ description: Configure per-agent models, memory, reasoning, rate limits, concurrency, delegation, and custom agent subclasses
5
5
  ---
6
6
 
7
7
  # Advanced Agent Configuration
8
8
 
9
- This tutorial covers advanced agent configuration techniques including memory systems, custom reasoning loops, delegation patterns, performance optimization, and specialized agent behaviors.
9
+ Every option here is a keyword argument to `RCrewAI::Agent.new`. All of them are
10
+ optional, and an agent behaves sensibly without them.
10
11
 
11
12
  ## Table of Contents
12
- 1. [Agent Memory Systems](#agent-memory-systems)
13
- 2. [Custom Reasoning Loops](#custom-reasoning-loops)
14
- 3. [Manager Agents and Delegation](#manager-agents-and-delegation)
15
- 4. [Performance Optimization](#performance-optimization)
16
- 5. [Specialized Agent Behaviors](#specialized-agent-behaviors)
17
- 6. [Agent Communication Patterns](#agent-communication-patterns)
18
- 7. [Error Handling and Recovery](#error-handling-and-recovery)
19
-
20
- ## Agent Memory Systems
21
-
22
- Agents in RCrewAI have sophisticated memory systems that allow them to learn and improve over time.
23
-
24
- ### Short-term and Long-term Memory
13
+ 1. [A Model per Agent](#a-model-per-agent)
14
+ 2. [Memory](#memory)
15
+ 3. [Reasoning](#reasoning)
16
+ 4. [Limits: Iterations, Rate, and Context](#limits-iterations-rate-and-context)
17
+ 5. [Concurrent Tool Calls](#concurrent-tool-calls)
18
+ 6. [Human Approval](#human-approval)
19
+ 7. [Managers and Delegation](#managers-and-delegation)
20
+ 8. [Subclassing Agent](#subclassing-agent)
21
+ 9. [Handling Failure](#handling-failure)
22
+ 10. [Best Practices](#best-practices)
23
+
24
+ ## A Model per Agent
25
+
26
+ By default an agent uses the global configuration. Pass `llm:` to give one agent
27
+ its own provider or model, for example a stronger model for planning and a
28
+ cheaper one for bulk work:
25
29
 
26
30
  ```ruby
27
31
  require 'rcrewai'
28
32
 
29
- # Create agent with enhanced memory capabilities
30
- analyst = RCrewAI::Agent.new(
31
- name: "data_analyst",
32
- role: "Senior Data Analyst",
33
- goal: "Analyze data patterns and learn from past analyses",
34
- backstory: "Expert analyst who improves with each analysis",
35
- verbose: true
33
+ RCrewAI.configure do |config|
34
+ config.llm_provider = :openai
35
+ config.model = 'gpt-4o'
36
+ end
37
+
38
+ reviewer = RCrewAI::Agent.new(
39
+ name: 'reviewer',
40
+ role: 'Principal Engineer',
41
+ goal: 'Find defects before they ship',
42
+ llm: { provider: :anthropic, model: 'claude-opus-5-5' }
36
43
  )
37
44
 
38
- # Memory is automatically created and managed
39
- memory = analyst.memory
45
+ # Provider and model only, using that provider's configured key.
46
+ summarizer = RCrewAI::Agent.new(
47
+ name: 'summarizer',
48
+ role: 'Technical Writer',
49
+ goal: 'Summarize findings',
50
+ llm: { provider: :openai, model: 'gpt-4o-mini' }
51
+ )
52
+ ```
40
53
 
41
- # After task execution, memory stores:
42
- # - Successful patterns and strategies
43
- # - Tool usage that worked well
44
- # - Context that led to good results
45
- # - Failed approaches to avoid
54
+ `llm:` accepts a provider symbol, a hash (`provider:`, `model:`, `api_key:`,
55
+ `temperature:`), or any object that responds to `chat`. Overrides never change
56
+ the global configuration. An agent that switches provider doesn't inherit a
57
+ global `config.model`: it uses its own provider's model.
46
58
 
47
- # Access memory statistics
48
- stats = memory.stats
49
- puts "Total executions: #{stats[:total_executions]}"
50
- puts "Success rate: #{stats[:success_rate]}%"
51
- puts "Most used tools: #{stats[:top_tools]}"
52
- puts "Average execution time: #{stats[:avg_execution_time]}s"
59
+ **Temperature.** Current Claude models reject `temperature`, so the Anthropic
60
+ client only sends one you set. If you set a global `config.temperature`, clear it
61
+ for a Claude agent with `llm: { provider: :anthropic, temperature: nil }`.
53
62
 
54
- # Memory influences future reasoning
55
- # Agent will prefer successful patterns from memory
56
- ```
63
+ ## Memory
57
64
 
58
- ### Custom Memory Persistence
65
+ Every agent has a memory, with nothing to configure. It records each task, and
66
+ later tasks recall relevant earlier work:
59
67
 
60
68
  ```ruby
61
- class PersistentMemoryAgent < RCrewAI::Agent
62
- def initialize(**options)
63
- super
64
- load_memory_from_storage
65
- end
66
-
67
- def execute_task(task)
68
- result = super
69
- save_memory_to_storage
70
- result
71
- end
72
-
73
- private
74
-
75
- def load_memory_from_storage
76
- if File.exist?("#{name}_memory.json")
77
- memory_data = JSON.parse(File.read("#{name}_memory.json"))
78
- @memory.restore(memory_data)
79
- end
80
- end
81
-
82
- def save_memory_to_storage
83
- File.write("#{name}_memory.json", @memory.to_json)
84
- end
85
- end
69
+ analyst = RCrewAI::Agent.new(name: 'analyst', role: 'Analyst', goal: 'Find trends')
86
70
 
87
- # Agent that remembers across sessions
88
- persistent_agent = PersistentMemoryAgent.new(
89
- name: "persistent_researcher",
90
- role: "Research Specialist",
91
- goal: "Build knowledge over time"
92
- )
71
+ analyst.memory.stats
72
+ # => { short_term_count: 0, long_term_total: 0, entity_count: 0, tool_usage_count: 0 }
93
73
  ```
94
74
 
95
- ### Memory-Enhanced Learning
75
+ By default memory lives in the process and is gone when it exits. Add an embedder
76
+ for semantic recall, and a store to survive restarts:
96
77
 
97
78
  ```ruby
98
- # Create a learning agent that improves over time
99
- learning_agent = RCrewAI::Agent.new(
100
- name: "learning_assistant",
101
- role: "Adaptive Assistant",
102
- goal: "Learn from each interaction to provide better assistance",
103
- backstory: "An AI that continuously improves through experience",
104
- tools: [RCrewAI::Tools::WebSearch.new, RCrewAI::Tools::FileWriter.new]
79
+ persistent = RCrewAI::Agent.new(
80
+ name: 'researcher',
81
+ role: 'Researcher',
82
+ goal: 'Build on earlier findings',
83
+ memory: {
84
+ store: RCrewAI::Memory::SqliteStore.new(path: 'researcher_memory.db'),
85
+ # embedder: RCrewAI::Knowledge::Embedder.new, # semantic recall; calls an embeddings API
86
+ short_term_limit: 200
87
+ }
105
88
  )
106
-
107
- # Track performance over multiple executions
108
- 10.times do |i|
109
- task = RCrewAI::Task.new(
110
- name: "research_task_#{i}",
111
- description: "Research topic #{i}",
112
- agent: learning_agent
113
- )
114
-
115
- result = task.execute
116
-
117
- # Agent automatically learns:
118
- # - Which search queries work best
119
- # - How to structure research
120
- # - Optimal tool usage patterns
121
-
122
- puts "Iteration #{i}: Success=#{task.status == :completed}"
123
- end
124
-
125
- # Check improvement
126
- puts "Learning progress: #{learning_agent.memory.learning_curve}"
127
89
  ```
128
90
 
129
- ## Custom Reasoning Loops
91
+ Memory is scoped to the agent's name, so agents can share a store without reading
92
+ each other's records. Pass `scope: 'shared'` when they should. See the
93
+ [Cognitive Memory tutorial]({{ site.baseurl }}/tutorials/memory) for memory types
94
+ and entity extraction.
130
95
 
131
- Advanced agents can have customized reasoning processes for specialized tasks.
96
+ ## Reasoning
132
97
 
133
- ### Custom Reasoning Agent
98
+ With `reasoning: true`, the agent writes a short plan before it answers, at the
99
+ cost of one extra LLM call per task. The plan feeds the answer and is returned
100
+ alongside it rather than mixed into `task.result`:
134
101
 
135
102
  ```ruby
136
- class AnalyticalReasoningAgent < RCrewAI::Agent
137
- def reasoning_loop(task, context)
138
- iteration = 0
139
- hypotheses = []
140
-
141
- loop do
142
- iteration += 1
143
-
144
- # Phase 1: Generate hypotheses
145
- if iteration == 1
146
- hypotheses = generate_hypotheses(task, context)
147
- @logger.info "Generated #{hypotheses.length} hypotheses"
148
- end
149
-
150
- # Phase 2: Test hypotheses
151
- if iteration > 1 && iteration <= hypotheses.length + 1
152
- hypothesis = hypotheses[iteration - 2]
153
- result = test_hypothesis(hypothesis, context)
154
-
155
- if result[:valid]
156
- return formulate_conclusion(hypothesis, result)
157
- end
158
- end
159
-
160
- # Phase 3: Synthesize findings
161
- if iteration > hypotheses.length + 1
162
- return synthesize_findings(hypotheses, context)
163
- end
164
-
165
- break if iteration > max_iterations
166
- end
167
- end
168
-
169
- private
170
-
171
- def generate_hypotheses(task, context)
172
- prompt = build_hypothesis_prompt(task, context)
173
- response = llm_client.chat(messages: [{ role: 'user', content: prompt }])
174
- parse_hypotheses(response[:content])
175
- end
176
-
177
- def test_hypothesis(hypothesis, context)
178
- # Use tools to validate hypothesis
179
- if tools.any? { |t| t.name == 'websearch' }
180
- evidence = use_tool('websearch', query: hypothesis[:query])
181
- { valid: evidence.include?(hypothesis[:expected]), evidence: evidence }
182
- else
183
- { valid: false, evidence: nil }
184
- end
185
- end
186
-
187
- def formulate_conclusion(hypothesis, result)
188
- "Conclusion: #{hypothesis[:statement]} is supported by evidence: #{result[:evidence]}"
189
- end
190
-
191
- def synthesize_findings(hypotheses, context)
192
- "Unable to validate hypotheses. Best assessment based on available data..."
193
- end
194
- end
195
-
196
- # Use the analytical reasoning agent
197
- analyst = AnalyticalReasoningAgent.new(
198
- name: "hypothesis_tester",
199
- role: "Scientific Analyst",
200
- goal: "Test hypotheses systematically",
201
- tools: [RCrewAI::Tools::WebSearch.new]
103
+ planner = RCrewAI::Agent.new(
104
+ name: 'planner',
105
+ role: 'Solutions Architect',
106
+ goal: 'Design migration plans',
107
+ reasoning: true,
108
+ max_reasoning_attempts: 3 # retries only if the model returns an empty plan
202
109
  )
203
- ```
204
110
 
205
- ### Multi-Stage Reasoning
111
+ task = RCrewAI::Task.new(name: 'plan', description: 'Plan a database migration', agent: planner)
206
112
 
207
- ```ruby
208
- class MultiStageReasoningAgent < RCrewAI::Agent
209
- REASONING_STAGES = [
210
- :understand,
211
- :analyze,
212
- :plan,
213
- :execute,
214
- :verify,
215
- :conclude
216
- ]
217
-
218
- def reasoning_loop(task, context)
219
- current_stage_index = 0
220
- stage_results = {}
221
-
222
- while current_stage_index < REASONING_STAGES.length
223
- stage = REASONING_STAGES[current_stage_index]
224
-
225
- @logger.info "Reasoning stage: #{stage}"
226
-
227
- result = case stage
228
- when :understand
229
- understand_requirements(task, context)
230
- when :analyze
231
- analyze_problem(task, context, stage_results[:understand])
232
- when :plan
233
- create_action_plan(stage_results[:analyze])
234
- when :execute
235
- execute_plan(stage_results[:plan])
236
- when :verify
237
- verify_results(stage_results[:execute])
238
- when :conclude
239
- formulate_conclusion(stage_results)
240
- end
241
-
242
- stage_results[stage] = result
243
-
244
- # Allow stage retry on failure
245
- if result[:success]
246
- current_stage_index += 1
247
- elsif result[:retry]
248
- @logger.info "Retrying stage: #{stage}"
249
- else
250
- break
251
- end
252
- end
253
-
254
- stage_results[:conclude] || "Reasoning incomplete"
255
- end
256
- end
113
+ result = planner.execute_task(task)
114
+ result[:reasoning] # the plan
115
+ result[:content] # the answer
257
116
  ```
258
117
 
259
- ## Manager Agents and Delegation
260
-
261
- Manager agents coordinate teams and delegate tasks intelligently.
118
+ If planning fails, or every attempt comes back empty, the agent carries on
119
+ without a plan.
262
120
 
263
- ### Creating a Manager Agent
121
+ ## Limits: Iterations, Rate, and Context
264
122
 
265
123
  ```ruby
266
- # Create a manager with delegation capabilities
267
- manager = RCrewAI::Agent.new(
268
- name: "team_manager",
269
- role: "Engineering Manager",
270
- goal: "Coordinate team to deliver projects efficiently",
271
- backstory: "Experienced manager who knows how to leverage team strengths",
272
- manager: true, # Mark as manager
273
- allow_delegation: true, # Enable delegation
274
- tools: [RCrewAI::Tools::FileWriter.new], # Manager tools
275
- verbose: true
276
- )
277
-
278
- # Create specialist team members
279
- backend_dev = RCrewAI::Agent.new(
280
- name: "backend_developer",
281
- role: "Backend Engineer",
282
- goal: "Build robust backend systems",
283
- tools: [RCrewAI::Tools::FileWriter.new]
284
- )
285
-
286
- frontend_dev = RCrewAI::Agent.new(
287
- name: "frontend_developer",
288
- role: "Frontend Engineer",
289
- goal: "Create excellent user interfaces",
290
- tools: [RCrewAI::Tools::FileWriter.new]
124
+ bounded = RCrewAI::Agent.new(
125
+ name: 'bounded',
126
+ role: 'Support Engineer',
127
+ goal: 'Resolve tickets',
128
+ max_iterations: 5, # LLM turns per task (default 10)
129
+ max_rpm: 30, # LLM calls per minute for this agent, thread-safe
130
+ respect_context_window: true # drop the oldest messages to fit the model's window
291
131
  )
132
+ ```
292
133
 
293
- qa_engineer = RCrewAI::Agent.new(
294
- name: "qa_engineer",
295
- role: "QA Engineer",
296
- goal: "Ensure software quality",
297
- tools: [RCrewAI::Tools::FileReader.new]
298
- )
134
+ `respect_context_window` looks up the window for known models and always keeps the
135
+ system prompt and the latest message.
299
136
 
300
- # Build team hierarchy
301
- manager.add_subordinate(backend_dev)
302
- manager.add_subordinate(frontend_dev)
303
- manager.add_subordinate(qa_engineer)
137
+ ## Concurrent Tool Calls
304
138
 
305
- # Manager will automatically delegate tasks to appropriate team members
306
- ```
139
+ When a model asks for several tools in one turn, they run at the same time, so the
140
+ turn costs the slowest call rather than the sum. Results stay in the order the
141
+ model asked for them, and up to 8 run at once.
307
142
 
308
- ### Advanced Delegation Strategies
143
+ Turn this off for an agent whose tools share state that isn't thread-safe, or that
144
+ call a rate-limited API:
309
145
 
310
146
  ```ruby
311
- class StrategicManager < RCrewAI::Agent
312
- def delegate_task(task, target_agent = nil)
313
- if target_agent.nil?
314
- # Intelligent agent selection based on multiple factors
315
- target_agent = select_best_agent(task)
316
- end
317
-
318
- # Create delegation context with strategic guidance
319
- delegation_context = {
320
- priority: assess_priority(task),
321
- deadline: calculate_deadline(task),
322
- resources: allocate_resources(task),
323
- success_criteria: define_success_criteria(task),
324
- escalation_path: define_escalation(task)
325
- }
326
-
327
- # Enhanced delegation with context
328
- @logger.info "Delegating #{task.name} to #{target_agent.name}"
329
- @logger.info "Context: #{delegation_context}"
330
-
331
- super(task, target_agent)
332
- end
333
-
334
- private
335
-
336
- def select_best_agent(task)
337
- # Score each subordinate for task fit
338
- scores = subordinates.map do |agent|
339
- score = 0
340
-
341
- # Factor 1: Role match
342
- role_match = calculate_role_match(task, agent)
343
- score += role_match * 0.4
344
-
345
- # Factor 2: Current workload
346
- workload = assess_workload(agent)
347
- score += (1.0 - workload) * 0.3
348
-
349
- # Factor 3: Past performance
350
- performance = agent.memory.stats[:success_rate] || 0.5
351
- score += performance * 0.2
352
-
353
- # Factor 4: Tool availability
354
- tool_match = calculate_tool_match(task, agent)
355
- score += tool_match * 0.1
356
-
357
- { agent: agent, score: score }
358
- end
359
-
360
- # Select highest scoring agent
361
- best = scores.max_by { |s| s[:score] }
362
- best[:agent]
363
- end
364
-
365
- def calculate_role_match(task, agent)
366
- task_keywords = extract_keywords(task.description)
367
- role_keywords = extract_keywords(agent.role)
368
-
369
- common = (task_keywords & role_keywords).length
370
- total = [task_keywords.length, role_keywords.length].max
371
-
372
- common.to_f / total
373
- end
374
-
375
- def assess_workload(agent)
376
- # Return workload between 0 (idle) and 1 (overloaded)
377
- active_tasks = @delegated_tasks[agent.name] || []
378
- active_tasks.count { |t| t.status == :running } / 5.0
379
- end
380
- end
147
+ sequential = RCrewAI::Agent.new(
148
+ name: 'db_writer',
149
+ role: 'Database Operator',
150
+ goal: 'Apply changes one at a time',
151
+ parallel_tools: false
152
+ )
381
153
  ```
382
154
 
383
- ### Cross-Team Coordination
155
+ This applies when the model uses native function calling. The older text-based
156
+ runner, used for models without native tools, always runs one tool at a time.
384
157
 
385
- ```ruby
386
- # Multiple managers coordinating
387
- engineering_manager = RCrewAI::Agent.new(
388
- name: "eng_manager",
389
- role: "Engineering Manager",
390
- manager: true,
391
- allow_delegation: true
392
- )
158
+ ## Human Approval
393
159
 
394
- product_manager = RCrewAI::Agent.new(
395
- name: "product_manager",
396
- role: "Product Manager",
397
- manager: true,
398
- allow_delegation: true
399
- )
400
-
401
- # Managers can coordinate through shared context
402
- shared_context = {
403
- project_goals: "Launch new feature by Q2",
404
- constraints: "Limited to 3 engineers",
405
- priorities: ["Performance", "User Experience", "Security"]
406
- }
407
-
408
- # Create tasks that require cross-team coordination
409
- feature_task = RCrewAI::Task.new(
410
- name: "new_feature",
411
- description: "Implement new dashboard feature",
412
- context_data: shared_context
160
+ ```ruby
161
+ supervised = RCrewAI::Agent.new(
162
+ name: 'operator',
163
+ role: 'Production Operator',
164
+ goal: 'Make careful changes',
165
+ human_input: true,
166
+ require_approval_for_tools: true,
167
+ require_approval_for_final_answer: true
413
168
  )
414
-
415
- # Both managers will coordinate their teams
416
169
  ```
417
170
 
418
- ## Performance Optimization
171
+ These prompts read from the terminal, so they suit attended runs rather than
172
+ background jobs. The [human-in-the-loop example]({{ site.baseurl }}/examples/human-in-the-loop)
173
+ covers the task-level options too.
419
174
 
420
- Optimize agent performance for production workloads.
175
+ ## Managers and Delegation
421
176
 
422
- ### Parallel Agent Execution
177
+ In a hierarchical crew, a manager coordinates the other agents:
423
178
 
424
179
  ```ruby
425
- # Configure agents for parallel execution
426
- fast_researcher = RCrewAI::Agent.new(
427
- name: "fast_researcher",
428
- role: "Research Specialist",
429
- goal: "Quickly gather information",
430
- max_iterations: 3, # Limit iterations
431
- max_execution_time: 60, # 1 minute timeout
432
- tools: [RCrewAI::Tools::WebSearch.new(timeout: 10)] # Fast timeout
180
+ manager = RCrewAI::Agent.new(
181
+ name: 'team_manager',
182
+ role: 'Engineering Manager',
183
+ goal: 'Coordinate the team to deliver projects',
184
+ manager: true,
185
+ allow_delegation: true
433
186
  )
434
187
 
435
- # Create parallel tasks
436
- parallel_tasks = 5.times.map do |i|
437
- RCrewAI::Task.new(
438
- name: "research_#{i}",
439
- description: "Research topic #{i}",
440
- agent: fast_researcher,
441
- async: true # Mark for async execution
442
- )
443
- end
188
+ backend = RCrewAI::Agent.new(name: 'backend', role: 'Backend Engineer', goal: 'Build reliable APIs')
189
+ qa = RCrewAI::Agent.new(name: 'qa', role: 'QA Engineer', goal: 'Verify software quality')
444
190
 
445
- # Execute in parallel
446
- crew = RCrewAI::Crew.new("parallel_crew")
447
- crew.add_agent(fast_researcher)
448
- parallel_tasks.each { |t| crew.add_task(t) }
191
+ crew = RCrewAI::Crew.new('delivery', process: :hierarchical)
192
+ [manager, backend, qa].each { |agent| crew.add_agent(agent) }
449
193
 
450
- results = crew.execute(async: true, max_concurrency: 5)
451
- ```
194
+ # Assigned explicitly.
195
+ crew.add_task(RCrewAI::Task.new(name: 'api', description: 'Build the orders API', agent: backend))
452
196
 
453
- ### Resource-Optimized Agents
197
+ # No agent: matched to the best subordinate by comparing the description with
198
+ # each agent's role and goal.
199
+ crew.add_task(RCrewAI::Task.new(name: 'verify', description: 'Verify software quality of the API'))
454
200
 
455
- ```ruby
456
- class ResourceOptimizedAgent < RCrewAI::Agent
457
- def initialize(**options)
458
- super
459
- @resource_monitor = ResourceMonitor.new
460
- end
461
-
462
- def execute_task(task)
463
- # Check resources before execution
464
- if @resource_monitor.memory_usage > 0.8
465
- @logger.warn "High memory usage, optimizing..."
466
- optimize_memory
467
- end
468
-
469
- # Use chunked processing for large tasks
470
- if task.estimated_size > 1_000_000
471
- execute_chunked(task)
472
- else
473
- super
474
- end
475
- end
476
-
477
- private
478
-
479
- def execute_chunked(task)
480
- chunks = split_task(task)
481
- results = []
482
-
483
- chunks.each_with_index do |chunk, i|
484
- @logger.info "Processing chunk #{i+1}/#{chunks.length}"
485
-
486
- # Process chunk with resource limits
487
- result = with_resource_limits do
488
- process_chunk(chunk)
489
- end
490
-
491
- results << result
492
-
493
- # Clear memory between chunks
494
- GC.start if i % 5 == 0
495
- end
496
-
497
- merge_results(results)
498
- end
499
-
500
- def with_resource_limits(&block)
501
- Thread.new do
502
- Thread.current[:memory_limit] = 100_000_000 # 100MB
503
- Thread.current[:time_limit] = 30 # 30 seconds
504
-
505
- Timeout::timeout(Thread.current[:time_limit]) do
506
- yield
507
- end
508
- end.value
509
- end
510
- end
201
+ results = crew.execute
511
202
  ```
512
203
 
513
- ### Caching and Memoization
514
-
515
- ```ruby
516
- class CachedAgent < RCrewAI::Agent
517
- def initialize(**options)
518
- super
519
- @cache = {}
520
- @cache_ttl = options[:cache_ttl] || 3600 # 1 hour default
521
- end
522
-
523
- def use_tool(tool_name, **params)
524
- cache_key = "#{tool_name}_#{params.hash}"
525
-
526
- # Check cache first
527
- if cached = get_cached(cache_key)
528
- @logger.info "Cache hit for #{tool_name}"
529
- return cached
530
- end
531
-
532
- # Execute and cache
533
- result = super
534
- set_cached(cache_key, result)
535
- result
536
- end
537
-
538
- private
539
-
540
- def get_cached(key)
541
- return nil unless @cache[key]
542
-
543
- entry = @cache[key]
544
- if Time.now - entry[:time] < @cache_ttl
545
- entry[:value]
546
- else
547
- @cache.delete(key)
548
- nil
549
- end
550
- end
551
-
552
- def set_cached(key, value)
553
- @cache[key] = {
554
- value: value,
555
- time: Time.now
556
- }
557
-
558
- # Limit cache size
559
- if @cache.size > 100
560
- oldest = @cache.min_by { |k, v| v[:time] }
561
- @cache.delete(oldest[0])
562
- end
563
- end
564
- end
565
- ```
204
+ The manager is the first agent with `manager: true`, otherwise the first with
205
+ `allow_delegation: true`. If the crew has neither, RCrewAI adds a default
206
+ `crew_manager`. A hierarchical crew needs at least one other agent and one task,
207
+ or it raises `RCrewAI::Process::ProcessError`.
566
208
 
567
- ## Specialized Agent Behaviors
209
+ Matching by description is a simple keyword comparison, so assign `agent:` yourself
210
+ whenever the choice matters.
568
211
 
569
- Create agents with specialized behaviors for specific use cases.
212
+ ## Subclassing Agent
570
213
 
571
- ### Research Specialist Agent
214
+ Most needs are covered by the options above, but you can subclass `Agent` to wrap
215
+ execution. Keep the full `execute_task` signature, because the crew passes `stream:`
216
+ to it. An override declared as `def execute_task(task)` fails with
217
+ `wrong number of arguments`.
572
218
 
573
219
  ```ruby
574
- class ResearchSpecialistAgent < RCrewAI::Agent
575
- def initialize(**options)
576
- super(options.merge(
577
- tools: [
578
- RCrewAI::Tools::WebSearch.new(max_results: 20),
579
- RCrewAI::Tools::FileWriter.new,
580
- RCrewAI::Tools::FileReader.new
581
- ]
582
- ))
583
-
584
- @research_depth = options[:research_depth] || 3
585
- @citation_style = options[:citation_style] || :apa
586
- end
587
-
588
- def execute_task(task)
589
- # Enhanced research methodology
590
- research_plan = create_research_plan(task)
591
- sources = gather_sources(research_plan)
592
- validated_sources = validate_sources(sources)
593
- synthesis = synthesize_findings(validated_sources)
594
-
595
- # Format with citations
596
- format_research_output(synthesis, validated_sources)
597
- end
598
-
599
- private
600
-
601
- def create_research_plan(task)
602
- {
603
- primary_queries: extract_key_topics(task.description),
604
- secondary_queries: generate_related_queries(task.description),
605
- depth_level: @research_depth,
606
- quality_threshold: 0.7
607
- }
608
- end
609
-
610
- def gather_sources(plan)
611
- sources = []
612
-
613
- # Primary research
614
- plan[:primary_queries].each do |query|
615
- results = use_tool('websearch', query: query, max_results: 10)
616
- sources.concat(parse_search_results(results))
617
- end
618
-
619
- # Deep research for important topics
620
- if @research_depth > 1
621
- plan[:secondary_queries].each do |query|
622
- results = use_tool('websearch', query: query, max_results: 5)
623
- sources.concat(parse_search_results(results))
624
- end
625
- end
626
-
627
- sources
628
- end
629
-
630
- def validate_sources(sources)
631
- sources.select do |source|
632
- score = calculate_source_credibility(source)
633
- score > 0.5
634
- end
635
- end
636
-
637
- def format_research_output(content, sources)
638
- output = "# Research Report\n\n"
639
- output += content
640
- output += "\n\n## References\n\n"
641
-
642
- sources.each_with_index do |source, i|
643
- output += format_citation(source, i + 1)
644
- end
645
-
646
- output
220
+ class TimedAgent < RCrewAI::Agent
221
+ def execute_task(task, stream: nil, **opts)
222
+ started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
223
+ super
224
+ ensure
225
+ elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
226
+ warn "#{name} spent #{elapsed.round(2)}s on #{task.name}"
647
227
  end
648
228
  end
649
- ```
650
-
651
- ### Code Review Agent
652
229
 
653
- ```ruby
654
- class CodeReviewAgent < RCrewAI::Agent
655
- REVIEW_CATEGORIES = [
656
- :syntax,
657
- :style,
658
- :security,
659
- :performance,
660
- :maintainability,
661
- :testing
662
- ]
663
-
664
- def initialize(**options)
665
- super(options.merge(
666
- role: "Senior Code Reviewer",
667
- goal: "Ensure code quality and best practices"
668
- ))
669
-
670
- @review_strictness = options[:strictness] || :medium
671
- @languages = options[:languages] || [:ruby, :python, :javascript]
672
- end
673
-
674
- def review_code(code, language = :ruby)
675
- review_results = {}
676
-
677
- REVIEW_CATEGORIES.each do |category|
678
- review_results[category] = review_category(code, category, language)
679
- end
680
-
681
- generate_review_report(review_results, code)
682
- end
683
-
684
- private
685
-
686
- def review_category(code, category, language)
687
- case category
688
- when :syntax
689
- check_syntax(code, language)
690
- when :style
691
- check_style_compliance(code, language)
692
- when :security
693
- security_scan(code)
694
- when :performance
695
- analyze_performance(code)
696
- when :maintainability
697
- assess_maintainability(code)
698
- when :testing
699
- check_test_coverage(code)
700
- end
701
- end
702
-
703
- def generate_review_report(results, code)
704
- report = "## Code Review Report\n\n"
705
-
706
- # Overall score
707
- overall_score = calculate_overall_score(results)
708
- report += "**Overall Score: #{overall_score}/10**\n\n"
709
-
710
- # Category breakdown
711
- results.each do |category, findings|
712
- report += "### #{category.to_s.capitalize}\n"
713
- report += format_findings(findings)
714
- report += "\n"
715
- end
716
-
717
- # Recommendations
718
- report += "### Recommendations\n"
719
- report += generate_recommendations(results)
720
-
721
- report
722
- end
723
- end
230
+ timed = TimedAgent.new(name: 'timed', role: 'Analyst', goal: 'Analyze data')
724
231
  ```
725
232
 
726
- ## Agent Communication Patterns
233
+ For observing a run without subclassing, prefer streaming events
234
+ (`crew.execute(stream: ...)`) or LLM interceptors.
727
235
 
728
- Enable sophisticated communication between agents.
236
+ ## Handling Failure
729
237
 
730
- ### Message Passing Between Agents
238
+ Failures are handled at the task and crew level:
731
239
 
732
240
  ```ruby
733
- class CommunicatingAgent < RCrewAI::Agent
734
- attr_accessor :message_queue
735
-
736
- def initialize(**options)
737
- super
738
- @message_queue = []
739
- @subscribers = []
740
- end
741
-
742
- def send_message(recipient, message)
743
- if recipient.respond_to?(:receive_message)
744
- recipient.receive_message(self, message)
745
- @logger.info "Sent message to #{recipient.name}: #{message[:type]}"
746
- end
747
- end
748
-
749
- def receive_message(sender, message)
750
- @message_queue << {
751
- from: sender.name,
752
- message: message,
753
- timestamp: Time.now
754
- }
755
-
756
- # Process immediately if high priority
757
- if message[:priority] == :high
758
- process_message(message)
759
- end
760
- end
761
-
762
- def broadcast(message)
763
- @subscribers.each do |subscriber|
764
- send_message(subscriber, message)
765
- end
766
- end
767
-
768
- def subscribe(agent)
769
- @subscribers << agent unless @subscribers.include?(agent)
770
- end
771
-
772
- private
773
-
774
- def process_message(message)
775
- case message[:type]
776
- when :request_help
777
- provide_assistance(message)
778
- when :share_findings
779
- incorporate_findings(message)
780
- when :coordinate
781
- coordinate_action(message)
782
- end
783
- end
784
- end
785
-
786
- # Create communicating agents
787
- lead_analyst = CommunicatingAgent.new(
788
- name: "lead_analyst",
789
- role: "Lead Data Analyst"
790
- )
791
-
792
- junior_analyst = CommunicatingAgent.new(
793
- name: "junior_analyst",
794
- role: "Junior Analyst"
241
+ writer = RCrewAI::Agent.new(name: 'writer', role: 'Writer', goal: 'Write summaries')
242
+
243
+ draft = RCrewAI::Task.new(
244
+ name: 'draft',
245
+ description: 'Write a summary',
246
+ agent: writer,
247
+ max_retries: 2, # re-run after an error (default 2)
248
+ guardrail: lambda { |output| # validate the output, retrying with feedback
249
+ output.length < 2000 ? [true, output] : [false, 'Keep it under 2000 characters']
250
+ }
795
251
  )
796
-
797
- # Set up communication
798
- junior_analyst.subscribe(lead_analyst)
799
-
800
- # Agents can now communicate during execution
801
- junior_analyst.send_message(lead_analyst, {
802
- type: :request_help,
803
- priority: :high,
804
- content: "Need help with statistical analysis"
805
- })
806
252
  ```
807
253
 
808
- ### Collaborative Decision Making
254
+ A tool that raises doesn't fail the task under native function calling: the error
255
+ goes back to the model as the tool's result, so it can try something else. A failed
256
+ task doesn't stop a sequential crew either, so check the outcome:
809
257
 
810
258
  ```ruby
811
- class CollaborativeAgent < RCrewAI::Agent
812
- def make_collaborative_decision(decision_context, collaborators)
813
- # Gather input from all collaborators
814
- inputs = collaborators.map do |agent|
815
- {
816
- agent: agent.name,
817
- opinion: get_agent_opinion(agent, decision_context),
818
- confidence: get_confidence_level(agent, decision_context)
819
- }
820
- end
821
-
822
- # Synthesize decision
823
- synthesize_collaborative_decision(inputs, decision_context)
824
- end
825
-
826
- private
827
-
828
- def get_agent_opinion(agent, context)
829
- # Request opinion from agent
830
- prompt = "Given context: #{context}, what is your recommendation?"
831
-
832
- # Simulate agent providing opinion based on expertise
833
- if agent.respond_to?(:provide_opinion)
834
- agent.provide_opinion(context)
835
- else
836
- "No opinion"
837
- end
838
- end
839
-
840
- def synthesize_collaborative_decision(inputs, context)
841
- # Weight opinions by confidence
842
- weighted_opinions = inputs.map do |input|
843
- {
844
- opinion: input[:opinion],
845
- weight: input[:confidence]
846
- }
847
- end
848
-
849
- # Find consensus or synthesize
850
- if unanimous?(weighted_opinions)
851
- weighted_opinions.first[:opinion]
852
- else
853
- create_consensus(weighted_opinions, context)
854
- end
855
- end
856
- end
857
- ```
259
+ crew = RCrewAI::Crew.new('reporting')
260
+ crew.add_agent(writer)
261
+ crew.add_task(draft)
858
262
 
859
- ## Error Handling and Recovery
860
-
861
- Advanced error handling strategies for robust agent operation.
862
-
863
- ### Graceful Degradation
864
-
865
- ```ruby
866
- class ResilientAgent < RCrewAI::Agent
867
- def execute_task(task)
868
- attempt_with_fallbacks(task)
869
- end
870
-
871
- private
872
-
873
- def attempt_with_fallbacks(task)
874
- strategies = [
875
- -> { execute_with_all_tools(task) },
876
- -> { execute_with_essential_tools(task) },
877
- -> { execute_with_no_tools(task) },
878
- -> { provide_best_effort_response(task) }
879
- ]
880
-
881
- strategies.each_with_index do |strategy, i|
882
- begin
883
- @logger.info "Attempting strategy #{i + 1}"
884
- return strategy.call
885
- rescue => e
886
- @logger.warn "Strategy #{i + 1} failed: #{e.message}"
887
- next
888
- end
889
- end
890
-
891
- "Unable to complete task after all strategies"
892
- end
893
-
894
- def execute_with_essential_tools(task)
895
- # Disable non-essential tools
896
- essential_tools = tools.select { |t| t.essential? }
897
- with_tools(essential_tools) do
898
- super(task)
899
- end
900
- end
901
-
902
- def execute_with_no_tools(task)
903
- # Pure reasoning without tools
904
- with_tools([]) do
905
- super(task)
906
- end
907
- end
908
- end
263
+ results = crew.execute
264
+ warn "#{results[:failed_tasks]} task(s) failed" if results[:failed_tasks].positive?
909
265
  ```
910
266
 
911
- ### Self-Healing Agents
912
-
913
- ```ruby
914
- class SelfHealingAgent < RCrewAI::Agent
915
- def initialize(**options)
916
- super
917
- @health_monitor = HealthMonitor.new(self)
918
- @recovery_strategies = {}
919
- end
920
-
921
- def execute_task(task)
922
- @health_monitor.check_health
923
-
924
- begin
925
- result = super
926
- @health_monitor.record_success
927
- result
928
- rescue => e
929
- @health_monitor.record_failure(e)
930
-
931
- if @health_monitor.needs_healing?
932
- perform_self_healing
933
- retry
934
- else
935
- raise
936
- end
937
- end
938
- end
939
-
940
- private
941
-
942
- def perform_self_healing
943
- @logger.info "Performing self-healing procedures"
944
-
945
- # Clear corrupted memory
946
- if @health_monitor.memory_corrupted?
947
- @memory.clear_corrupted_entries
948
- end
949
-
950
- # Reset tool connections
951
- if @health_monitor.tools_failing?
952
- reset_tool_connections
953
- end
954
-
955
- # Adjust parameters
956
- if @health_monitor.performance_degraded?
957
- optimize_parameters
958
- end
959
-
960
- @health_monitor.reset
961
- end
962
-
963
- def optimize_parameters
964
- # Dynamically adjust agent parameters
965
- self.max_iterations = [max_iterations - 2, 3].max
966
- self.max_execution_time = max_execution_time * 1.5
967
-
968
- @logger.info "Adjusted parameters for better performance"
969
- end
970
- end
971
- ```
267
+ A failed task also fails any task that depends on it through `context:`. To resume a
268
+ long run without repeating finished work, pass a store to `crew.execute(checkpoint:)`
269
+ and call `crew.resume(run_id)`.
972
270
 
973
271
  ## Best Practices
974
272
 
975
- ### 1. **Agent Design Principles**
976
- - Single Responsibility: Each agent should have one clear role
977
- - Clear Goals: Define specific, measurable goals
978
- - Rich Backstories: Provide context that guides behavior
979
- - Appropriate Tools: Equip agents with necessary tools only
980
-
981
- ### 2. **Performance Guidelines**
982
- - Set reasonable iteration limits (5-10 for most tasks)
983
- - Use timeouts to prevent hanging (60-300 seconds typical)
984
- - Cache expensive operations when possible
985
- - Use async execution for independent tasks
986
-
987
- ### 3. **Memory Management**
988
- - Implement memory cleanup for long-running agents
989
- - Persist valuable memory across sessions
990
- - Limit memory size to prevent bloat
991
- - Use memory statistics for optimization
992
-
993
- ### 4. **Delegation Best Practices**
994
- - Managers should have broad understanding, not deep expertise
995
- - Delegate based on agent strengths and availability
996
- - Provide clear context in delegations
997
- - Monitor delegation success rates
998
-
999
- ### 5. **Error Handling**
1000
- - Implement graceful degradation strategies
1001
- - Log errors with context for debugging
1002
- - Use retry logic with exponential backoff
1003
- - Provide fallback responses
273
+ - **Use specific roles and goals.** They drive the prompt and hierarchical task matching.
274
+ - **Give agents only the tools they need.** Fewer tools means fewer wrong choices.
275
+ - **Set `max_iterations` and `max_rpm` deliberately.** They bound both cost and rate-limit errors.
276
+ - **Reserve expensive models for the agents that need them.** Use `llm:` per agent.
277
+ - **Set `parallel_tools: false` for tools that aren't thread-safe.** Concurrency is on by default.
1004
278
 
1005
279
  ## Next Steps
1006
280
 
1007
- Now that you understand advanced agent configuration:
281
+ - [Custom Tools Development]({{ site.baseurl }}/tutorials/custom-tools)
282
+ - [Advanced Agent & Task Options]({{ site.baseurl }}/tutorials/agent-options)
283
+ - [Working with Multiple Crews]({{ site.baseurl }}/tutorials/multiple-crews)
284
+ - [Production Deployment]({{ site.baseurl }}/tutorials/deployment)
1008
285
 
1009
- 1. Try the [Custom Tools Development]({{ site.baseurl }}/tutorials/custom-tools) tutorial
1010
- 2. Learn about [Working with Multiple Crews]({{ site.baseurl }}/tutorials/multiple-crews)
1011
- 3. Explore [Production Deployment]({{ site.baseurl }}/tutorials/deployment) strategies
1012
- 4. Review [API Documentation]({{ site.baseurl }}/api/) for detailed reference
286
+ ## Next Steps
1013
287
 
1014
- Advanced agents are the key to building sophisticated AI systems that can handle complex, real-world tasks with reliability and efficiency.
288
+ - [LLM Providers]({{ site.baseurl }}/tutorials/providers): set up each provider
289
+ - [Concurrency]({{ site.baseurl }}/tutorials/concurrency): control parallel tool calls
290
+ - [Interceptors and Events]({{ site.baseurl }}/tutorials/interceptors-and-events): see inside a run
291
+ - [Checkpointing]({{ site.baseurl }}/tutorials/checkpointing): resume failed runs