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
@@ -13,11 +13,13 @@ This tutorial will walk you through installing RCrewAI and creating your first A
13
13
  Before you begin, ensure you have:
14
14
  - Ruby 3.0 or higher installed
15
15
  - Bundler gem installed (`gem install bundler`)
16
- - An API key from one of the supported providers:
17
- - **OpenAI** (recommended for beginners): Get from [platform.openai.com](https://platform.openai.com)
18
- - **Anthropic (Claude)**: Get from [console.anthropic.com](https://console.anthropic.com)
19
- - **Google (Gemini)**: Get from [ai.google.dev](https://ai.google.dev)
20
- - **Azure OpenAI**: Set up through Azure portal
16
+ - Access to a model through one of the supported providers:
17
+ - **OpenAI**: get a key from [platform.openai.com](https://platform.openai.com)
18
+ - **Anthropic (Claude)**: get a key from [console.anthropic.com](https://console.anthropic.com)
19
+ - **Google (Gemini)**: get a key from [ai.google.dev](https://ai.google.dev)
20
+ - **Azure OpenAI**: set up through the Azure portal
21
+ - **Ollama**: runs locally, with no key
22
+ - **Others**: AWS Bedrock, Snowflake Cortex, or any OpenAI-compatible endpoint
21
23
 
22
24
  ## Installation
23
25
 
@@ -45,20 +47,19 @@ gem install rcrewai
45
47
 
46
48
  ## Configuration
47
49
 
48
- RCrewAI supports multiple LLM providers. Choose the one that works best for you:
50
+ Choose a provider. API keys are read from environment variables, and `config.model`
51
+ selects the model.
49
52
 
50
- ### OpenAI (Recommended for beginners)
53
+ ### OpenAI
51
54
 
52
- Set your API key as an environment variable:
53
55
  ```bash
54
56
  export OPENAI_API_KEY="your-openai-key-here"
55
57
  ```
56
58
 
57
- Configure RCrewAI:
58
59
  ```ruby
59
60
  RCrewAI.configure do |config|
60
61
  config.llm_provider = :openai
61
- config.openai_model = 'gpt-4' # or 'gpt-3.5-turbo' for lower cost
62
+ config.model = 'gpt-4o'
62
63
  end
63
64
  ```
64
65
 
@@ -71,7 +72,7 @@ export ANTHROPIC_API_KEY="your-anthropic-key-here"
71
72
  ```ruby
72
73
  RCrewAI.configure do |config|
73
74
  config.llm_provider = :anthropic
74
- config.anthropic_model = 'claude-3-sonnet-20240229'
75
+ config.model = 'claude-opus-5-5'
75
76
  end
76
77
  ```
77
78
 
@@ -84,7 +85,7 @@ export GOOGLE_API_KEY="your-google-key-here"
84
85
  ```ruby
85
86
  RCrewAI.configure do |config|
86
87
  config.llm_provider = :google
87
- config.google_model = 'gemini-pro'
88
+ config.model = 'gemini-3.8-flash'
88
89
  end
89
90
  ```
90
91
 
@@ -92,7 +93,7 @@ end
92
93
 
93
94
  ```bash
94
95
  export AZURE_OPENAI_API_KEY="your-azure-key"
95
- export AZURE_API_VERSION="2023-05-15"
96
+ export AZURE_API_VERSION="2024-10-21"
96
97
  export AZURE_DEPLOYMENT_NAME="your-deployment"
97
98
  ```
98
99
 
@@ -100,7 +101,15 @@ export AZURE_DEPLOYMENT_NAME="your-deployment"
100
101
  RCrewAI.configure do |config|
101
102
  config.llm_provider = :azure
102
103
  config.base_url = "https://your-resource.openai.azure.com/"
103
- config.azure_model = 'gpt-4'
104
+ end
105
+ ```
106
+
107
+ ### Ollama (local)
108
+
109
+ ```ruby
110
+ RCrewAI.configure do |config|
111
+ config.llm_provider = :ollama
112
+ config.model = 'llama3.1' # no API key needed
104
113
  end
105
114
  ```
106
115
 
@@ -117,7 +126,8 @@ require 'rcrewai'
117
126
 
118
127
  # Configure RCrewAI with your chosen provider
119
128
  RCrewAI.configure do |config|
120
- config.llm_provider = :openai # or :anthropic, :google, :azure
129
+ config.llm_provider = :openai
130
+ config.model = 'gpt-4o'
121
131
  # API keys are loaded from environment variables automatically
122
132
  end
123
133
 
@@ -137,8 +147,8 @@ researcher = RCrewAI::Agent.new(
137
147
  goal: "Uncover cutting-edge developments in AI and data science",
138
148
  backstory: "You are a seasoned researcher with a knack for uncovering the latest trends and technologies in AI and data science. You excel at finding reliable sources and extracting key insights.",
139
149
  tools: [RCrewAI::Tools::WebSearch.new], # Can search the web!
140
- verbose: true, # Shows reasoning process
141
- max_iterations: 5 # Limit reasoning loops
150
+ verbose: true, # Logs each step
151
+ max_iterations: 5 # Limit LLM turns per task
142
152
  )
143
153
 
144
154
  # Writer Agent with file writing capabilities
@@ -165,21 +175,22 @@ crew.add_agent(writer)
165
175
  Define tasks with specific outputs and dependencies:
166
176
 
167
177
  ```ruby
168
- # Research Task - Agent will actually search the web!
178
+ # Research Task - The agent can search the web
169
179
  research_task = RCrewAI::Task.new(
170
- name: "research_ai_trends_2024",
171
- description: "Research the latest AI developments and breakthroughs in 2024. Focus on identifying key trends, major companies involved, and potential impacts on different industries.",
180
+ name: "research_ai_trends",
181
+ description: "Research the latest AI developments and breakthroughs. Focus on identifying key trends, major companies involved, and potential impacts on different industries.",
172
182
  agent: researcher,
173
- expected_output: "A comprehensive research report covering: 1) Top 5 AI trends in 2024, 2) Key companies and their innovations, 3) Industry impact analysis, 4) Future predictions",
174
- max_retries: 2 # Retry if web search fails
183
+ expected_output: "A comprehensive research report covering: 1) Top 5 AI trends, 2) Key companies and their innovations, 3) Industry impact analysis, 4) Future predictions",
184
+ max_retries: 2 # Retry if the task raises an error
175
185
  )
176
186
 
177
- # Writing Task - Agent will use research results and save to file!
187
+ # Writing Task - Agent uses the research results, and the output is saved to a file
178
188
  writing_task = RCrewAI::Task.new(
179
189
  name: "write_ai_trends_article",
180
- description: "Write a compelling, informative article about AI trends based on the research. Make it engaging for a tech-savvy audience. Save the final article to a file named 'ai_trends_2024.md'.",
190
+ description: "Write a compelling, informative article about AI trends based on the research. Make it engaging for a tech-savvy audience.",
181
191
  agent: writer,
182
- expected_output: "A well-structured 1000-1500 word article covering the research findings, saved to ai_trends_2024.md file",
192
+ expected_output: "A well-structured 1000-1500 word article covering the research findings",
193
+ output_file: "ai_trends.md", # Writes the result here when the task finishes
183
194
  context: [research_task], # Uses research results as input
184
195
  callback: ->(task, result) { puts "Article completed: #{result.length} characters written!" }
185
196
  )
@@ -197,12 +208,9 @@ Run the crew and monitor the intelligent agents at work:
197
208
  puts "🚀 Starting AI Research Crew..."
198
209
  puts "The agents will now research and write about AI trends!"
199
210
 
200
- # Execute the crew - this will:
201
- # 1. Research agent searches web for AI trends
202
- # 2. Research agent analyzes and summarizes findings
203
- # 3. Writer agent receives research context
204
- # 4. Writer agent creates article and saves to file
211
+ # Runs the tasks in order, passing the research to the writer as context
205
212
  result = crew.execute
213
+ puts "Success rate: #{result[:success_rate]}% (#{result[:completed_tasks]}/#{result[:total_tasks]} tasks)"
206
214
 
207
215
  # Check results and status
208
216
  puts "\n" + "="*50
@@ -220,9 +228,9 @@ puts "Article Preview:"
220
228
  puts writing_task.result[0..200] + "..." if writing_task.result
221
229
 
222
230
  # Check if file was actually created
223
- if File.exist?('ai_trends_2024.md')
224
- puts "\n✅ Article successfully saved to ai_trends_2024.md"
225
- puts "File size: #{File.size('ai_trends_2024.md')} bytes"
231
+ if File.exist?('ai_trends.md')
232
+ puts "\n✅ Article successfully saved to ai_trends.md"
233
+ puts "File size: #{File.size('ai_trends.md')} bytes"
226
234
  else
227
235
  puts "\n❌ Article file not found"
228
236
  end
@@ -235,57 +243,33 @@ puts "Writer memory: #{writer.memory.stats}"
235
243
 
236
244
  ### What Just Happened?
237
245
 
238
- When you run this code with a valid API key, here's what actually happens:
246
+ When you run this code with a valid API key:
239
247
 
240
- 1. **Researcher Agent**:
241
- - Uses reasoning loops to plan the research approach
242
- - Executes web searches using DuckDuckGo
243
- - Analyzes search results to identify key trends
244
- - Synthesizes findings into a comprehensive report
245
- - Stores successful strategies in memory
248
+ 1. **The researcher** gets its task plus its tools. The model decides whether and how
249
+ often to call `web_search`, which uses DuckDuckGo, and writes a report from the results.
250
+ 2. **The writer** gets the researcher's result as context, because the task lists it in
251
+ `context:`, and writes the article. RCrewAI saves the result to `ai_trends.md`
252
+ because of `output_file:`.
253
+ 3. **Each agent** records its work in memory. By default this lasts only as long as the
254
+ process. See [Cognitive Memory]({{ site.baseurl }}/tutorials/memory) to persist it.
246
255
 
247
- 2. **Writer Agent**:
248
- - Receives research findings as context
249
- - Plans article structure and key points
250
- - Creates engaging, well-structured content
251
- - Saves the final article to a markdown file
252
- - Learns from successful writing patterns
253
-
254
- 3. **System Features**:
255
- - Automatic retry if web search fails
256
- - Security controls on file operations
257
- - Memory persistence between executions
258
- - Comprehensive logging and monitoring
256
+ A task that raises an error is retried up to `max_retries` times. If it still fails,
257
+ the crew moves on, and `result[:failed_tasks]` tells you how many failed. Any task that
258
+ depends on a failed one through `context:` fails too.
259
259
 
260
260
  ## Using the CLI
261
261
 
262
- RCrewAI also provides a command-line interface for managing crews:
263
-
264
- ### Create a New Crew
262
+ RCrewAI also installs an `rcrewai` command. Its most useful job today is inspecting
263
+ saved checkpoints with `rcrewai checkpoint list`, `info`, and `delete`.
265
264
 
266
265
  ```bash
267
- $ rcrewai new research_team
268
- Creating new crew: research_team
269
- Crew 'research_team' created successfully!
266
+ $ rcrewai version
267
+ $ rcrewai checkpoint list --dir .rcrewai/checkpoints
270
268
  ```
271
269
 
272
- ### List Available Crews
273
-
274
- ```bash
275
- $ rcrewai list
276
- Available crews:
277
- - research_team
278
- - marketing_crew
279
- - development_crew
280
- ```
281
-
282
- ### Run a Crew
283
-
284
- ```bash
285
- $ rcrewai run --crew research_team
286
- Running crew: research_team
287
- Executing tasks...
288
- ```
270
+ The `new`, `list`, and `run` commands are placeholders. They don't save crew definitions
271
+ between invocations, so `rcrewai run --crew NAME` starts an empty crew, and `rcrewai list`
272
+ prints fixed example names. Define your crews in Ruby, as in this tutorial.
289
273
 
290
274
  ## Working with Tools
291
275
 
@@ -319,20 +303,24 @@ Now that you've created your first crew, explore these topics:
319
303
  - [Advanced Agent Configuration]({{ site.baseurl }}/tutorials/advanced-agents)
320
304
  - [Custom Tools Development]({{ site.baseurl }}/tutorials/custom-tools)
321
305
  - [Working with Multiple Crews]({{ site.baseurl }}/tutorials/multiple-crews)
306
+ - [Cognitive Memory]({{ site.baseurl }}/tutorials/memory)
322
307
  - [Production Deployment]({{ site.baseurl }}/tutorials/deployment)
323
308
 
324
309
  ## Troubleshooting
325
310
 
326
311
  ### Common Issues
327
312
 
328
- **Issue**: "No API key configured"
329
- **Solution**: Ensure your API key is set in the environment variables or configuration file.
313
+ **Issue**: `API key must be set for openai`
314
+ **Solution**: Set the provider's environment variable, such as `OPENAI_API_KEY`, or assign it in `RCrewAI.configure`.
315
+
316
+ **Issue**: A model-not-found error from the provider
317
+ **Solution**: Set `config.model` to a model your account can use. Some built-in defaults are old, and providers retire models over time.
330
318
 
331
- **Issue**: "Agent not found"
332
- **Solution**: Make sure the agent is added to the crew before creating tasks that reference it.
319
+ **Issue**: A 400 error mentioning `temperature` on Claude
320
+ **Solution**: Remove `config.temperature`, or set `temperature: nil` in that agent's `llm:`. Current Claude models reject this parameter.
333
321
 
334
- **Issue**: "Task execution failed"
335
- **Solution**: Check that all task dependencies are properly defined and agents have necessary tools.
322
+ **Issue**: A task has status `failed`
323
+ **Solution**: Check `task.result`, which holds the error message, and the log output. A task also fails if a task in its `context:` failed.
336
324
 
337
325
  ## Get Help
338
326
 
@@ -62,6 +62,25 @@ Welcome to the RCrewAI tutorials! These step-by-step guides will take you from b
62
62
 
63
63
  ---
64
64
 
65
+ ## 🔌 Production Controls (0.8 – 0.10)
66
+
67
+ ### [LLM Providers]({{ site.baseurl }}/tutorials/providers)
68
+ **Set up any of the nine providers**, including AWS Bedrock, Snowflake Cortex and OpenAI-compatible endpoints.
69
+
70
+ ### [Checkpointing]({{ site.baseurl }}/tutorials/checkpointing)
71
+ **Resume a failed run** without repeating finished tasks, and follow a run's lineage.
72
+
73
+ ### [Interceptors and Events]({{ site.baseurl }}/tutorials/interceptors-and-events)
74
+ **See inside a run.** Hook into every LLM call and rebuild the event stream into a trace.
75
+
76
+ ### [Concurrency]({{ site.baseurl }}/tutorials/concurrency)
77
+ **Control what runs in parallel:** tool calls, consensus rounds, embeddings and tasks.
78
+
79
+ ### [Live Streaming]({{ site.baseurl }}/tutorials/live-streaming)
80
+ **Build real-time callers** with cancellable Anthropic streams and connection reuse.
81
+
82
+ ---
83
+
65
84
  ## ✨ Capabilities (0.4 – 0.7)
66
85
 
67
86
  The features that grew RCrewAI beyond the classic crew model.
@@ -0,0 +1,84 @@
1
+ ---
2
+ layout: tutorial
3
+ title: Interceptors and Events
4
+ description: Inspect or change LLM requests and responses, and rebuild a run's event stream into a trace
5
+ ---
6
+
7
+ # Interceptors and Events
8
+
9
+ Interceptors let you see or change each LLM call. Events report what a crew is doing
10
+ while it runs.
11
+
12
+ ## LLM interceptors
13
+
14
+ Build a client with hooks, then give it to an agent:
15
+
16
+ ```ruby
17
+ redact = lambda do |payload, _context|
18
+ payload.merge(user: 'anonymous')
19
+ end
20
+
21
+ client = RCrewAI::LLMClient.for_provider(:openai, RCrewAI.configuration,
22
+ before_request: redact)
23
+
24
+ client.after_response do |result, context|
25
+ puts "#{context[:provider]}/#{context[:model]} took #{context[:duration_ms]}ms"
26
+ nil # keep the original result
27
+ end
28
+
29
+ agent = RCrewAI::Agent.new(name: 'analyst', role: 'Analyst', goal: 'Analyze', llm: client)
30
+ ```
31
+
32
+ - `before_request` receives `(payload, context)`. `after_response` receives
33
+ `(result, context)`, and its context also has `:duration_ms`.
34
+ - Return a new value to replace the original, or `nil` to keep it.
35
+ - Hooks run in the order they were registered.
36
+ - A hook that raises is reported to stderr and skipped, so it can't break the call.
37
+ That also means a hook can't be used to block a request by raising.
38
+
39
+ ## Events
40
+
41
+ Pass a block or callable to `crew.execute` to receive events. `stream:` also takes an
42
+ array of subscribers:
43
+
44
+ ```ruby
45
+ crew.execute do |event|
46
+ case event
47
+ when RCrewAI::Events::TextDelta then print event.text
48
+ when RCrewAI::Events::ToolCallStart then puts "Calling #{event.tool}"
49
+ when RCrewAI::Events::Usage then puts "Cost: #{event.cost_usd}"
50
+ end
51
+ end
52
+ ```
53
+
54
+ | Event | Fields, besides the common ones |
55
+ |---|---|
56
+ | `IterationStart` / `IterationEnd` | `iteration_index` / `finish_reason` |
57
+ | `TextDelta` / `TextDone` | `text` |
58
+ | `Thinking` | `text` |
59
+ | `ToolCallStart` | `tool`, `args`, `call_id` |
60
+ | `ToolCallResult` | `tool`, `call_id`, `result`, `duration_ms` |
61
+ | `ToolCallError` | `tool`, `call_id`, `error` |
62
+ | `Usage` | `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost_usd`, `cached_tokens` |
63
+ | `Error` | `error` |
64
+
65
+ Token and text events come from agents using native function calling. An agent that
66
+ falls back to the legacy runner, such as Ollama with a model without native tools,
67
+ emits fewer of them.
68
+
69
+ Delivery is serialized, so a subscriber is never entered from two threads at once and
70
+ doesn't need its own mutex.
71
+
72
+ ## Building a trace
73
+
74
+ Every event has an `id`, and a `parent_id` naming the span that encloses it, so you can
75
+ rebuild the flat stream into a tree. To group your own work under a span:
76
+
77
+ ```ruby
78
+ RCrewAI::Events.with_parent(span_id) do
79
+ RCrewAI::Events.emit(sink, RCrewAI::Events::Event.new(type: :checkpoint))
80
+ end
81
+ ```
82
+
83
+ Spans are per-thread. Tool events from RCrewAI's own worker threads carry the run's
84
+ span across, but a thread you start yourself begins with no parent.
@@ -0,0 +1,52 @@
1
+ ---
2
+ layout: tutorial
3
+ title: Live Streaming
4
+ description: Stream Anthropic replies with cancellation, connection reuse, per-call models and cached token counts
5
+ ---
6
+
7
+ # Live Streaming
8
+
9
+ These features are for real-time callers such as voice agents, where a reply may need
10
+ to stop as soon as the user interrupts. They work on the Anthropic client's `chat`
11
+ method, not through `crew.execute`.
12
+
13
+ ```ruby
14
+ client = RCrewAI::LLMClient.for_provider(:anthropic)
15
+ token = RCrewAI::CancelToken.new
16
+
17
+ begin
18
+ client.chat(
19
+ messages: [{ role: 'user', content: 'Tell me a story' }],
20
+ model: 'claude-haiku-5-5', # for this call only
21
+ cancel: token,
22
+ stream: lambda do |event|
23
+ print event.text if event.is_a?(RCrewAI::Events::TextDelta)
24
+ end
25
+ )
26
+ rescue RCrewAI::StreamCancelled
27
+ puts '(interrupted)'
28
+ end
29
+ ```
30
+
31
+ ## Cancelling
32
+
33
+ Call `token.cancel!` from the stream callback, another thread or another fiber. The
34
+ stream stops at the next chunk, the connection closes, and the caller gets
35
+ `RCrewAI::StreamCancelled`. Inside an Async reactor, stopping the calling task does the
36
+ same.
37
+
38
+ ## Connection reuse
39
+
40
+ Streaming requests from one client share a keep-alive connection, so back-to-back turns
41
+ skip TCP and TLS setup. Reuse the client between turns to get this. Streaming doesn't
42
+ block other fibers inside an Async reactor on Ruby 3.2 or later.
43
+
44
+ ## Cached tokens
45
+
46
+ `usage[:cached_tokens]` in the result, and `cached_tokens` on the `Usage` event, report
47
+ Anthropic's `cache_read_input_tokens`.
48
+
49
+ ## Custom endpoint
50
+
51
+ The Anthropic client uses `config.base_url` when it's set, for example to go through a
52
+ gateway.