Skip to content
Docs menu

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.

View .md

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 unset

vllm, 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:

  1. Propose, then a person acts. propose_action only 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.
  2. Ask before a call. A tool without readOnlyHint asks your approve callback. Over venom serve each ask is an approval_request event your UI answers with decide, denied after approvalTimeoutMs (60 s by default) (approvals).
  3. 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.mp3

You 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.yaml under voice: (agents, routes from a number to an agent, twilio or asterisk), each agent a directory with agent.yaml, instructions.md and tools.ts.
  • The collections-us rules 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 answers 403 compliance_refused naming 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, budget and allowed_models; keys stored outside the code
  • Org guardrails (credentials, card_numbers, national_ids) and per-tenant keep_local rules
  • One harness per tenant: compat: false, plugins: false, policy: null or your own, unused tools denied
  • Side effects only through proposals, approvals or the inbox
  • An AuditSink into your database, and the request log kept
  • The SaaS checklist on the harness side