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
@@ -6,7 +6,9 @@ description: Complete guide to deploying RCrewAI applications in production with
6
6
 
7
7
  # Production Deployment
8
8
 
9
- This comprehensive tutorial covers deploying RCrewAI applications to production environments with enterprise-grade reliability, monitoring, scaling, and security. You'll learn containerization, orchestration, monitoring, and operational best practices.
9
+ This tutorial shows one way to run RCrewAI in production: a small web service wrapping your crews, packaged with Docker and run on Kubernetes.
10
+
11
+ RCrewAI is a library, so the gem itself provides only the crews and their configuration. The web app, metrics, logging, tracing, and infrastructure below are example application code for you to adapt. They need their own gems, such as `sinatra`, `puma`, and `prometheus-client`.
10
12
 
11
13
  ## Table of Contents
12
14
  1. [Production Readiness Checklist](#production-readiness-checklist)
@@ -35,7 +37,7 @@ Before deploying to production, ensure your RCrewAI application meets these requ
35
37
  - [ ] Environment-based configuration
36
38
  - [ ] Secrets management implemented
37
39
  - [ ] Resource limits defined
38
- - [ ] Timeout and retry logic configured
40
+ - [ ] Timeouts, `max_retries`, and `max_rpm` set deliberately
39
41
  - [ ] Logging levels appropriate for production
40
42
 
41
43
  ### ✅ Monitoring
@@ -140,7 +142,6 @@ RUN chown -R rcrewai:rcrewai /app
140
142
  USER rcrewai
141
143
 
142
144
  # Environment variables
143
- ENV RAILS_ENV=production
144
145
  ENV RACK_ENV=production
145
146
  ENV BUNDLE_DEPLOYMENT=true
146
147
  ENV BUNDLE_WITHOUT="development:test"
@@ -162,9 +163,99 @@ require 'rcrewai'
162
163
  require 'sinatra'
163
164
  require 'json'
164
165
  require 'logger'
166
+ require 'securerandom'
167
+ require 'time'
165
168
  require 'prometheus/middleware/collector'
166
169
  require 'prometheus/middleware/exporter'
167
170
 
171
+ class ValidationError < StandardError; end
172
+
173
+ # Tasks hold the state of their run, so build a new crew for each request
174
+ # rather than sharing one between threads.
175
+ class CrewRegistry
176
+ def initialize
177
+ @crews = {}
178
+ end
179
+
180
+ def register_crew(name, &builder)
181
+ @crews[name] = builder
182
+ end
183
+
184
+ def get_crew(name)
185
+ builder = @crews[name]
186
+ raise ValidationError, "Crew not found: #{name}" unless builder
187
+ builder.call
188
+ end
189
+
190
+ def crew_exists?(name)
191
+ @crews.key?(name)
192
+ end
193
+
194
+ def crew_count
195
+ @crews.length
196
+ end
197
+
198
+ def register_default_crews
199
+ # Register your production crews here
200
+ register_crew('customer_support') { create_support_crew }
201
+ register_crew('data_analysis') { create_analysis_crew }
202
+ end
203
+
204
+ private
205
+
206
+ def create_support_crew
207
+ crew = RCrewAI::Crew.new("customer_support")
208
+
209
+ support_agent = RCrewAI::Agent.new(
210
+ name: "support_specialist",
211
+ role: "Customer Support Specialist",
212
+ goal: "Provide excellent customer support and resolve issues efficiently",
213
+ tools: [
214
+ RCrewAI::Tools::WebSearch.new(max_results: 5),
215
+ RCrewAI::Tools::FileReader.new
216
+ ]
217
+ )
218
+
219
+ crew.add_agent(support_agent)
220
+
221
+ support_task = RCrewAI::Task.new(
222
+ name: "handle_support_request",
223
+ description: "Handle customer support request with empathy and expertise",
224
+ agent: support_agent,
225
+ expected_output: "Professional support response with clear next steps"
226
+ )
227
+
228
+ crew.add_task(support_task)
229
+ crew
230
+ end
231
+
232
+ def create_analysis_crew
233
+ crew = RCrewAI::Crew.new("data_analysis")
234
+
235
+ analyst = RCrewAI::Agent.new(
236
+ name: "data_analyst",
237
+ role: "Senior Data Analyst",
238
+ goal: "Analyze data and provide actionable insights",
239
+ tools: [
240
+ RCrewAI::Tools::FileReader.new,
241
+ RCrewAI::Tools::WebSearch.new
242
+ ]
243
+ )
244
+
245
+ crew.add_agent(analyst)
246
+
247
+ analysis_task = RCrewAI::Task.new(
248
+ name: "data_analysis",
249
+ description: "Perform comprehensive data analysis and generate insights",
250
+ agent: analyst,
251
+ expected_output: "Detailed analysis report with recommendations"
252
+ )
253
+
254
+ crew.add_task(analysis_task)
255
+ crew
256
+ end
257
+ end
258
+
168
259
  class ProductionRCrewAI < Sinatra::Base
169
260
  configure :production do
170
261
  enable :logging
@@ -177,8 +268,10 @@ class ProductionRCrewAI < Sinatra::Base
177
268
  # Configure RCrewAI for production
178
269
  RCrewAI.configure do |config|
179
270
  config.llm_provider = ENV.fetch('LLM_PROVIDER', 'openai').to_sym
180
- config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
181
- config.temperature = ENV.fetch('LLM_TEMPERATURE', '0.1').to_f
271
+ config.model = ENV.fetch('LLM_MODEL', 'gpt-4o')
272
+ # API keys are read from the provider's environment variable.
273
+ # Current Claude models reject `temperature`: leave this unset for them.
274
+ config.temperature = ENV['LLM_TEMPERATURE'].to_f if ENV['LLM_TEMPERATURE']
182
275
  config.max_tokens = ENV.fetch('LLM_MAX_TOKENS', '4000').to_i
183
276
  config.timeout = ENV.fetch('LLM_TIMEOUT', '60').to_i
184
277
  end
@@ -267,11 +360,10 @@ class ProductionRCrewAI < Sinatra::Base
267
360
 
268
361
  # Check LLM provider connectivity
269
362
  begin
270
- # Quick LLM test
271
- RCrewAI.client.chat(
363
+ # Quick LLM test. This is a billable call, so poll it infrequently.
364
+ RCrewAI::LLMClient.for_provider.chat(
272
365
  messages: [{ role: 'user', content: 'test' }],
273
- max_tokens: 1,
274
- temperature: 0
366
+ max_tokens: 1
275
367
  )
276
368
  checks[:checks][:llm] = { status: 'healthy' }
277
369
  rescue => e
@@ -317,42 +409,46 @@ class ProductionRCrewAI < Sinatra::Base
317
409
  start_time = Time.now
318
410
  execution_id = SecureRandom.uuid
319
411
 
320
- logger.info "Starting execution", {
412
+ logger.info({
413
+ message: 'Starting execution',
321
414
  execution_id: execution_id,
322
415
  crew_name: crew.name,
323
416
  request_id: request_data['request_id']
324
- }
417
+ }.to_json)
325
418
 
326
419
  begin
327
- # Execute crew
328
- result = crew.execute(
329
- timeout: ENV.fetch('EXECUTION_TIMEOUT', '300').to_i,
330
- max_retries: ENV.fetch('MAX_RETRIES', '3').to_i
331
- )
420
+ # Execute crew. Failed tasks are reported in the result, not raised.
421
+ # Inputs reach your before_kickoff hooks, which can add them to task
422
+ # descriptions with task.enrich_description.
423
+ result = crew.execute(inputs: request_data.fetch('inputs', {}))
332
424
 
333
425
  duration = Time.now - start_time
334
426
 
335
- logger.info "Execution completed", {
427
+ logger.info({
428
+ message: 'Execution completed',
336
429
  execution_id: execution_id,
337
430
  duration: duration,
338
431
  success_rate: result[:success_rate]
339
- }
432
+ }.to_json)
340
433
 
341
434
  {
342
435
  execution_id: execution_id,
343
- success: true,
436
+ success: result[:failed_tasks].zero?,
344
437
  duration: duration,
345
- result: result
438
+ success_rate: result[:success_rate],
439
+ # Task objects aren't useful as JSON, so return plain values.
440
+ tasks: result[:results].map { |r| { name: r[:task].name, status: r[:status], result: r[:result] } }
346
441
  }
347
442
 
348
443
  rescue => e
349
444
  duration = Time.now - start_time
350
445
 
351
- logger.error "Execution failed", {
446
+ logger.error({
447
+ message: 'Execution failed',
352
448
  execution_id: execution_id,
353
449
  duration: duration,
354
450
  error: e.message
355
- }
451
+ }.to_json)
356
452
 
357
453
  raise
358
454
  end
@@ -370,98 +466,22 @@ class ProductionRCrewAI < Sinatra::Base
370
466
  end
371
467
  end
372
468
 
373
- class ValidationError < StandardError; end
374
-
375
- class CrewRegistry
376
- def initialize
377
- @crews = {}
378
- end
379
-
380
- def register_crew(name, crew)
381
- @crews[name] = crew
382
- end
383
-
384
- def get_crew(name)
385
- crew = @crews[name]
386
- raise ValidationError, "Crew not found: #{name}" unless crew
387
- crew
388
- end
389
-
390
- def crew_exists?(name)
391
- @crews.key?(name)
392
- end
393
-
394
- def crew_count
395
- @crews.length
396
- end
397
-
398
- def register_default_crews
399
- # Register your production crews here
400
- support_crew = create_support_crew
401
- register_crew('customer_support', support_crew)
402
-
403
- analysis_crew = create_analysis_crew
404
- register_crew('data_analysis', analysis_crew)
405
- end
406
-
407
- private
408
-
409
- def create_support_crew
410
- crew = RCrewAI::Crew.new("customer_support")
411
-
412
- support_agent = RCrewAI::Agent.new(
413
- name: "support_specialist",
414
- role: "Customer Support Specialist",
415
- goal: "Provide excellent customer support and resolve issues efficiently",
416
- tools: [
417
- RCrewAI::Tools::WebSearch.new(max_results: 5),
418
- RCrewAI::Tools::FileReader.new
419
- ]
420
- )
421
-
422
- crew.add_agent(support_agent)
423
-
424
- support_task = RCrewAI::Task.new(
425
- name: "handle_support_request",
426
- description: "Handle customer support request with empathy and expertise",
427
- expected_output: "Professional support response with clear next steps"
428
- )
429
-
430
- crew.add_task(support_task)
431
- crew
432
- end
433
-
434
- def create_analysis_crew
435
- crew = RCrewAI::Crew.new("data_analysis")
436
-
437
- analyst = RCrewAI::Agent.new(
438
- name: "data_analyst",
439
- role: "Senior Data Analyst",
440
- goal: "Analyze data and provide actionable insights",
441
- tools: [
442
- RCrewAI::Tools::FileReader.new,
443
- RCrewAI::Tools::WebSearch.new
444
- ]
445
- )
446
-
447
- crew.add_agent(analyst)
448
-
449
- analysis_task = RCrewAI::Task.new(
450
- name: "data_analysis",
451
- description: "Perform comprehensive data analysis and generate insights",
452
- expected_output: "Detailed analysis report with charts and recommendations"
453
- )
454
-
455
- crew.add_task(analysis_task)
456
- crew
457
- end
469
+ # Start the application
470
+ if __FILE__ == $0
471
+ ProductionRCrewAI.run!(
472
+ host: '0.0.0.0',
473
+ port: ENV.fetch('PORT', 8080).to_i
474
+ )
458
475
  end
476
+ ```
477
+
478
+ The Dockerfile's health check runs a separate script:
459
479
 
460
- # Health check script for Docker
480
+ ```ruby
461
481
  # health_check.rb
482
+ require 'net/http'
483
+
462
484
  begin
463
- require 'net/http'
464
-
465
485
  uri = URI('http://localhost:8080/health')
466
486
  response = Net::HTTP.get_response(uri)
467
487
 
@@ -469,14 +489,6 @@ begin
469
489
  rescue
470
490
  exit 1
471
491
  end
472
-
473
- # Start the application
474
- if __FILE__ == $0
475
- ProductionRCrewAI.run!(
476
- host: '0.0.0.0',
477
- port: ENV.fetch('PORT', 8080).to_i
478
- )
479
- end
480
492
  ```
481
493
 
482
494
  ### Docker Compose for Development
@@ -494,12 +506,11 @@ services:
494
506
  ports:
495
507
  - "8080:8080"
496
508
  environment:
497
- - RAILS_ENV=production
509
+ - RACK_ENV=production
498
510
  - OPENAI_API_KEY=${OPENAI_API_KEY}
499
511
  - LLM_PROVIDER=openai
512
+ - LLM_MODEL=gpt-4o
500
513
  - LLM_TEMPERATURE=0.1
501
- - EXECUTION_TIMEOUT=300
502
- - MAX_RETRIES=3
503
514
  depends_on:
504
515
  - redis
505
516
  - prometheus
@@ -585,7 +596,7 @@ spec:
585
596
  ports:
586
597
  - containerPort: 8080
587
598
  env:
588
- - name: RAILS_ENV
599
+ - name: RACK_ENV
589
600
  value: "production"
590
601
  - name: OPENAI_API_KEY
591
602
  valueFrom:
@@ -598,10 +609,6 @@ spec:
598
609
  value: "openai"
599
610
  - name: LLM_TEMPERATURE
600
611
  value: "0.1"
601
- - name: EXECUTION_TIMEOUT
602
- value: "300"
603
- - name: MAX_RETRIES
604
- value: "3"
605
612
  resources:
606
613
  requests:
607
614
  memory: "256Mi"
@@ -697,10 +704,9 @@ metadata:
697
704
  name: rcrewai-config
698
705
  data:
699
706
  LLM_PROVIDER: "openai"
707
+ LLM_MODEL: "gpt-4o"
700
708
  LLM_TEMPERATURE: "0.1"
701
709
  LLM_MAX_TOKENS: "4000"
702
- EXECUTION_TIMEOUT: "300"
703
- MAX_RETRIES: "3"
704
710
  LOG_LEVEL: "INFO"
705
711
  METRICS_ENABLED: "true"
706
712
  ---
@@ -769,38 +775,25 @@ class ProductionConfig
769
775
  RCrewAI.configure do |config|
770
776
  # LLM Provider Configuration
771
777
  config.llm_provider = ENV.fetch('LLM_PROVIDER', 'openai').to_sym
778
+ config.model = ENV['LLM_MODEL'] if ENV['LLM_MODEL']
772
779
 
780
+ # Keys are read from OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY,
781
+ # and AZURE_OPENAI_API_KEY. Other providers use LLM_API_KEY.
773
782
  case config.llm_provider
774
783
  when :openai
775
- config.openai_api_key = ENV.fetch('OPENAI_API_KEY')
776
784
  config.base_url = ENV['OPENAI_BASE_URL'] # Optional custom endpoint
777
- when :anthropic
778
- config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY')
779
785
  when :azure
780
- config.azure_api_key = ENV.fetch('AZURE_OPENAI_API_KEY')
781
786
  config.base_url = ENV.fetch('AZURE_OPENAI_ENDPOINT')
782
- config.api_version = ENV.fetch('AZURE_API_VERSION', '2023-05-15')
783
- when :google
784
- config.google_api_key = ENV.fetch('GOOGLE_API_KEY')
787
+ config.api_version = ENV.fetch('AZURE_API_VERSION', '2024-10-21')
788
+ when :bedrock
789
+ config.aws_region = ENV.fetch('AWS_REGION')
785
790
  end
786
791
 
787
- # Model Parameters
788
- config.temperature = ENV.fetch('LLM_TEMPERATURE', '0.1').to_f
792
+ # Model Parameters. Current Claude models reject `temperature`, so leave
793
+ # LLM_TEMPERATURE unset for them.
794
+ config.temperature = ENV['LLM_TEMPERATURE'].to_f if ENV['LLM_TEMPERATURE']
789
795
  config.max_tokens = ENV.fetch('LLM_MAX_TOKENS', '4000').to_i
790
796
  config.timeout = ENV.fetch('LLM_TIMEOUT', '60').to_i
791
-
792
- # Production Settings
793
- config.retry_limit = ENV.fetch('LLM_RETRY_LIMIT', '3').to_i
794
- config.retry_delay = ENV.fetch('LLM_RETRY_DELAY', '2').to_i
795
- config.max_concurrent_requests = ENV.fetch('MAX_CONCURRENT_REQUESTS', '10').to_i
796
-
797
- # Logging
798
- config.log_level = ENV.fetch('LOG_LEVEL', 'INFO').upcase
799
- config.structured_logging = ENV.fetch('STRUCTURED_LOGGING', 'true') == 'true'
800
-
801
- # Security
802
- config.validate_ssl = ENV.fetch('VALIDATE_SSL', 'true') == 'true'
803
- config.user_agent = "RCrewAI/#{RCrewAI::VERSION} (Production)"
804
797
  end
805
798
  end
806
799
 
@@ -851,7 +844,7 @@ class VaultClient
851
844
  secret = Vault.logical.read(path)
852
845
  secret&.data
853
846
  rescue Vault::VaultError => e
854
- Rails.logger.error "Vault error: #{e.message}"
847
+ warn "Vault error: #{e.message}"
855
848
  raise
856
849
  end
857
850
 
@@ -871,7 +864,10 @@ class VaultClient
871
864
  ENV['OPENAI_API_KEY'] = new_secrets[:openai_api_key]
872
865
  ENV['ANTHROPIC_API_KEY'] = new_secrets[:anthropic_api_key]
873
866
 
874
- # Reconfigure RCrewAI with new secrets
867
+ # Keys are read from the environment when the configuration is created,
868
+ # so reset it before configuring again. Clients that already exist keep
869
+ # the old configuration until they are rebuilt.
870
+ RCrewAI.reset_configuration!
875
871
  ProductionConfig.configure
876
872
  end
877
873
  end
@@ -887,7 +883,7 @@ Thread.new do
887
883
  begin
888
884
  vault_client.refresh_secrets
889
885
  rescue => e
890
- Rails.logger.error "Secret refresh failed: #{e.message}"
886
+ warn "Secret refresh failed: #{e.message}"
891
887
  end
892
888
  end
893
889
  end
@@ -1051,7 +1047,7 @@ class StructuredLogger
1051
1047
  message: message,
1052
1048
  service: 'rcrewai',
1053
1049
  version: RCrewAI::VERSION,
1054
- environment: ENV.fetch('RAILS_ENV', 'development'),
1050
+ environment: ENV.fetch('RACK_ENV', 'development'),
1055
1051
  process_id: Process.pid,
1056
1052
  thread_id: Thread.current.object_id
1057
1053
  }.merge(context)
@@ -1833,4 +1829,9 @@ echo "Disaster recovery completed"
1833
1829
  - Incident response playbooks
1834
1830
  - Regular performance reviews
1835
1831
 
1836
- This production deployment guide provides a comprehensive foundation for running RCrewAI applications at scale with enterprise-grade reliability, security, and observability.
1832
+ Adapt these examples to your own stack. For observability built into the gem, see streaming events (`crew.execute(stream:)`) and the LLM interceptors. To survive restarts during long runs, see checkpointing (`crew.execute(checkpoint:)` and `crew.resume`).
1833
+
1834
+ ## Related
1835
+
1836
+ - [Checkpointing]({{ site.baseurl }}/tutorials/checkpointing): resume a failed run without repeating finished tasks
1837
+ - [Interceptors and Events]({{ site.baseurl }}/tutorials/interceptors-and-events): send traces and cost data to your monitoring