Undercover Agents is an open-source, multi-tenant AI platform for building, operating, and publishing agentic systems from a Rails application.
It is designed for teams that want more than a thin SDK. You can configure agents, orchestrate workflows, connect external systems, package reusable knowledge, and expose the result through branded chat or API channels, all inside the same product.
- AI agents with tools, subagents, skills, and optional capabilities
- Visual workflows called Missions for multi-step LLM and automation pipelines
- Retrieval and knowledge experiences backed by RAG flows and skill catalogs
- Internal pilots, AI assistants, and customer-facing chat experiences
- Published agent or mission endpoints through web, API, and external channels
- Multi-tenant by design, with workspace-style Operations inside each tenant
- Visual mission designer for orchestrating prompts, APIs, tools, control flow, and outputs
- Plugin-first architecture for connectors, tools, channels, capabilities, and RAG modules
- Builtin product-manual skill catalogs for admin, agents, missions, channels, test suites, skills, tools, and RAG
- Built-in admin assistant, playground, inspector, API docs, and job dashboard
- Agent Alpha can now inspect agent chat history and run synchronous debug prompts against agents through the agent-designer runtime tools, using the same persisted chats/messages the inspector shows.
- Rails-native stack with Hotwire, Haml, Tailwind, Solid Queue, and Falcon
| Concept | What it means |
|---|---|
| Tenant | The top-level isolation boundary for users, operations, connectors, and preferences |
| Operation | A workspace inside a tenant that scopes agents, missions, tools, skill catalogs, RAG flows, and channels |
| Agent | A configurable LLM-backed assistant with tools, skills, subagents, and capabilities |
| Mission | A visual workflow for orchestrating multi-step AI or automation behavior |
| Connector | A connection to an external provider or system |
| Tool | A runtime ability exposed to agents or missions |
| Skill Catalog | A library of packaged knowledge that agents can activate on demand |
| Channel | A published invocation surface for agents or missions |
- Ruby 4.0.4
- Rails 8.1
- Falcon application server
- PostgreSQL
- Haml views
- Tailwind CSS v4
- Hotwire: Turbo + Stimulus
- Importmap for JavaScript delivery
- React + React Flow for the mission designer
- Solid Queue + Mission Control Jobs
- RSpec, Capybara, RuboCop, haml-lint, Brakeman, bundler-audit
- Ruby 4.0.4
- PostgreSQL running locally with the pgvector
vectorextension available - Bundler
- Node.js and
pnpm(via Corepack or a local install)
Most integrations are optional. You can boot the app locally without configuring an LLM provider, but AI features that depend on a default model will stay unavailable until you add one.
git clone https://github.com/undercoveragents/undercoveragents.git
cd undercoveragents
bundle install
pnpm installbin/setup --skip-serverThis installs missing gems if needed, prepares the database, and clears old logs and temp files.
Default bundle exec rspec runs only the repository's app and plugin specs under spec/ and plugins/**/spec/, and excludes system specs unless you target them explicitly.
Fresh environments that render the mission designer in request specs also need the esbuild bundle in app/assets/builds; run pnpm run build:mission once if you are not already running bin/dev or bin/ci.
bin/ci runs the RSpec step with CI=1 so local coverage matches GitHub Actions' eager-load test mode.
bin/devThis starts:
- Falcon on
http://localhost:3000 - Tailwind watcher
- Mission designer JavaScript watcher
- Solid Queue worker
After setup, the app seeds a default system administrator account:
- Email:
admin@localhost - Password:
Changeme123!
You can override those defaults before first setup with ADMIN_EMAIL and ADMIN_PASSWORD.
The bootstrap flow also creates a default tenant plus its two core operations:
HeadquarterDefault
Use the shared sign-in page at /login for local sign-in or already-linked external accounts, or tenant-specific login pages at /tenants/:tenant_id/login.
First-time external sign-in and external-account linking must start from the tenant-specific login page.
For hosted onboarding, /try-in-cloud creates a brand-new workspace and first admin with either email/password or Google when a Google authentication connector is enabled. The initial workspace name is generated from the admin email and can be renamed later.
Normal user management in the admin UI is tenant-scoped, including for system administrators; cross-tenant administration belongs on the dedicated tenant-management surfaces.
To enable the full AI feature set:
- Go to Admin -> Connectors and add an LLM provider.
- Go to Admin -> Preferences and select the default model.
- Create or edit an agent and start testing in Playground.
- Create an agent and open it in Playground.
- Build a Mission with an input node, an LLM node, and an output node.
- Add a tool backed by a connector.
- Create a skill catalog and attach it to an agent.
- Publish an experience through a channel.
app/ Rails application code
config/ Rails configuration, routes, initializers, builtin agents and skills
db/ Schema, migrations, seeds, queue schema
plugins/ Plugin-based extensions for connectors, tools, channels, capabilities, and RAG modules
spec/ Test suite
website/ VitePress marketing site
Undercover Agents is intentionally plugin-oriented. The application already uses that pattern internally for:
- connectors
- tools
- channels
- capabilities
- RAG modules
If you want to add a new integration or runtime surface, plugins/ is usually the right place to start.
Issues and pull requests are welcome.
Before opening a PR, run:
bundle exec rakeUndercover Agents is under active development. The core product is usable today, but some extension points and internal APIs may continue to evolve as the open-source release matures.
Special mention to ruby_llm, whose beautiful and easy-to-use API made this project possible.
Project by Mirko Mignini. Open sourced under the Apache 2.0 License. See LICENSE.md.
