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.
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 rakeGitHub Actions also emits a Cobertura coverage report at coverage/coverage.xml. The Codecov upload runs as a non-blocking best-effort step until the repository is connected to the Codecov GitHub app, so missing Codecov access does not fail the main CI job.
Undercover 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.