rails-agent-stack 0.1.1

data/examples/support/evals/smoke.yml

@@ -0,0 +1,4 @@
+- name: greeting
+  input: "Hello"
+  expected_contains:
+    - "help"

data/examples/support/knowledge/shipping.md

@@ -0,0 +1 @@
+# Orders ship within 2 business days.

data/examples/support/memory.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+# Conversation memory � managed by Rails Agent Cloud vector store.

data/examples/support/prompt.md

@@ -0,0 +1,9 @@
+# Support Agent
+
+You are Support, a Knowledge agent for this Rails application.
+
+- Answer plainly and confidently.
+- Use tools to look up order status when asked.
+- Escalate billing disputes to a human.
+
+Provider credentials are stored in Rails Agent Cloud (BYOK) — not in this repository.

data/exe/rails-agents

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rails_agents/cli"
+
+RailsAgents::CLI.start(ARGV)

data/lib/generators/rails_agents/agent/agent_generator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/named_base"
+
+module RailsAgents
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :type,
+        type: :string,
+        default: "knowledge",
+        desc: "Agent taxonomy: knowledge, workflow, operations, monitoring"
+
+      class_option :database,
+        type: :boolean,
+        default: false,
+        desc: "Scaffold database-connected tools (Knowledge agents)"
+
+      desc "Scaffold an agent directory under app/agents/"
+
+      def create_agent_directory
+        empty_directory agent_path
+        empty_directory File.join(agent_path, "tools")
+        empty_directory File.join(agent_path, "skills")
+        empty_directory File.join(agent_path, "knowledge")
+        empty_directory File.join(agent_path, "connectors")
+        empty_directory File.join(agent_path, "plugins")
+        empty_directory File.join(agent_path, "channels")
+        empty_directory File.join(agent_path, "evals")
+      end
+
+      def create_agent_files
+        if database?
+          template "agent_database.rb.tt", File.join(agent_path, "agent.rb")
+          template "prompt_database.md.tt", File.join(agent_path, "prompt.md")
+        else
+          template "agent.rb.tt", File.join(agent_path, "agent.rb")
+          template "prompt.md.tt", File.join(agent_path, "prompt.md")
+        end
+        template "memory.rb.tt", File.join(agent_path, "memory.rb")
+        template "imports.yml.tt", File.join(agent_path, "imports.yml")
+        template "channels/slack.rb.tt", File.join(agent_path, "channels/slack.rb")
+        template "evals/smoke.yml.tt", File.join(agent_path, "evals/smoke.yml")
+      end
+
+      private
+
+      def agent_path
+        File.join("app/agents", file_name)
+      end
+
+      def class_name
+        name.camelize
+      end
+
+      def agent_type
+        type = options[:type].to_s.downcase
+        return type if RailsAgents::TAXONOMY_TYPES.map(&:to_s).include?(type)
+
+        say "Unknown --type #{options[:type].inspect}; using knowledge.", :yellow
+        "knowledge"
+      end
+
+      def agent_base_class
+        {
+          "knowledge" => "KnowledgeAgent",
+          "workflow" => "WorkflowAgent",
+          "operations" => "OperationsAgent",
+          "monitoring" => "MonitoringAgent"
+        }.fetch(agent_type)
+      end
+
+      def database?
+        options[:database]
+      end
+    end
+  end
+end

data/lib/generators/rails_agents/agent/templates/agent.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < RailsAgents::<%= agent_base_class %>
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation
+  knowledge_from "knowledge/**/*"
+
+  tool :ping do
+    { status: "ok", agent: "<%= file_name %>" }
+  end
+
+  skill :triage, from: "skills/triage.rb"
+  channel :slack
+end

data/lib/generators/rails_agents/agent/templates/agent_database.rb.tt

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < RailsAgents::KnowledgeAgent
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation
+  knowledge_from "knowledge/**/*"
+
+  tool :lookup_order do |order_number:|
+    order = Order.find_by(number: order_number)
+    return { error: "Order not found", order_number: order_number } unless order
+
+    {
+      number: order.number,
+      status: order.status,
+      customer_name: order.customer_name,
+      customer_email: order.customer_email,
+      total_cents: order.total_cents,
+      currency: order.currency,
+      shipped_at: order.shipped_at&.iso8601
+    }
+  end
+
+  tool :search_products do |query:|
+    scope = Product.where(status: "active")
+    if query.present?
+      pattern = "%#{query}%"
+      scope = scope.where("name LIKE ? OR sku LIKE ?", pattern, pattern)
+    end
+
+    scope.limit(10).map do |product|
+      {
+        sku: product.sku,
+        name: product.name,
+        price_cents: product.price_cents,
+        stock: product.stock,
+        collection: product.collection&.name
+      }
+    end
+  end
+
+  channel :web
+end

data/lib/generators/rails_agents/agent/templates/channels/slack.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Slack channel connector � install via dashboard or:
+# RailsAgents::Client.new.install_channel(kind: :slack)
+
+RailsAgents.configure do |config|
+  # Channel OAuth handled by Rails Agent Cloud.
+end

data/lib/generators/rails_agents/agent/templates/evals/smoke.yml.tt

@@ -0,0 +1,4 @@
+- name: smoke
+  input: "Hello"
+  expected_contains:
+    - "ok"

data/lib/generators/rails_agents/agent/templates/imports.yml.tt

@@ -0,0 +1,9 @@
+version: 1
+
+# Reuse capabilities from app/agents_library without duplicating source files.
+# Example:
+# imports:
+#   - kind: skill
+#     slug: triage
+#     from: library/skills/triage.rb
+imports: []

data/lib/generators/rails_agents/agent/templates/memory.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Managed conversation memory � synced to Rails Agent Cloud.
+RailsAgents.configure do |config|
+  # Memory is cloud-managed; no local vector DB required.
+end

data/lib/generators/rails_agents/agent/templates/prompt.md.tt

@@ -0,0 +1,10 @@
+# <%= class_name %> Agent
+
+You are <%= class_name %>, a Knowledge agent for this Rails application.
+
+- Answer plainly using database tools when the user asks about orders, products, or catalog data.
+- Call `lookup_order` for order numbers (e.g. ORD-DEMO-1001).
+- Call `search_products` to find products by name or SKU.
+- Escalate to a human when you cannot answer safely or need write access.
+
+Provider credentials are stored in Rails Agent Cloud — never paste API keys into this repo.

data/lib/generators/rails_agents/agent/templates/prompt_database.md.tt

@@ -0,0 +1,14 @@
+# <%= class_name %> Agent
+
+You are <%= class_name %>, a database-connected Knowledge agent for this Rails app.
+
+## Tools
+
+- `lookup_order(order_number:)` — order status, customer, total, shipped_at
+- `search_products(query:)` — active products by name or SKU
+
+## Demo data
+
+After `bin/rails db:seed`, try order numbers like `ORD-DEMO-1001` or ask about products such as "Classic Tee".
+
+Provider credentials live in Rails Agent Cloud (BYOK). Do not commit secrets to this repository.

data/lib/generators/rails_agents/install/INSTALL

@@ -0,0 +1,10 @@
+Rails Agents is mounted at /agents.
+
+Next steps:
+
+  1. bin/dev  (or bin/rails server)
+  2. Open http://localhost:3000/agents and connect your company workspace
+  3. Read AGENTS.md in your app root
+  4. bin/rails generate rails_agents:agent my_agent --type knowledge --database
+
+Platform guide: https://rails-agent.com/docs/getting-started

data/lib/generators/rails_agents/install/install_generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RailsAgents
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Mount the Rails Agents engine and create the initializer"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/rails_agents.rb"
+        template "rails_agents_autoload.rb.tt", "config/initializers/rails_agents_autoload.rb"
+      end
+
+      def mount_engine
+        route "mount RailsAgents::Engine, at: \"/agents\""
+      end
+
+      def create_agents_guide
+        template "AGENTS.md.tt", "AGENTS.md"
+      end
+
+      def create_workspace_library
+        %w[tools skills connectors plugins knowledge knowledge/sources packages].each do |folder|
+          empty_directory File.join("app/agents_library", folder)
+        end
+        template "library_manifest.yml.tt", "app/agents_library/manifest.yml"
+        template "library_README.md.tt", "app/agents_library/README.md"
+      end
+
+      def create_env_placeholders
+        env_path = File.expand_path(".env", destination_root)
+        placeholders = <<~ENV
+
+          # Rails Agent Cloud platform key — NOT your OpenAI/Anthropic keys (those are BYOK in dashboard)
+          # Written automatically when you connect from /agents
+          RAILS_AGENTS_API_KEY=
+          RAILS_AGENTS_PROJECT_ID=
+        ENV
+
+        if File.exist?(env_path)
+          unless File.read(env_path).include?("RAILS_AGENTS_API_KEY")
+            append_to_file ".env", placeholders
+          end
+        else
+          create_file ".env.rails_agents.example", placeholders.lstrip
+        end
+      end
+
+      def show_next_steps
+        return unless behavior == :invoke
+
+        port = ENV.fetch("PORT", "3000")
+        url = "http://localhost:#{port}/agents"
+
+        say ""
+        say "============================================================", :green
+        say "  Rails Agents installed", :green
+        say "============================================================", :green
+        say ""
+        say "  1. Start server:  bin/dev  (or bin/rails server)", :green
+        say "  2. Connect:       #{url}", :green
+        say "  3. Read AGENTS.md — scaffold your first database Knowledge agent:", :green
+        say "     bin/rails generate rails_agents:agent my_agent --type knowledge --database", :green
+        say "============================================================", :green
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/rails_agents/install/templates/AGENTS.md.tt

@@ -0,0 +1,46 @@
+# AGENTS.md — <%= Rails.application.class.module_parent_name rescue "YourApp" %>
+
+Project guide for external coding agents. Platform docs: [rails-agents/docs/AGENTS.md](https://github.com/Tiny-Bubble-Company/rails-agents/blob/main/docs/AGENTS.md)
+
+## This app
+
+- Rails Agent mounted at `/agents`
+- Demo ecommerce models: `Collection`, `Product`, `Order`, `OrderItem`
+- Seed data: `bin/rails db:seed` (order numbers like `ORD-DEMO-1001`)
+
+## First agent (database Knowledge)
+
+Reference implementation: `app/agents/store_assistant/`
+
+```bash
+bin/rails generate rails_agents:agent store_assistant --type knowledge --database
+bundle exec rails-agents sync store_assistant
+bundle exec rails-agents run store_assistant "Status of ORD-DEMO-1001?"
+```
+
+## BYOK
+
+Store OpenAI/Anthropic/etc. keys in **cloud dashboard → Settings → Providers**. Reference in agent.rb:
+
+```ruby
+model :gpt_5_mini, provider: :openai, credential: :company_openai
+```
+
+Never commit provider API keys to this repository.
+
+## Reusable capabilities
+
+Keep agent-specific files under `app/agents/<slug>/`. Put stable tools, skills,
+knowledge, or plugin manifests needed by multiple agents under
+`app/agents_library/`, then attach them through the agent's `imports.yml`.
+
+Do not move a capability into the Library until another agent needs it.
+
+## Taxonomy
+
+- **Knowledge** — understand and answer
+- **Workflow** — execute predictable processes
+- **Operations** — coordinate unpredictable real-world work
+- **Monitoring** — observe changes and respond
+
+See root gem `docs/AGENTS.md` for the full progressive path (tools → plugins → skills → channels → evals → deploy).

data/lib/generators/rails_agents/install/templates/initializer.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RailsAgents.configure do |config|
+  # Platform API key (https://cloud.rails-agent.com/dashboard/keys).
+  # Provider/model keys (BYOK) are stored in the cloud — reference them in agent.rb via credential:.
+  config.api_key = ENV["RAILS_AGENTS_API_KEY"]
+  config.project_id = ENV["RAILS_AGENTS_PROJECT_ID"]
+end

data/lib/generators/rails_agents/install/templates/library_README.md.tt

@@ -0,0 +1,28 @@
+# Agent Library
+
+Reusable capabilities shared by agents in this Rails application.
+
+- `tools/` — Ruby actions and service wrappers
+- `skills/` — reusable multi-step behavior
+- `packages/` — installable capabilities from Skills.sh, Microsoft APM, and Smithery
+- `knowledge/` — documents and data-source definitions
+- `connectors/` — external connection manifests
+
+Keep one-off capabilities inside `app/agents/<slug>/`. Move a capability here
+only when multiple agents should reuse the same implementation.
+
+Attach shared files in an agent's `imports.yml`:
+
+```yaml
+version: 1
+imports:
+  - kind: skill
+    slug: triage
+    from: library/skills/triage.rb
+  - kind: package
+    slug: frontend_design
+    from: library/packages/frontend_design
+```
+
+`rails-agents sync <agent>` uploads imported files into that agent's runtime
+bundle without duplicating the shared source in the repository.

data/lib/generators/rails_agents/install/templates/library_manifest.yml.tt

@@ -0,0 +1,5 @@
+version: 1
+
+# Workspace capabilities that may be reused by multiple agents.
+# Agents opt in through app/agents/<slug>/imports.yml.
+resources: []

data/lib/generators/rails_agents/install/templates/rails_agents_autoload.rb.tt

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Prevents Zeitwerk from treating agent definitions and shared assets as normal
+# application namespaces. Agents load through the Rails Agent runtime.
+Rails.application.configure do
+  config.before_configuration do
+    Rails.autoloaders.main.ignore(Rails.root.join("app/agents"))
+    Rails.autoloaders.main.ignore(Rails.root.join("app/agents_library"))
+  end
+end

data/lib/rails-agent-stack.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler.require for gem "rails-agent-stack" loads this file.
+require "rails_agents"

data/lib/rails_agents/background_agent.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsAgents
+  # @deprecated Use {OperationsAgent} for async / scheduled agents.
+  class BackgroundAgent < OperationsAgent
+    def self.inherited(subclass)
+      super
+      warn "[RailsAgents] BackgroundAgent is deprecated; use OperationsAgent instead.", uplevel: 1
+    end
+
+    def self.agent_kind
+      :operations
+    end
+  end
+end