Guide
How to build AI agents in Ruby on Rails
This guide walks from prerequisites to a production checklist: agent anatomy, tools, memory, knowledge, background execution, approvals, evaluations, deploy, and monitoring—using Rails-native patterns.
Updated 2026-07-28 · Rails Agent · Tiny Bubble Company
Direct answer
To build AI agents in Ruby on Rails, define agents in your Rails app, give them tools over your models, add memory or knowledge as needed, run work in the background, evaluate behavior, then deploy with monitoring and guardrails. Rails Agent is the full-stack agentic platform that covers that lifecycle without assembling a separate stack for each layer.
Prerequisites
- Ruby 3.2+ and Rails 6.1+
- A Rails app you can restart locally
- A provider API key (OpenAI, Anthropic, or another supported provider)
- Familiarity with models, jobs, and authorization in your app
Install and open /agents
gem "rails-agent-stack", "~> 0.2"
bundle install
bin/rails generate rails_agents:install
bin/dev
# → http://localhost:3000/agentsAgent anatomy in Rails
An agent is typed Ruby under app/agents/: a base class (Knowledge, Workflow, Operations, or Monitoring), model selection, instructions, optional tools, memory, knowledge, and channels. Local files remain the source of truth; the dashboard helps scaffold, test, and deploy.
class Support < RailsAgents::KnowledgeAgent
model :auto
knowledge_from "knowledge/**/*"
channel :web
tool :lookup_order, using: OrdersTool
endTools and model calls
Wrap ActiveRecord lookups and service objects as tools with authorization. Prefer curated tools over free-form SQL. See tool calling from Rails models for safe patterns.
Memory and knowledge
Use thread or user memory for conversational state. Use knowledge (RAG) for policies and documents. Rails Agent offers managed knowledge so you do not have to operate a vector database for the standard path.
Background execution
Do not block web requests on long multi-tool runs. Use the platform runtime (and Sidekiq patterns where you own custom jobs) with retries and idempotent tools.
Approvals and guardrails
Scope tools, set budgets, and require human approval for refunds, outbound messages, and destructive writes. Prompt text alone is not a control plane.
Testing and evaluations
Maintain golden scenarios: happy path, tool failure, policy escalation, and cost-sensitive cases. Re-run after prompt, model, or tool changes before promoting to production.
Deploying and monitoring
Promote when evals pass. Attach BYOK credentials, deploy through the hosted runtime, and watch traces, errors, and spend in /agents.
Production checklist
- Authorized tools only; no unconstrained SQL
- Memory/knowledge retention reviewed for privacy
- HITL on irreversible actions
- Eval suite green on critical cases
- Traces and cost visibility enabled
- On-call knows how to disable or roll back an agent
Frequently asked questions
How long does it take to build a first Rails AI agent?
A minimal agent can be scaffolded in minutes after installing rails-agent-stack and opening /agents. Production readiness—tools, evals, guardrails, and deploy—usually takes longer and should follow the checklist in this guide.
Do I need to leave Ruby to build agents?
No. Rails Agent keeps agent definitions, tools, and prompts in the Rails app under app/agents/, with a hosted runtime for production execution and monitoring.
What is the difference between a demo agent and a production agent?
A demo answers a few prompts. A production agent has authorized tools, memory or knowledge as needed, background execution, evaluations, guardrails or approvals, deployment, and observability.
Build your first production agent
Install the gem, open /agents, scaffold from docs or a Playbook, then follow this checklist through deploy.
Keep reading
Ruby on Rails AI agents →
Category pillar
Deploy AI agents in Rails →
Operations follow-up
Evaluate Rails AI agents →
Evals follow-up
Best Ruby AI frameworks →
Evaluation roundup
Getting started docs →
Product docs
Playbooks →
Start from a pattern
Agent types →
Knowledge → Monitoring
Tool calling from Rails models →
Build-time tools
Memory patterns →
Build-time memory
RAG without a vector database →
Knowledge at build time
Dashboard test tab →
Sandbox runs before promote
Structured outputs →
Testable agent results