Rubyrana

Build production-ready AI agents in Ruby with just a few lines of code.

Quick Start ◆ Features ◆ Tools ◆ Model Providers ◆ MCP

Rubyrana is a lightweight, model-driven Ruby SDK for building AI agents. Start with a simple conversational assistant, then scale to multi-tool workflows and production deployments.

Quick Start

# Install Rubyrana
bundle add rubyrana

require "rubyrana"

Rubyrana.configure do |config|
  config.default_provider = Rubyrana::Providers::Anthropic.new(
    api_key: ENV.fetch("ANTHROPIC_API_KEY"),
    model: ENV.fetch("ANTHROPIC_MODEL", "claude-3-haiku-20240307")
  )
end

agent = Rubyrana::Agent.new
puts agent.call("What is the square root of 1764?")

Note: Configure your Anthropic credentials before running.

Features

Simple agent loop with a clean Ruby API
Anthropic-first provider integration with tool calling and streaming
Tooling-first design for structured, safe function calls
Streaming-ready architecture (planned)
MCP support to connect thousands of tools (planned)

Tools

Create tools with a Ruby DSL:

require "rubyrana"

word_count = Rubyrana::Tool.new("word_count") do |text:|
  text.split.size
end

agent = Rubyrana::Agent.new(tools: [word_count])
puts agent.call("How many words are in this sentence?")

Built-in Tools

Rubyrana ships with optional built-in tools:

require "rubyrana"

tools = [
  Rubyrana::Tools.code_interpreter,
  Rubyrana::Tools.web_search
]

agent = Rubyrana::Agent.new(tools: tools)
puts agent.call("Search Ruby 3.3 release highlights and summarize.")

Note: web_search requires users to bring their own WEB_SEARCH_API_KEY (Serper). code_interpreter runs code in a local process.

Tool Decorators + Loader

Define tools with a simple Ruby decorator and load them from a directory:

require "rubyrana"

Rubyrana.tool("hello", description: "Greet a user", schema: {
  type: "object",
  properties: { name: { type: "string" } },
  required: ["name"]
}) do |name:|
  "Hello, #{name}!"
end

agent = Rubyrana::Agent.new(load_tools_from: "./tools")
puts agent.call("Use the hello tool to greet Ajay")

Web Search via MCP (Preferred)

If you want a Strands-style approach, delegate web search to an MCP server:

require "rubyrana"

web_search = Rubyrana::Tools.web_search_mcp(
  command: "uvx",
  args: ["awslabs.aws-documentation-mcp-server@latest"],
  tool_name: "search_documentation"
)

agent = Rubyrana::Agent.new(tools: [web_search])
puts agent.call("Search Bedrock docs and summarize the key points.")

Hot-reload tools from a folder:

agent = Rubyrana::Agent.new(load_tools_from: "./tools")
agent.call("Use any tools you find in the tools directory")

MCP (Experimental)

Connect Model Context Protocol servers:

require "rubyrana"

mcp = Rubyrana::MCP::Client.new(command: "uvx", args: ["awslabs.aws-documentation-mcp-server@latest"])

mcp.with_session do |tools|
  agent = Rubyrana::Agent.new(tools: tools)
  puts agent.call("Tell me about Amazon Bedrock and how to use it with Ruby")
end

Model Provider

Rubyrana is Anthropic-native today.

Example:

require "rubyrana"

model = Rubyrana::Providers::Anthropic.new(
  api_key: ENV.fetch("ANTHROPIC_API_KEY"),
  model: ENV.fetch("ANTHROPIC_MODEL", "claude-3-haiku-20240307")
)

agent = Rubyrana::Agent.new(model: model)
puts agent.call("Explain agentic workflows in simple terms")

Documentation

Getting Started
Core Concepts
Tools & MCP
Production Deployment

Contributing

Contributions are welcome. Please open issues and PRs with clear reproduction steps and context.

License

Apache 2.0

rubyrana

Development

Runtime