radioso

Radioso Cloud · Docs · Why Radioso? · Run locally · API reference · Contributing

Radioso is the open-source platform for designing and running customer-facing AI agents

Tried Parlant but wanting batteries included? Or looking for an open-source alternative for Fin, Rasa or Ada.cx?

Radioso is the platform for steering LLM conversations according to your rules. It answers from the documents you gave it, with citations so you can check its work. It carries a request across turns: collects what it needs, calls your tools, finishes the job. And when the conversation needs a human, it hands the whole thing to one instead of improvising. All of this happens inside rules you author — we call it guided autonomy. You don't have to enumerate every path in advance, and you don't have to accept whatever the model decides on its own.

Run it in Radioso Cloud or on your own infrastructure, so your data sits where you want it. Multi-provider, so no model lock-in. API-first, because you'll want to build on it.

The whole thing ships in this repo:

• Grounded answers — replies built on your own documents, cited back to them, with retrieval you can tune per agent.
• Directives — standing rules matched by meaning, in any language: "when the customer sounds anxious, slow down and confirm before acting." Write the rule once; it applies on every turn, on every surface.
• Routines — multi-turn flows you author in plain language and ship with the rest of the agent, no redeploy; the engine runs and resumes them turn to turn until the task is done.
• Skills — what the agent can do: grounded retrieval, your webhooks, Slack posts, customer email, or tools from your own MCP servers.
• Human takeover — an operator claims the conversation and replies as a named person; the Inbox queues waiting handoffs and routine approvals.
• Ray, the operator copilot — ask why a conversation went the way it did; when the answer is a change, Ray drafts it as a proposal you review and apply.
• Quality & Evals — triage weak answers, preserve one as a repeatable eval case in a single request, and verify the fix. Close the loop.
• Audience Pulse — a census of the last 30 days of visitor questions: named topics with exact counts, recurring grounding gaps, and content recommendations you can open as a draft document.
• Workbench — replay real conversations against your draft changes before they go live.
• Website embed — one script tag opens a themed chat widget on origins you approve.
• REST API, TypeScript SDK, and MCP — the same agent from your backend, your code, or clients like Cursor and Claude.
• Bring your own models — OpenAI, Anthropic, Gemini, or any OpenAI-compatible endpoint; per-workspace keys and per-capability model choice, changed without a restart.

Every surface hands its turn to the same engine, and every turn records which directive steered it, which skill it dispatched, and which routine step it was on. So when the agent does something you didn't expect, you don't guess — you open the trace, see which rule did it, and fix that.

Quick start

Fastest path. Create a workspace at app.radioso.ai. Radioso Cloud is this platform hosted in the EU, with every product feature you see below and your own model keys.

Run it yourself. You need Node.js 24+ and Docker Desktop. On Windows, configure Docker Desktop to use Linux containers. A provider API key (OpenAI, Gemini, or Anthropic) can wait — enter it when the bootstrap prompts, or add it later in the app under Settings → Credentials.

macOS or Linux:

./run-dev.sh

Windows PowerShell or Command Prompt:

.\run-dev.cmd

The bootstrap generates secrets and starts the full stack. OpenAI, OpenAI-compatible, and Gemini keys serve both text and embeddings; with a Claude key, the bootstrap asks which supported provider should create document embeddings.

Then, five minutes and three steps:

1. Register. The first registration on an empty server creates the organization and default workspace; the development stack verifies the account and signs you in.
2. Answer. Upload a document and ask about it. The reply comes back cited to the document it came from.
3. Act and hand off. On the agent's Skills tab, add a Notify Human skill named contact_human with a recipient email, then ask to speak to a person. The built-in contact routine takes over: it collects an email and a message, sends them to that recipient, and confirms. That flow is itself just routine data — authoring routines shows how to build your own.

That's the whole product in miniature. Everything else is tuning.

Development-stack notes: source is bind-mounted into the containers, backend TypeScript restarts on change, and prompt templates under backend/prompts/ are re-read per request. The Compose project is named radioso and keeps Postgres on 127.0.0.1:5432 — reachable from your machine, not from public interfaces. To run several stacks side by side, set a distinct COMPOSE_PROJECT_NAME together with RADIOSO_FRONTEND_PORT, RADIOSO_BACKEND_PORT, and RADIOSO_POSTGRES_PORT before your platform's launcher; Conductor workspaces pick up their CONDUCTOR_PORT allocation automatically.

Production concerns — registration email verification, mail configuration, secrets — live in Deployment and Authentication.

For Enterprise Edition development on macOS or Linux, ./run-ee-dev.sh starts Postgres in Docker and runs the backend, workers, frontend, and embed harness on the host with the commercial packages from ee/packages built in. Enterprise host-service development requires a Unix-like shell. Both open-source launchers remove generated Enterprise routes before starting the OSS stack.

How a turn works

Every human-facing turn takes one path: the conversation engine, a loop with four phases.

1. Gather — interpret the message: intent, query rewrite, routing.
2. Select — decide which skill or skills the turn needs.
3. Dispatch — run them through one invocation port.
4. Compose — build the reply from what they returned and the steering that applies.

The loop holds the mechanism; the behavior lives in small units you register.

• A skill is something the agent does — grounded retrieval, a lookup, a webhook call. It is dispatched through one port and returns a result. Retrieval itself is the retrieval.answer skill, reached the same way as every other capability.
• A directive is a standing rule that shapes how the agent behaves: a condition paired with an action, judged by the model by meaning — Radioso is multilingual, so a condition is never a keyword list — and added to the turn's instructions when it holds.
• A routine is a stateful, multi-turn flow authored as data — in the dashboard or over the API — validated as you write it and shipped with the agent's next revision, no redeploy. The platform compiles it into a graph the engine runs and resumes turn to turn.

Skills act, directives steer, routines carry a flow across turns.

    Web app · REST API · TS SDK · MCP server · Website embed
      (browser, your code, Node app, Cursor/Claude/ChatGPT)
                               │ a turn enters the engine
                               ▼
   ═══════════════════ Conversation engine ═════════════════════

      Gather ──▶ Select ──▶ Dispatch ──▶ Compose ──▶ reply
                   ▲           │
                   │           ▼
      ┌───────────────┐   ┌─────────────────┐
      │ Directives    │   │     Skills      │
      │ matched rules │   │ retrieval.answer│
      │ that steer    │   │ documents.search│
      │ selection &   │   │ assistant.chat  │
      │ the reply     │   │ your skill …    │
      └───────▲───────┘   └─────────────────┘
              │
      ┌───────┴───────┐
      │ Routines      │  an active flow projects a
      │ stateful      │  directive each turn, and can
      │ multi-turn    │  drive a skill, take an action,
      │ flows         │  or hand off to a person
      └───────────────┘

   ═════════════════════════════════════════════════════════════
                               │ retrieval.answer reads
                               ▼
   Your content ──▶ ┌──────────────────────────────────┐
   chunk + embed    │       Postgres + pgvector        │
                    │   documents · chunks · vectors   │
                    └──────────────────────────────────┘

Adding a capability or a rule means registering a unit, not editing the loop, and the engine is the only turn path the assistant uses. On eligible turns the engine fuses its pre-answer classification into one planning call, so a simple turn costs two model calls instead of five, with the staged calls as fallback — see Assistant turn spine.

Postgres is the system of record for everything, not just vectors: documents, chunks, embeddings (pgvector), conversations, settings, and audit events. Ingestion runs in a background worker, so uploads never block a turn. The engine itself is product-independent: the turn vocabulary lives in packages/conversation-contract/ and the pure runtime loop in packages/conversation-engine/, while Radioso's auth, retrieval, settings, persistence, and streaming stay in adapters the engine reaches through ports.

The long versions: Conversational directives and Conversational routines.

Talking to your agent

Five ways in: the web app, the REST API, the TypeScript SDK, an MCP client, and the website embed.

Choose the credential for the job. Personal tokens carry the issuing user's live workspace membership and expire within 90 days. Service accounts are stable workspace identities for CI and unattended workloads; create them under Settings → API access, and give each credential an expiry of at most 365 days. Their credentials authorize eligible role-aware workspace APIs.

Agent chat uses a separate credential created on that agent's Channels → API or Channels → MCP card. It has no member or admin role: it is bound to one agent and one audience, expires at the time you choose, and is shown once. Workspace payloads carry both id and publicRouteKey: use id in API calls and publicRouteKey in dashboard URLs (/w/<key>/...). Full account and session flows: Authentication.

Ask a question. Put the chosen agent's id in the path and use a REST-audience agent credential. Each turn runs through the engine above: it selects retrieval.answer when evidence is needed, applies whatever directives match, and resumes an active routine if there is one.

curl -sS \
  -H "Authorization: Bearer <agent-rest-credential>" \
  -H 'Content-Type: application/json' \
  -d '{"message":"What does the FAQ say about refunds?","stream":false}' \
  http://localhost:8080/api/v1/agents/<agent-id>/chat

Grounded retrieval without the persona. When you want search or answer generation over workspace content with no assistant behavior, call retrieval directly:

curl -sS \
  -H "Authorization: Bearer <api-credential>" \
  -H 'Content-Type: application/json' \
  -d '{"query":"refund policy"}' \
  http://localhost:8080/api/v1/retrieval/search

curl -sS \
  -H "Authorization: Bearer <api-credential>" \
  -H 'Content-Type: application/json' \
  -d '{"query":"What does the FAQ say about refunds?"}' \
  http://localhost:8080/api/v1/retrieval/answer

/api/v1/retrieval/search returns matches instead of an answer. Both accept per-call filters such as metadataFilter, and both accept agentId to run with one agent's retrieval settings and source scope — the response reports which agent it measured in agentScope. See Documents and search.

curl -sS \
  -H "Authorization: Bearer <api-credential>" \
  http://localhost:8080/api/v1/skills

See why. Responses are lean by default. Add includeDebug: true and diagnostics arrive under a debug field — routing, retrieval summaries, activity traces, and full evidence — instead of mixing into the user-facing payload.

Everything else. Agents and their per-skill settings live under /api/v1/agents; routines are authored per agent under /api/v1/agents/<agentId>/routines (create, update, validate). GET /api/v1/skills lists the skills the engine can select. History, settings, the document-type catalog, answer feedback, quality triage, and usage subtotals each have their own routes — start at the API index or the OpenAPI reference.

TypeScript SDK

The SDK wraps role-aware workspace chat, streaming, and document management, and follows the same lean-response contract (response.debug when you asked for it):

import { createRadiosoClient } from "@radioso/typescript-sdk";

const client = createRadiosoClient({
  baseUrl: "http://localhost:8080",
  apiToken: process.env.RADIOSO_API_TOKEN!,
});

await client.documents.create({
  title: "Support FAQ",
  content: "...",
  source: { kind: "website", url: "https://example.com/docs" },
});

for await (const event of client.chat.stream({ message: "Summarize the FAQ" })) {
  if (event.type === "chunk") process.stdout.write(event.text);
}

That client uses the personal or service-account credential supplied as apiToken. A client that should only converse with one agent uses a separate REST-audience agent credential with POST /api/v1/agents/{agentId}/chat.

Start with Getting started and Basic usage.

MCP

The standalone HTTP server has two separate MCP surfaces. /mcp exposes ask_agent, which talks to exactly one agent through its full turn loop. A signed-in user with permission to manage that agent creates its audience-bound credential from Channels → MCP and sends the one-time secret to standalone.

/operator/mcp lets the signed-in person connect an OAuth-capable client to Ray's governed read, probe, and proposal tools. Start under Settings → API access, choose a workspace and scopes in browser consent, then manage the grant from the same page. See Operator MCP OAuth access for the current tool boundary and exact-build compatibility gate.

The package has no stdio MCP entrypoint. Hosted clients require a public HTTPS deployment; local clients can use the standalone HTTP URL supported by their connection profile.

Website embed

One script tag, pasted on any page of an approved origin, opens a Radioso-hosted chat iframe — no backend work on the host site, and origin policy stays under your control. The widget, theming, and origin approval are part of the open-source build; Enterprise Edition adds human-contact routing on top. The Web chat page under an agent's Channels section holds both placements — public link and website widget — with each public-launch credential's status and last use; rotation stops new sessions on the old value immediately. Public-launch credentials are separate from personal and service API credentials. See the website embed quickstart.

Configuration and operations

Short version here; every link goes to the full reference.

• Models and keys. Workspaces store their own provider keys (encrypted with CONNECTOR_ENCRYPTION_KEY) and pick a model per capability — chat, rewrite, rerank — with no restart. Resolution at chat time is agent override → workspace preference → environment default. Settings API →
• Ingestion. Uploads create durable Postgres jobs first; chunking, parsing, and embedding run in a background worker. Optional metadata extraction classifies each document against a workspace-defined type catalog and writes typed tags that per-agent retrieval rules can filter and boost on. Document metadata → · Document processing →
• Website crawler. POST /api/v1/document/crawl crawls a site with the bundled provider and publishes pages through the normal ingestion pipeline. It identifies as RadiosoCrawler/1.0 and records 401/403/429 responses as failed pages rather than ingesting them. Website crawler →
• Deployment. Backend, frontend, and workers are separate services; the backend migrates the database on startup. Worker dispatch polls by default, with Cloud Tasks and AMQP drivers for push; rate limits and reverse-proxy hops are environment-tuned. Deployment → · Self-hosting operations →
• Observability. Runtime flags, /metrics, and optional PostHog or Sentry sinks. Observability →
• Authenticated LLM request limits. Assistant chat and retrieval answer/search share a durable operator-configured limit. Browser sessions are scoped by account and workspace; personal and service credentials receive separate credential-specific buckets. Deployment →

Docs

The full documentation lives at docs.radioso.ai: quickstarts, core concepts, the API reference, and operator runbooks. Architecture deep-dives are in-repo under docs/architecture/, starting with the assistant turn spine; docs/README.md indexes the rest.

Contributing

Contributions are welcome. Run ./run-dev.sh on macOS or Linux, or .\run-dev.cmd on Windows, for a full local stack. Then read CONTRIBUTING.md for per-package test targets, the pnpm run ci:local check to run before opening a pull request, and the Conventional Commits format the history uses.

backend/         Express API and background document worker
frontend/        Next.js application
typescript-sdk/  First-party TypeScript SDK
packages/        Shared local packages (conversation engine, MCP server, parser, contracts)
infra/           Docker Compose and Terraform
docs/            Product and SDK guides

Found a security vulnerability? Report it privately — see SECURITY.md. By taking part you agree to the Code of Conduct.

License

Radioso is dual-licensed:

• The open-source edition is licensed under the Apache License, Version 2.0.
• The files under ee/ are Radioso Enterprise Edition, commercial source-available software governed by ee/LICENSE, and are not covered by Apache 2.0. We are happy for everyone to run Radioso for business and personal purposes; ee/ holds the features and setups we need to run Radioso as a cloud service, and using them requires a commercial license. Contact us for inquiries!

See NOTICE for attribution and the Enterprise Edition.