---
title: Build a collections SaaS on venom
description: 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.
section: cookbook
order: 10
audience: [builder, operator]
sources: [packages/harness/src/session.ts, packages/harness/src/harness.ts, packages/harness/src/inbox/index.ts, config/orchestrator.yaml, services/go-orchestrator/internal/guardrails, services/go-orchestrator/internal/router, services/nodejs-cloud/lib/compliance/pack.ts, cli/src/compliance.ts, docs/build-an-agent-app.md, docs/voice-agents.md, docs/guardrails.md]
features: []
---

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](/docs/harness/saas-recipe.md). Read it first; this page wires it to the rest of venom.

## Architecture {#architecture}

```text
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](/docs/harness.md) |
| Orchestrator | one OpenAI-compatible endpoint; per-tenant keys, budgets, guardrails; local models first | [Orchestrator](/docs/orchestrator.md) |
| Guardrails | redact or block personal data and credentials before a prompt leaves | [Guardrails](/docs/security/guardrails.md) |
| Inbox and approvals | the human decisions | [Inbox](/docs/automation/inbox.md), [approvals over HTTP](/docs/server-api/approvals-and-questions.md) |
| Audit, compliance pack | the evidence | [Audit and compliance](/docs/security/audit.md) |
| Voice | speech today; calls are Coming | [Voice](/docs/voice.md) |

## 1. Route the agent's model {#route}

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`:

```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](/docs/orchestrator/configuration.md#loading)). 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](/docs/cookbook/cost-routing.md).

## 2. A key and a budget per tenant {#keys}

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.

```bash
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](/docs/orchestrator/keys-and-budgets.md), [spend](/docs/orchestrator/admin-api.md#spend)).

For a budget per account worked rather than per tenant, send `x-venom-intent` on the requests of that job
([intent spend accounts](/docs/orchestrator/keys-and-budgets.md#intents)).

## 3. Guardrails {#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.

```yaml
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](/docs/security/guardrails.md#catalog); the orchestrator side is
[`guardrails:` in orchestrator.yaml](/docs/orchestrator/configuration.md#guardrails).

## 4. The back-office agent {#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](/docs/harness/saas-recipe.md#tools); here they come from your own
module.

```ts
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](/docs/harness/embedding.md#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](/docs/cookbook/nextjs-app.md#worker) shows the wiring).

## 5. Human handoff {#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](/docs/server-api/approvals-and-questions.md#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.

```ts
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](/docs/automation/inbox.md), [`@venom/harness/inbox`](/docs/harness/entry-points.md#inbox).) Between people,
`venom handoff` passes a whole session to a teammate or another `venom serve` host
([handoff](/docs/automation/teams.md#handoff)).

## 6. The phone agent {#voice}

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:

```bash
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](/docs/voice/speech-api.md)).

> [!NOTE]
> Coming: realtime phone calls. The design is final (ADR 0043, summarized in
> [Realtime voice agents](/docs/reference/voice-agents.md)), but none of its six slices is merged yet: the
> orchestrator's streaming transcription endpoint (`GET /v1/realtime?intent=transcription`), the `@venom/voice`
> package, calls in `venom serve` (`/v1/calls`), the Twilio and Asterisk transports, the compliance and handoff
> layer, and the example agents with the console's Calls page. Names below follow the design and may change.

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 {#evidence}

| 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](/docs/security/audit.md#actions)) |
| 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](/docs/security/audit.md#compliance)) |

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 {#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](/docs/harness/saas-recipe.md#checklist) on the harness side

## Related {#related}

- [Build a SaaS on the harness](/docs/harness/saas-recipe.md): tenancy, tools and data handling in depth.
- [Your own tools and approvals](/docs/harness/tools-and-approvals.md).
- [Keys and budgets](/docs/orchestrator/keys-and-budgets.md), [routing](/docs/orchestrator/routing.md).
- [Voice](/docs/voice.md) and [the voice agent design](/docs/reference/voice-agents.md).
