Build a collections SaaS on venom
Put the harness, the orchestrator, guardrails, human handoff and the compliance evidence together into a multi-tenant collections product, with the phone agent's design and what of it ships today.
This recipe builds the whole product around the agent: a collections back office where an agent reads overdue accounts and drafts the next step, a collector approves it, every tenant has its own key, budget and guardrails, and an auditor can check what happened. A phone agent that calls debtors comes last, and most of it is still being built: the parts that depend on unmerged work are marked Coming.
The agent design itself (tenancy, tools, approvals, data handling) is on its own page: Build a SaaS on the harness. Read it first; this page wires it to the rest of venom.
Architecture
collector's browser ── your web app (auth, queue, approval inbox)
│ HTTP
▼
agent worker (Node) ── one harness per tenant ── your tools ── your DB, mailer, payments
│ provider: the tenant's key
▼
venom orchestrator ── guardrails, budgets, routing, request log
│
┌────────────┼──────────────┐
vLLM / Ollama OpenAI, Qwen… speech models (venom-speak)
(your GPUs) (fallback)
phone agent (Coming): venom serve + @venom/voice, a harness session per call| Piece | Job here | Reference |
|---|---|---|
@venom/harness |
the agent loop, your tools, the permission gate, audit | Harness |
| Orchestrator | one OpenAI-compatible endpoint; per-tenant keys, budgets, guardrails; local models first | Orchestrator |
| Guardrails | redact or block personal data and credentials before a prompt leaves | Guardrails |
| Inbox and approvals | the human decisions | Inbox, approvals over HTTP |
| Audit, compliance pack | the evidence | Audit and compliance |
| Voice | speech today; calls are Coming | Voice |
1. Route the agent's model
Give the product its own alias, so you can change models without touching the app. Local first; the cloud target
only serves when the local engine is down or its key is set. In orchestrator.yaml:
routes:
- alias: collections
strategy: fallback
ttft_timeout: 15s
targets:
- {upstream: vllm, model: "${VLLM_MODEL:-Qwen/Qwen3-Coder-30B-A3B-Instruct}"}
- {upstream: ollama, model: "${VENOM_OLLAMA_MODEL:-qwen3:8b}"}
- {upstream: openai, model: gpt-5.4-mini} # skipped while OPENAI_API_KEY is unsetvllm, ollama and openai are upstreams the shipped config already defines. Reload with
POST /admin/v1/reload or SIGHUP (loading and reloading). To keep
account data on your own hardware no matter what, drop the cloud target, or add a keep_local guardrail (step 3).
Strategies other than fallback, such as cheapest, are in Add a provider key and route by cost.
2. A key and a budget per tenant
Mint one client key per tenant with the admin token. team labels the tenant in spend views and selects its
guardrails; budget caps its spend; allowed_models keeps it on the product's aliases.
curl -s -X POST http://127.0.0.1:8787/admin/v1/keys \
-H "Authorization: Bearer $VENOM_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"tenant-acme","team":"acme","rpm_limit":120,
"allowed_models":["collections","venom-fast"],
"budget":{"daily_usd":5,"monthly_usd":100}}'The answer holds the plaintext vk-… key once: store it in your secrets store against the tenant. A tenant over its
hard limit gets 429 budget_exceeded with x-venom-budget-reset; requests that can reach only local models cost
$0 and are never refused. venom-fast is in the list because compaction summaries use the fast tier. Change a
budget later with PATCH /admin/v1/keys/{id}; read spend per tenant with GET /admin/v1/spend?team=acme
(keys and budgets, spend).
For a budget per account worked rather than per tenant, send x-venom-intent on the requests of that job
(intent spend accounts).
3. Guardrails
Guardrails run in the orchestrator on every /v1 request, so they hold for the harness and for any other client.
The org layer applies to every tenant; teams: is keyed by the key's team label.
guardrails:
catalog: [credentials, card_numbers, national_ids, prompt_injection]
rules:
- {code: GR-ORG-PII-001, name: Emails, kind: content, action: redact,
match: {type: detector, detector: emails}}
teams:
acme:
rules:
- {code: GR-TEAM-RX-001, name: Account numbers stay local, kind: routing, action: keep_local,
match: {type: regex, pattern: 'ACME-\d{8}'}}credentials and card_numbers block, national_ids and the email rule redact, and the acme rule sends any
request containing one of its account numbers to local upstreams only. A block answers 403 guardrail_blocked with
the rule's code; a redaction passes with an x-venom-guardrail header. The rule format, every catalog entry and the
codes are in Guardrails; the orchestrator side is
guardrails: in orchestrator.yaml.
4. The back-office agent
One harness per tenant, using that tenant's key. The tools (lookup_account, propose_action) and the locked-down
policy are the ones from Build a SaaS on the harness; here they come from your own
module.
import { createHarness, type AuditSink } from "@venom/harness";
import { collectionsTools } from "./collections-tools.js"; // the InlineExtension from the SaaS design
import { auditSinkFor } from "./audit.js"; // an AuditSink writing rows tagged with the tenant
export function tenantHarness(t: { id: string; venomKey: string }) {
const audit: AuditSink = auditSinkFor(t.id);
return createHarness({
cwd: `/var/lib/collections/work/${t.id}`,
venomHome: `/var/lib/collections/venom/${t.id}`,
mode: "default",
compat: false, plugins: false, policy: null, subagents: false,
network: "offline",
rules: { deny: ["bash", "write", "edit", "web_fetch", "web_search"] },
audit,
guards: { maxToolCalls: 60, maxSeconds: 600, maxCost: 0.5 },
provider: { baseUrl: process.env.VENOM_BASE_URL!, apiKey: t.venomKey, defaultModel: "collections" },
});
}
export async function triage(t: { id: string; venomKey: string }, accountId: string) {
const harness = tenantHarness(t);
const session = await harness.createSession({ extensions: [collectionsTools(t.id)] });
try {
return await session.prompt(`Review account ${accountId} and propose the next action.`);
} finally {
session.dispose();
await harness.close();
}
}Run it in a long-lived worker, not a short serverless function (embedding in a worker).
For many concurrent runs and approvals from another process, run venom serve as the worker and drive it with
HarnessClient (the Next.js recipe shows the wiring).
5. Human handoff
Three levels, from the one you will use most:
- Propose, then a person acts.
propose_actiononly writes a row; your UI shows it; your code sends the letter or sets up the plan after a collector approves. The agent never holds the power to contact anyone. - Ask before a call. A tool without
readOnlyHintasks yourapprovecallback. Overvenom serveeach ask is anapproval_requestevent your UI answers withdecide, denied afterapprovalTimeoutMs(60 s by default) (approvals). - Escalate to the inbox. For a decision that may wait hours (a dispute, a hardship claim), post an item to the
shared inbox and wait for the answer. Collectors on the same machine answer it with
venom inbox; your UI can read and resolve the same files.
import { inbox } from "@venom/harness";
const store = new inbox.InboxStore(inbox.inboxDir(`/var/lib/collections/venom/${tenant}`));
const item = store.post({
kind: "question",
title: `Account ${accountId}: debtor reports a hardship, pause collection?`,
detail: summary,
agent: "collections",
safety: true, // never held back by the attention budget
});
const answer = await store.wait(item.id); // { action: "approve" | "reject" | "redirect" | "take-over", message? }(Inbox, @venom/harness/inbox.) Between people,
venom handoff passes a whole session to a teammate or another venom serve host
(handoff).
6. The phone agent
What ships today is the orchestrator's audio API: POST /v1/audio/speech (streamed), GET /v1/audio/voices,
POST /v1/audio/transcriptions and /v1/audio/translations, behind aliases with fallback and pricing like chat.
The shipped venom-speak alias speaks through a local Kokoro server when you run one, else OpenAI:
curl -s http://127.0.0.1:8787/v1/audio/speech \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"model": "venom-speak", "input": "Your payment plan is set up.", "voice": "coral"}' -o reply.mp3You can build voicemail drops, call summaries and transcripts of recorded calls on that now (the audio API).
How the collections phone agent will fit in, per the design:
- A harness session per call, inside
venom serve, with the same business tools as the back office (verify_identity,lookup_account,propose_payment_plan,create_payment_plan,record_dispute). The permission gate, audit and guards apply to them unchanged. - Configured in
venom.yamlundervoice:(agents,routesfrom a number to an agent,twilioorasterisk), each agent a directory withagent.yaml,instructions.mdandtools.ts. - The
collections-usrules pack, modelled on the FDCPA and Regulation F: calling hours in every candidate time zone, a 7-in-7-days attempts ledger, a do-not-call list, the debt-collector disclosure only after identity is verified, limited-content voicemail, cease requests, and a speech guard that blocks threats and false claims and refuses any amount or date not found in a tool result. A refused dial answers403 compliance_refusednaming the rule. It is a starting point you edit, not legal advice. - Human handoff on the phone: the caller asks for a person, the model calls
transfer_to_human, speech recognition stays unsure, or the guard blocks twice; a 40-word whisper summary is played to the collector before the caller is bridged.
The orchestrator's guardrails (step 3) will still apply to the call's model requests; the speech guard is the call-specific layer after them.
7. Evidence for auditors
| What | Where | Check it with |
|---|---|---|
| Every permission decision, per tenant | your AuditSink (step 4) |
your own queries |
| Every model request: route, upstream, tokens, cost, session | the orchestrator's request log (SQLite) | GET /admin/v1/requests, GET /admin/v1/spend |
| Commands and file writes of agent sessions on a machine | the signed action log | venom actions verify (signed action log) |
| The org side on Venom Cloud: members, keys, spend, controls and their changes, incidents | the compliance pack, a signed ZIP from Settings, Compliance | venom compliance verify pack.zip --fingerprint "<fp>" (compliance packs) |
Call recordings, transcripts and the attempts ledger of the phone agent are Coming with the voice slices; the
design keeps them under <venomHome>/calls/ with 90-day retention and secret redaction before anything is written.
Checklist
- A product alias (
collections) with local targets first - One client key per tenant with
team,budgetandallowed_models; keys stored outside the code - Org guardrails (
credentials,card_numbers,national_ids) and per-tenantkeep_localrules - One harness per tenant:
compat: false,plugins: false,policy: nullor your own, unused tools denied - Side effects only through proposals, approvals or the inbox
- An
AuditSinkinto your database, and the request log kept - The SaaS checklist on the harness side
Related
- Build a SaaS on the harness: tenancy, tools and data handling in depth.
- Your own tools and approvals.
- Keys and budgets, routing.
- Voice and the voice agent design.