deepagents 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c68db07095761fd89fad4e2d5c27427ae659d94eaf9d2ebc8f4d5b7f2e243727
+  data.tar.gz: aca823c82b3ae695af8e2f75e5450a10d55a94e064fb59ec901a48007a2c9ccf
+SHA512:
+  metadata.gz: 69998915abd938c0de71ef6f0248a52708fa3f0680e076f0421cfd4a6305980da9456a7646fdcc8f969256de7da20ad17121314b2b653cfc88b25ded2fad27ac
+  data.tar.gz: 5fdf4e47952dcfb7b83e8e6c3c02c369491a219b07d16dbf544f12b761e8a313577db66956f78d9c929d53971e30e5f0a66745227afac55ff0f470cd983f109c

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# 🧠🤖 DeepAgents for Ruby
+
+Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks. Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things: a **planning tool**, **sub agents**, access to a **file system**, and a **detailed prompt**.
+
+`deepagents` is a Ruby gem that implements these in a general purpose way so that you can easily create a Deep Agent for your application.
+
+**Acknowledgements: This project was inspired by the Python [deepagents](https://github.com/langchain-ai/deepagents) library and is a Ruby implementation of its functionality.**
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'deepagents'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install deepagents
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'deepagents'
+require 'anthropic'
+
+# Initialize the Anthropic client
+anthropic_client = Anthropic::Client.new(api_key: ENV['ANTHROPIC_API_KEY'])
+
+# Define a search tool
+def internet_search(query, max_results: 5, topic: 'general', include_raw_content: false)
+  # In a real implementation, this would call a search API
+  # For example, you could use a Ruby wrapper for Tavily or another search API
+  "Search results for: #{query}"
+end
+
+# Create a tool object
+search_tool = DeepAgents::Tool.new(
+  "internet_search",
+  "Run a web search"
+) do |query, max_results: 5, topic: 'general', include_raw_content: false|
+  internet_search(query, max_results: max_results, topic: topic, include_raw_content: include_raw_content)
+end
+
+# Prompt prefix to steer the agent to be an expert researcher
+research_instructions = <<~INSTRUCTIONS
+  You are an expert researcher. Your job is to conduct thorough research, and then write a polished report.
+
+  You have access to a few tools.
+
+  ## `internet_search`
+
+  Use this to run an internet search for a given query. You can specify the number of results, the topic, and whether raw content should be included.
+INSTRUCTIONS
+
+# Create the agent using built-in model adapters
+agent = DeepAgents.create_deep_agent(
+  [search_tool],
+  research_instructions,
+  model: DeepAgents.claude_model() # or DeepAgents.openai_model()
+)
+
+# Invoke the agent
+result = agent.invoke({
+  messages: [{role: "user", content: "what is Ruby on Rails?"}]
+})
+
+# Access the agent's response
+puts result.messages.last[:content]
+```
+
+### Using with langchainrb and langgraph_rb
+
+```ruby
+require 'deepagents'
+require 'langchainrb'
+require 'langgraph_rb'
+
+# Create a search tool using langchainrb's tool system
+search_tool = Langchain::Tool.new(
+  name: "internet_search",
+  description: "Run a web search",
+  function: ->(query:, max_results: 5) {
+    # In a real implementation, this would call a search API
+    "Search results for: #{query}"
+  }
+)
+
+# Convert to DeepAgents tool
+deep_search_tool = DeepAgents::Tool.from_langchain(search_tool)
+
+# Create a deep agent with langchainrb integration
+agent = DeepAgents.create_deep_agent(
+  [deep_search_tool],
+  "You are an expert researcher. Your job is to conduct thorough research.",
+  model: "claude-3-sonnet-20240229" # Will automatically create appropriate model adapter
+)
+
+# Run the agent
+result = agent.run("What is Ruby on Rails?")
+puts result
+```
+
+## Creating a custom deep agent
+
+There are three parameters you can pass to `create_deep_agent` to create your own custom deep agent.
+
+### `tools` (Required)
+
+The first argument to `create_deep_agent` is `tools`.
+This should be an array of tool objects created using `DeepAgents::Tool.new`.
+The agent (and any subagents) will have access to these tools.
+
+### `instructions` (Required)
+
+The second argument to `create_deep_agent` is `instructions`.
+This will serve as part of the prompt of the deep agent.
+Note that there is a built-in system prompt as well, so this is not the *entire* prompt the agent will see.
+
+### `model` (Optional)
+
+By default, `deepagents` uses a simple placeholder model. You should provide your own model implementation that interfaces with an LLM API like Anthropic's Claude or OpenAI.
+
+Your model class should implement a `generate` method that takes a prompt and messages array and returns a response string.
+
+### `subagents` (Optional)
+
+A keyword parameter to `create_deep_agent` is `subagents`.
+This can be used to specify any custom subagents this deep agent will have access to.
+
+`subagents` should be an array of `DeepAgents::SubAgent` objects, where each has:
+
+- **name**: The name of the subagent, and how the main agent will call the subagent
+- **description**: The description of the subagent that is shown to the main agent
+- **prompt**: The prompt used for the subagent
+- **tools**: The list of tools that the subagent has access to (optional)
+
+To use it looks like:
+
+```ruby
+research_sub_agent = DeepAgents::SubAgent.new(
+  name: "research-agent",
+  description: "Used to research more in depth questions",
+  prompt: sub_research_prompt
+)
+
+agent = DeepAgents.create_deep_agent(
+  tools,
+  prompt,
+  subagents: [research_sub_agent]
+)
+```
+
+## Integration with langchainrb and langgraph_rb
+
+DeepAgents now integrates with the popular Ruby gems `langchainrb` and `langgraph_rb` to provide enhanced functionality and compatibility with the broader LLM ecosystem.
+
+### langchainrb Integration
+
+The `langchainrb` integration provides:
+
+- **Model Compatibility**: All DeepAgents model adapters can be converted to langchainrb models using the `to_langchain_model` method
+- **Tool Interoperability**: Convert between DeepAgents tools and langchainrb tools
+- **Vector Database Access**: Leverage langchainrb's vector database integrations for RAG applications
+- **Prompt Management**: Use langchainrb's prompt templates with DeepAgents
+
+### langgraph_rb Integration
+
+The `langgraph_rb` integration enables:
+
+- **Stateful Agents**: Build agents that maintain state across interactions
+- **Directed Graphs**: Create complex agent workflows with directed graph structures
+- **Multi-Actor Systems**: Coordinate multiple agents working together
+- **Checkpointing**: Save and restore agent state
+
+## Deep Agent Details
+
+The below components are built into `deepagents` and help make it work for deep tasks off-the-shelf.
+
+### Planning Tool
+
+`deepagents` comes with a built-in planning tool. This planning tool is very simple and is based on ClaudeCode's TodoWrite tool.
+This tool doesn't actually do anything - it is just a way for the agent to come up with a plan, and then have that in the context to help keep it on track.
+
+### File System Tools
+
+`deepagents` comes with four built-in file system tools: `ls`, `edit_file`, `read_file`, `write_file`.
+These do not actually use a file system - rather, they mock out a file system using the agent's state object.
+
+Right now the "file system" will only be one level deep (no sub directories).
+
+These files can be passed in (and also retrieved) by using the `files` key in the agent's state.
+
+```ruby
+agent = DeepAgents.create_deep_agent(...)
+
+result = agent.invoke({
+  messages: [...],
+  # Pass in files to the agent using this key
+  # files: {"foo.txt" => "foo", ...}
+})
+
+# Access any files afterwards like this
+result.files
+```
+
+### Sub Agents
+
+`deepagents` comes with the built-in ability to call sub agents.
+It has access to a `general-purpose` subagent at all times - this is a subagent with the same instructions as the main agent and all the tools that it has access to.
+You can also specify custom sub agents with their own instructions and tools.
+
+Sub agents are useful for "context quarantine" (to help not pollute the overall context of the main agent) as well as custom instructions.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/cdaviis/deepagents/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,17 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Run tests with coverage"
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task["spec"].execute
+end
+
+desc "Run the example research agent"
+task :example do
+  ruby "examples/research_agent.rb"
+end

data/examples/langchain_integration.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "deepagents"
+require "langchainrb"
+require "langgraph_rb"
+
+# Example showing integration between DeepAgents, langchainrb, and langgraph_rb
+
+# 1. Create a langchainrb tool
+search_tool = Langchain::Tool.new(
+  name: "internet_search",
+  description: "Search the internet for information",
+  function: ->(query:) {
+    puts "Searching for: #{query}"
+    "Here are some results for '#{query}': [Example search results]"
+  }
+)
+
+# 2. Create a DeepAgents tool
+calculator_tool = DeepAgents::Tool.new(
+  "calculator",
+  "Perform mathematical calculations"
+) do |expression|
+  begin
+    eval(expression).to_s
+  rescue => e
+    "Error: #{e.message}"
+  end
+end
+
+# 3. Create a Claude model using DeepAgents
+claude_model = DeepAgents.claude_model(model: "claude-3-sonnet-20240229")
+
+# 4. Create a research sub-agent
+research_agent = DeepAgents::SubAgent.new(
+  name: "research-agent",
+  description: "Used for in-depth research on specific topics",
+  prompt: "You are a specialized research agent. Your task is to provide detailed information on specific topics."
+)
+
+# 5. Create a deep agent with both tools and the sub-agent
+agent = DeepAgents.create_deep_agent(
+  [calculator_tool],
+  "You are a helpful assistant that can perform calculations and search for information.",
+  model: claude_model,
+  subagents: [research_agent]
+)
+
+# 6. Run the agent with a user query
+if ARGV.length > 0
+  result = agent.run(ARGV.join(" "))
+  puts "Agent response:"
+  puts result
+else
+  puts "Please provide a query as a command-line argument."
+  puts "Example: ruby langchain_integration.rb 'What is 42 * 73?'"
+end

data/examples/research_agent.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add the lib directory to the load path
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require 'deepagents'
+
+# Load environment variables from .env file if present
+begin
+  require 'dotenv'
+  Dotenv.load
+rescue LoadError
+  # dotenv gem not installed, skipping
+  puts "Note: dotenv gem not installed. Using environment variables directly."
+end
+
+# Define a search tool (in a real implementation, this would use a search API)
+class MockInternetSearch
+  def initialize
+    # Mock search results
+    @results = {
+      "ruby gem" => "Ruby gems are packages of code that can be downloaded and used in Ruby projects. They are distributed via RubyGems.org.",
+      "anthropic claude" => "Claude is a family of AI assistants created by Anthropic. Claude excels at thoughtful dialogue and complex reasoning.",
+      "deep agent" => "Deep agents are AI systems that can perform complex tasks by breaking them down into smaller steps and using tools to accomplish goals."
+    }
+  end
+  
+  def search(query)
+    # Find the most relevant result
+    best_match = @results.keys.max_by do |key|
+      # Simple relevance scoring based on word overlap
+      (query.downcase.split & key.downcase.split).size
+    end
+    
+    # Return the result or a default message
+    @results[best_match] || "No results found for '#{query}'."
+  end
+end
+
+# Create a search tool using the mock internet search
+search_engine = MockInternetSearch.new
+search_tool = DeepAgents::Tool.new(
+  "search",
+  "Search the internet for information"
+) do |query, state:, tool_call_id:, **kwargs|
+  begin
+    raise ArgumentError, "Query cannot be empty" if query.nil? || query.strip.empty?
+    result = search_engine.search(query)
+    DeepAgents::ToolMessage.new(
+      "Search results for '#{query}':\n#{result}",
+      tool_call_id: tool_call_id
+    )
+  rescue => e
+    DeepAgents::ToolMessage.new(
+      "Error searching for '#{query}': #{e.message}",
+      tool_call_id: tool_call_id
+    )
+  end
+end
+
+# Define the agent's instructions
+instructions = <<~INSTRUCTIONS
+  You are a research assistant that helps users find information and write reports.
+  
+  When given a research topic:
+  1. Break down the topic into key questions to investigate
+  2. Use the search tool to find information about each question
+  3. Synthesize the information into a coherent report
+  4. Use the write_file tool to save your report
+  
+  Be thorough but concise in your research.
+  Always cite your sources.
+INSTRUCTIONS
+
+# Create a research sub-agent for more focused research
+sub_research_prompt = <<~SUB_PROMPT
+  You are a specialized research assistant. Your job is to dive deep into specific topics and extract detailed information.
+  
+  When given a research task:
+  1. Break it down into specific questions
+  2. Search for information on each question
+  3. Organize the information in a structured way
+  4. Return a detailed analysis
+SUB_PROMPT
+
+research_sub_agent = DeepAgents::SubAgent.new(
+  name: "research-agent",
+  description: "Used to research more in depth questions",
+  prompt: sub_research_prompt
+)
+
+# Create the agent with proper error handling
+begin
+  puts "Creating research agent..."
+  
+  # Try to use the real API if keys are available
+  if ENV['ANTHROPIC_API_KEY']
+    puts "Using Anthropic Claude API"
+    model = DeepAgents.claude_model
+  elsif ENV['OPENAI_API_KEY']
+    puts "Using OpenAI API"
+    model = DeepAgents.openai_model
+  else
+    # Fall back to the mock model
+    puts "Warning: No API keys found. Using mock model."
+    model = DeepAgents::Models::MockModel.new({
+      "ruby gems" => <<~RESPONSE
+        I'll research Ruby gems for you.
+        
+        I'll break this down into steps:
+        
+        ```tool_call
+        {"name": "write_todos", "arguments": {"todos": [{"content": "Search for Ruby gem information", "status": "pending"}, {"content": "Synthesize findings into a report", "status": "pending"}, {"content": "Save report to a file", "status": "pending"}]}}
+        ```
+        
+        Let me search for information about Ruby gems.
+        
+        ```tool_call
+        {"name": "search", "arguments": {"query": "ruby gem"}}
+        ```
+        
+        Now I'll write a report based on this information.
+        
+        ```tool_call
+        {"name": "write_todos", "arguments": {"todos": [{"content": "Search for Ruby gem information", "status": "completed"}, {"content": "Synthesize findings into a report", "status": "in_progress"}, {"content": "Save report to a file", "status": "pending"}]}}
+        ```
+        
+        ```tool_call
+        {"name": "write_file", "arguments": {"file_path": "/ruby_gems_report.md", "content": "# Ruby Gems Report\n\nRuby gems are packages of code that can be downloaded and used in Ruby projects. They are distributed via RubyGems.org.\n\n## Key Points\n\n- Ruby gems are reusable code packages\n- They are distributed through RubyGems.org\n- They make it easy to share and use code across projects\n\n## Sources\n\n- Internet search results"}}
+        ```
+        
+        ```tool_call
+        {"name": "write_todos", "arguments": {"todos": [{"content": "Search for Ruby gem information", "status": "completed"}, {"content": "Synthesize findings into a report", "status": "completed"}, {"content": "Save report to a file", "status": "completed"}]}}
+        ```
+        
+        I've completed the research on Ruby gems and saved a report to `/ruby_gems_report.md`. The report includes information about what Ruby gems are, how they're distributed, and their purpose in the Ruby ecosystem.
+      RESPONSE
+    })
+  end
+  
+  agent = DeepAgents.create_deep_agent(
+    [search_tool],
+    instructions,
+    model: model,
+    subagents: [research_sub_agent]
+  )
+  
+  # Run the agent with a research topic
+  puts "\n🤖 Running research agent..."
+  result = agent.invoke(messages: [{role: "user", content: "Please research Ruby gems and write a report."}])
+  
+  # Print the final state
+  puts "\n📊 Final State:\n"
+  puts "Messages:"
+  result.messages.each do |message|
+    puts "#{message[:role]}: #{message[:content].split('\n').first}..."
+  end
+  
+  puts "\n📁 Files:"
+  result.files.each do |path, content|
+    puts "#{path}:\n#{content}\n"
+  end
+  
+  puts "\n📋 Todos:"
+  result.todos.each do |todo|
+    puts "- [#{todo.status == 'completed' ? 'x' : ' '}] #{todo.content}"
+  end
+rescue DeepAgents::CredentialsError => e
+  puts "\n❌ API Credential Error: #{e.message}"
+  puts "Please set the appropriate API key in your environment variables."
+rescue DeepAgents::ModelError => e
+  puts "\n❌ Model Error: #{e.message}"
+  puts "There was an issue with the LLM model."
+rescue DeepAgents::Error => e
+  puts "\n❌ DeepAgents Error: #{e.message}"
+rescue => e
+  puts "\n❌ Unexpected Error: #{e.message}"
+  puts e.backtrace.join("\n")
+end

data/lib/deepagents/deepagentsrb/errors.rb

@@ -0,0 +1,80 @@
+module DeepAgentsRb
+  # Base error class for all DeepAgentsRb errors
+  class Error < StandardError; end
+  
+  # Error raised when there's an issue with the state
+  class StateError < Error; end
+  
+  # Error raised when there's an issue with a tool
+  class ToolError < Error
+    attr_reader :tool_name
+    
+    def initialize(tool_name, message)
+      @tool_name = tool_name
+      super("Error in tool '#{tool_name}': #{message}")
+    end
+  end
+  
+  # Error raised when a tool is not found
+  class ToolNotFoundError < ToolError
+    def initialize(tool_name)
+      super(tool_name, "Tool not found")
+    end
+  end
+  
+  # Error raised when there's an issue with a file operation
+  class FileError < Error; end
+  
+  # Error raised when a file is not found
+  class FileNotFoundError < FileError
+    attr_reader :path
+    
+    def initialize(path)
+      @path = path
+      super("File not found: #{path}")
+    end
+  end
+  
+  # Error raised when there's an issue with a model
+  class ModelError < Error; end
+  
+  # Error raised when there's an issue with API credentials
+  class CredentialsError < ModelError
+    def initialize(model_name)
+      super("Missing API credentials for #{model_name}")
+    end
+  end
+  
+  # Error raised when there's an issue with a sub-agent
+  class SubAgentError < Error; end
+  
+  # Error raised when a sub-agent is not found
+  class SubAgentNotFoundError < SubAgentError
+    attr_reader :agent_name
+    
+    def initialize(agent_name)
+      @agent_name = agent_name
+      super("Sub-agent not found: #{agent_name}")
+    end
+  end
+  
+  # Error raised when there's an issue with parsing a tool call
+  class ToolCallParseError < Error
+    attr_reader :raw_content
+    
+    def initialize(message, raw_content = nil)
+      @raw_content = raw_content
+      super(message)
+    end
+  end
+  
+  # Error raised when there's an issue with the LLM response
+  class LLMResponseError < Error; end
+  
+  # Error raised when the maximum number of iterations is reached
+  class MaxIterationsError < Error
+    def initialize(iterations)
+      super("Maximum number of iterations (#{iterations}) reached")
+    end
+  end
+end