DEV Community: George Kosmopoulos

AI agents in Rails, for a business that actually has customers

George Kosmopoulos — Thu, 10 Sep 2026 09:34:55 +0000

Originally published on gkosmo.eu.

An agent is a background job that gets to call a few methods

I have been putting this post off for months. Partly because "AI agents" is a phrase that makes me tired, and partly because most of what I read about it is either a demo that writes haikus or an architecture diagram with eleven boxes.

Here is what I actually run. It's small. You can paste it into a Rails app this afternoon.

The gems are rcrewai and rcrewai-rails. I maintain both and I use them on nakyma.io, so this is not a neutral review. It is the thing I reach for.

The example

A shop. Customers open support tickets. Somebody in the shop reads each one, looks up the customer's orders, decides if it's a refund, a shipping question or something else, and writes a reply.

That last person is the bottleneck. We are going to replace the reading and the drafting, and keep the sending.

That line matters: agents draft, humans send. Every time I've skipped this rule I regretted it within a week.

Setup

# Gemfile
gem "rcrewai"
gem "rcrewai-rails"

# config/initializers/rcrewai.rb
RCrewAI.configure do |config|
  config.llm_provider = :anthropic
  config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY")
  config.anthropic_model = ENV.fetch("ANTHROPIC_MODEL", "claude-sonnet-4-5")
  config.temperature = 0.1
end

Temperature low. This is a support desk, not a poetry slam.

The tool

This is the part people get wrong, so it comes first.

A tool is a Ruby object the model is allowed to call. Not "the database". Not "ActiveRecord". One method, scoped to one customer, read-only, returning a string.

# app/tools/order_lookup_tool.rb
class OrderLookupTool < RCrewAI::Tools::Base
  tool_name "order_lookup"
  description "Recent orders for the customer who opened this ticket. " \
              "Returns number, status, total and shipped_at."

  param :limit, type: :integer, required: false, default: 5,
        description: "How many recent orders to return (max 10)"

  def initialize(customer:)
    super()
    @customer = customer
  end

  def execute(limit: 5)
    @customer.orders
             .order(created_at: :desc)
             .limit(limit.clamp(1, 10))
             .map { |o| o.slice(:number, :status, :total, :shipped_at) }
             .to_json
  end
end

The param DSL turns into a JSON schema the model sees. The customer: is injected by us, not chosen by the model. The model cannot ask for someone else's orders because there is no parameter for that. Security by not having the argument. It's the cheapest kind.

The gem ships with WebSearch, SqlDatabase, FileWriter and friends, and the Rails engine adds an ActiveRecordTool. I don't use the generic ones in production. A tool that can run any query is a tool I have to explain to a customer later.

The crew

Two agents, two tasks, run in order. The first drafts, the second checks and formats.

# app/services/ticket_triage.rb
class TicketTriage
  class Failed < StandardError; end

  OUTPUT = {
    type: "object",
    properties: {
      category:         { type: "string" },  # refund | shipping | other
      refund_requested: { type: "boolean" },
      reply:            { type: "string" }
    },
    required: %w[category refund_requested reply]
  }.freeze

  def initialize(ticket)
    @ticket = ticket
  end

  def call
    support = RCrewAI::Agent.new(
      name: "support",
      role: "Support agent at a small online shop",
      goal: "Answer the customer accurately using their real order data",
      backstory: "You never invent order details. If the tool has no " \
                 "matching order, say so and ask for the order number.",
      tools: [OrderLookupTool.new(customer: @ticket.customer)],
      max_iterations: 6
    )

    reviewer = RCrewAI::Agent.new(
      name: "reviewer",
      role: "Support lead",
      goal: "Make sure replies follow policy and are short",
      backstory: "Policy: refunds within 30 days of delivery, no questions. " \
                 "After 30 days, offer store credit. Never promise a date " \
                 "we did not get from the order data."
    )

    draft = RCrewAI::Task.new(
      name: "draft",
      agent: support,
      description: <<~TXT,
        Customer #{@ticket.customer.name} wrote:

        #{@ticket.body}

        Look up their orders, then write a reply.
      TXT
      expected_output: "A plain-text reply of at most 120 words."
    )

    review = RCrewAI::Task.new(
      name: "review",
      agent: reviewer,
      context: [draft],
      description: "Check the draft against policy. Fix it if needed. " \
                   "Classify the ticket.",
      expected_output: "JSON with category, refund_requested and reply.",
      output_schema: OUTPUT
    )

    crew = RCrewAI::Crew.new("ticket_triage")
    crew.add_agent(support)
    crew.add_agent(reviewer)
    crew.add_task(draft)
    crew.add_task(review)

    result = crew.execute
    raise Failed, result[:results].map { _1[:result] }.join("\n") if result[:failed_tasks] > 0

    review.structured_output
  end
end

Things to notice.

The ticket text goes straight into the task description. There is no template engine, no {placeholder} interpolation. It's a Ruby heredoc. The crew is built per ticket and thrown away. Objects are cheap; I stopped trying to make crews reusable and my code got shorter.

context: [draft] is how the reviewer sees the support agent's output. That's the whole "multi-agent" story. One task's result becomes the next task's input. Nothing more mystical than a pipeline.

output_schema makes the last task return parsed JSON, validated, with retries when the model rambles. review.structured_output is a Hash with string keys. No regex on model output. If you are writing JSON.parse(response[/\{.*\}/m]) somewhere, this is the fix.

The job

# app/jobs/triage_ticket_job.rb
class TriageTicketJob < ApplicationJob
  queue_as :agents
  retry_on RCrewAI::Error, TicketTriage::Failed,
           wait: :polynomially_longer, attempts: 3

  def perform(ticket)
    out = TicketTriage.new(ticket).call

    ticket.update!(
      category:         out["category"],
      refund_requested: out["refund_requested"],
      draft_reply:      out["reply"],
      triaged_at:       Time.current
    )
  end
end

# app/models/support_ticket.rb
class SupportTicket < ApplicationRecord
  belongs_to :customer
  after_create_commit -> { TriageTicketJob.perform_later(self) }
end

That's it. A ticket arrives, thirty seconds later it has a category and a draft reply sitting in the admin, and a human clicks send or rewrites it. Give the agents queue its own worker so a slow model call doesn't sit in front of your password reset emails.

Where rcrewai-rails comes in

Everything above is the core gem. It's plain Ruby, it runs in a rake task, in a test, anywhere.

The Rails engine is for the day after it works, when someone asks "why did it tell Mrs Dupont she'd get a refund?".

rails generate rcrewai:rails:install
rails db:migrate

# config/routes.rb
mount RcrewAI::Rails::Engine => "/rcrewai"

You get tables for crews, agents, tasks and executions, an ActiveJob that records every run with its inputs, output, duration and error, and a span tree of every prompt and tool call underneath. There is a dashboard at /rcrewai. On nakyma.io that is how I find out what a run cost and where it looped.

If you want your crews to live in the database instead of in a service object, the engine has a CrewBuilder mixin and RcrewAI::Rails::Crew#execute_async. I use it for the crews that don't change per request. For the per-ticket kind, the PORO above is simpler and I'd start there.

Opinions, since you asked

Two agents is plenty. I've never needed a third that a better task description couldn't replace.

Put the policy in the backstory, not in a vector database. Thirty days, store credit after, don't promise dates. That fits in a sentence. Retrieval is for when it doesn't fit in a page.

Make the tool the security boundary. The model gets a method with the arguments you choose. Nothing else.

Never let the agent's output reach a customer without a draft_ prefix on the column. The day you remove the prefix should be a decision, not an accident.

And run it as a job. An agent is a background job that gets to call a few methods. Once I stopped thinking of it as anything more, it fit into Rails the way everything else does.

Code for both gems: rcrewAI and rcrewai-rails. Issues welcome, especially the ones that say I'm wrong.

Check the code health of your rails app

George Kosmopoulos — Tue, 17 Jun 2025 14:55:00 +0000

Rails Code Health: Turn Technical Debt Into Hard Numbers

What if your "quick fix" could predict next quarter's delivery delays? What if messy code came with a price tag? What if your codebase could literally tell you it needs therapy?

Meet Rails Code Health - the first gem to put a scientific health score on your Rails codebase, because apparently we needed peer-reviewed research to confirm that spaghetti code is, in fact, terrible.

The $85 Billion "I Told You So" Moment

Here's what researchers found when they studied real production codebases (shocking absolutely no one who's ever worked with legacy code):

💥 Low quality code has 15x more bugs (surprised Pikachu face)
⏰ Takes 124% longer to ship features (somewhere, a PM cries)
🎲 Creates 9x more unpredictable delivery times (your estimates were doomed from the start)

The kicker? 42% of developer time is wasted on technical debt, costing the industry $85 billion annually. That's enough money to buy Twitter... wait, scratch that, bad example. That's enough money to buy a lot of coffee for very tired developers.

Yet only 10% of companies actively manage it. The other 90% are too busy putting out fires they accidentally started.

The Research That Changes Everything (Finally!)

The peer-reviewed paper "Code Red: The Business Impact of Code Quality" analyzed 30,737 files across diverse industries. Scientists literally counted bugs so you don't have to argue with your PM about why that "simple" feature took three sprints.

Translation: That controller you've been avoiding since 2019 isn't just scary—it's statistically proven to be a productivity vampire. 🧛‍♂️

Rails Code Health: Because Your Code Deserves Better Than "It Works™"

This gem transforms academic research into actionable insights for Rails applications. Think of it as a fitness tracker for your codebase, except instead of counting steps, it counts tears shed during debugging sessions.

🎯 Smart Analysis Beyond "It Has Too Many Lines"

# This looks fine to humans who haven't lost all hope...
class UsersController < ApplicationController
  def create
    # 50 lines of business logic, validations, email sending,
    # PDF generation, coffee brewing, existential dread...
  end
end

# But Rails Code Health knows this is a war crime
# Score: 4.2/10.0 - "This method needs an intervention"

📊 One Number to Rule Them All

Health Score: 1-10 scale (like rating your pain at the doctor, but for code)

🟢 8.0-10.0: "Chef's kiss" - Ship fast, sleep well, maybe even have a social life
🟡 4.0-7.9: Manageable technical debt (like a small kitchen fire)
🔴 1.0-3.9: Your code is screaming internally (and so are you)
⚫ <1.0: Abandon all hope, ye who enter here

🔍 Rails-Specific Intelligence (It Speaks Rails!)

Controllers: Counts actions like a bouncer counts troublemakers
Models: Detects fat models before they need bariatric surgery
Views: Spots business logic hiding in templates like a very boring game of hide-and-seek
Migrations: Judges your schema changes harder than Gordon Ramsay judges amateur chefs

See Your Code's Therapy Session

$ rails-health

Rails Code Health Report
========================
🏥 Code Triage Results

📊 Overall Health: 6.8/10.0 (Could be worse! Could be WordPress!)
🟢 Healthy: 89 files (Living their best life)
🔴 Alert: 6 files (Currently having existential crisis)

🚨 Patients Needing Immediate Care:
1. 🔴 app/models/user.rb (2.8/10.0) - *Terminal case*
   • 847 lines - This isn't a model, it's a novella
   • 12 callbacks - More callbacks than a reality TV show

2. 🔴 app/controllers/admin_controller.rb (3.1/10.0) - *Critically obese*
   • 18 actions - REST in peace, RESTful conventions
   • No strong parameters - Security? We don't know her

💰 Business Impact (AKA "Why You Should Care"):
   Fixing alert files could speed development by 55%
   (That's like getting a whole extra developer, but cheaper and less pizza required)

The ROI Calculator (Or: How to Justify Your Refactoring to The Suits)

Based on actual science (not just developer complaints), improving health from 4.0 → 8.0:

For a 10-person team:

55% faster feature delivery = $550k saved annually (enough for a really nice coffee machine)
93% fewer production bugs = Fewer 3 AM phone calls
89% more predictable timelines = Your estimates might actually be... accurate? gasps

Drop-In Integration (Easier Than Your Ex)

# Install (like npm install, but for grown-ups)
gem install rails_code_health

# Analyze (brace yourself)
rails-health

# CI Integration (because humans can't be trusted)
rails-health --format json --output report.json
# Fail build if health drops below 6.0 (harsh but fair)

GitHub Actions Example:

- name: Code Health Reality Check
  run: |
    rails-health --format json | \
    ruby -e "exit 1 if JSON.parse(STDIN.read)['average_score'] < 6.0"
    echo "Your code has been judged... and found wanting"

Beyond Just Metrics (It's Got Personality!)

This isn't another linter that screams about semicolons like a grammar Nazi. It's a business intelligence tool that:

✅ Predicts delivery delays before your PM has to explain them to stakeholders

✅ Prioritizes refactoring with data instead of "this code gives me anxiety"

✅ Connects code quality to money (finally, a language executives understand!)

✅ Builds quality culture without the usual developer smugness

Real Teams, Real Results (Not Fake Testimonials)

"We identified our 3 biggest bottlenecks in 5 minutes. Our velocity increased 40% after addressing them. Also, I can sleep again." - Senior Rails Developer Who Used To Cry

"Finally, concrete numbers to justify refactoring time to management. No more 'trust me, this code is bad' arguments." - Engineering Manager (Reformed Excel Enthusiast)

"The health score became our team's most watched metric. We have a leaderboard now. It's gotten competitive." - Tech Lead (Slightly Concerning Competitive)

Why This Matters Now (Spoiler: Everything Is On Fire)

Developer shortage + 42% wasted time + infinite technical debt = 🔥🔥🔥

You can't hire your way out of technical debt. Trust us, we've tried. But you can measure it, shame it into submission, and eliminate it with the power of science and mild public embarrassment.

Rails Code Health gives you the ammunition to:

Stop playing technical debt whack-a-mole
Justify refactoring without sounding like a perfectionist
Prevent future disasters before they require therapy
Ship faster without sacrificing your sanity (or your weekend)

Common Developer Reactions

😱 "Oh no, my code has a score?" - Yes, and it's probably lower than you think
🤔 "But my code works fine!" - So does a 1994 Honda Civic, doesn't mean you should drive it to a client meeting
😤 "This is just opinion!" - It's literally peer-reviewed research, Karen
🥺 "Can I improve my score?" - That's... that's the whole point

Get Started Today (Your Future Self Will Thank You)

gem install rails_code_health
cd your_rails_project
rails-health
# Prepare for emotional damage

Join the support group of developers building better Rails applications through measurable code quality and shared trauma.

Open source • Research-backed • Rails-optimized • Therapist-approved*

GitHub Repository

Because your code quality should be as measurable as your therapy bills.

*Not actually approved by therapists, but several have expressed concern

PS: I do go to therapy to talk about my emotions and my life, and it is super beneficial. I have never managed to make my therapist laugh and it is not a goal ( just a side quest ). Do take therapy seriously

Intro to Rsmolagent

George Kosmopoulos — Tue, 11 Mar 2025 07:59:34 +0000

So I Made a Thing: RSmolagent for Ruby Devs Who Just Want Stuff to Work

Hey folks! gkosmo here. I wanted to chat about this little library I put together called RSmolagent. It's basically just me wanting to have the cool AI agent stuff that Python devs have, but in Ruby, and without all the fuss.

Why I Built This Thing

Look, I'm a Ruby dev. I like Ruby. It's elegant, it's fun to write, and it just makes me happy. But lately, all the cool AI agent frameworks are in Python. You've got LangChain (which is awesome but huge), and you've got smolagent (which is nice and simple).

I kept thinking: "Why can't we have something like smolagent but for Ruby?" I didn't want to switch to Python just to build AI agents, and I definitely didn't want to deal with some complex Ruby-Python bridge setup that would break in weird ways.

So I did what any slightly stubborn developer would do - I built my own version.

What's an "Agent" Anyway?

Before I dive in, let's talk about what an "agent" is in this context. It's pretty simple:

You've got an LLM (like GPT-4)
You give it access to some tools (like web search, calculators, APIs)
It figures out which tools to use to complete a task
It uses the results from those tools to give you a final answer

That's it. Nothing magical. The LLM is the brain, the tools are the hands, and RSmolagent is the nervous system connecting them.

How RSmolagent Works

The core idea is dead simple:

# You create an LLM provider
llm = RSmolagent::OpenAIProvider.new(
  model_id: "gpt-4",
  client: your_openai_client
)

# You create some tools
web_search = RSmolagent::Tools::WebSearchTool.new
calculator = MyCalculatorTool.new

# You create an agent with those tools
agent = RSmolagent::Agent.new(
  llm_provider: llm,
  tools: [web_search, calculator]
)

# You run the agent with a task
result = agent.run("What's the population of Tokyo multiplied by 3?")

Behind the scenes, the agent:

Asks the LLM what to do
The LLM says "I should search for Tokyo's population, then multiply it by 3"
The agent executes the web search tool
The agent sends the results back to the LLM
The LLM says "now I need to calculate this"
The agent runs the calculator tool
The LLM gets the final answer

It's a loop, but a pretty straightforward one.

Making Your Own Tools

The real fun comes when you make your own tools. Here's a dead simple example:

class DadJokeTool < RSmolagent::Tool
  def initialize
    super(
      name: "dad_joke",
      description: "Get a random dad joke",
      input_schema: {} # No inputs needed
    )
  end

  def execute(args)
    jokes = [
      "Why don't scientists trust atoms? Because they make up everything!",
      "I told my wife she was drawing her eyebrows too high. She looked surprised.",
      "What do you call a fake noodle? An impasta!"
    ]
    jokes.sample
  end
end

Now your agent can tell dad jokes. Revolutionary, I know.

But seriously, you can build tools that:

Query your database
Call your company's internal APIs
Control IoT devices
Generate images
Whatever else you can code in Ruby

The Code Is Stupidly Simple (By Design)

I intentionally kept the codebase tiny. There are basically four main parts:

Agent - Manages the conversation loop
Tool - Base class for all tools
LLMProvider - Talks to language models
Memory - Keeps track of conversation history

That's it. The entire thing is a few hundred lines of code. You could read the entire library in 15 minutes.

Why so simple? Because I wanted something I could understand entirely, modify easily, and not worry about mysterious bugs in some deep dependency chain.

A Real Example

Let's build something slightly more useful - a research assistant that can search the web and summarize what it finds:

require 'rsmolagent'
require 'ruby/openai'

# Set up OpenAI client
client = OpenAI::Client.new(access_token: ENV["OPENAI_API_KEY"]) 
llm = RSmolagent::OpenAIProvider.new(
  model_id: "gpt-3.5-turbo",
  client: client
)

# Create web search tool
web_search = RSmolagent::Tools::WebSearchTool.new

# Create the agent
agent = RSmolagent::Agent.new(
  llm_provider: llm,
  tools: [web_search],
  max_steps: 5
)

# Ask a research question
puts "What do you want to research?"
question = gets.chomp

puts "Researching... (this might take a bit)"
result = agent.run(question)

puts "\nHere's what I found:\n#{result}"

Just like that, you've got a research assistant. No complex setup, no weird Python dependencies, just plain Ruby.

It's Not Perfect (And That's Okay)

Look, RSmolagent isn't trying to compete with LangChain or even smolagent in terms of features. It's a minimal implementation that:

Works with Ruby
Is easy to understand
Gets the job done

It might not have every bell and whistle, but it's a solid foundation you can build on. And since the code is so simple, extending it is straightforward.

Give It a Try

If you're a Ruby dev curious about AI agents but don't want to learn a whole new language or framework, give RSmolagent a shot. It's open source, it's simple, and it works.

Clone it, hack on it, build something cool with it. And if you improve it, send a PR! This is just the beginning.

Because at the end of the day, programming should be fun. And nothing's more fun than building a little AI assistant that can actually do useful stuff.

Catch you later,
gkosmo