Declarative Resources

Anything under .voicerun/templates/ is rendered with Helm at vr release time and snapshotted onto the release manifest. Each YAML document declares one resource:

apiVersion: voicerun/v1
kind: Deployment | Simulation | Webhook | Evaluator
metadata:
  name: <unique within the manifest>
spec:
  ...

Preview rendered output with vr render; validate spec shape with vr validate. Values referenced as {{ .Values.foo }} come from .voicerun/values.yaml (and overlays); {{ .Agent.Name }} and friends come from .voicerun/agent.yaml. Secrets are referenced as {{ Secrets.organization.NAME }} — Helm leaves the placeholder intact and the API resolves it at session start.

metadata.name must be unique within a manifest for each kind. It's the handle used by other commands (e.g. vr simulate --name <…>, vr evaluation list --type <…>).

Deployment#

Runtime configuration for the agent in an environment. Every field is optional except kind/metadata.name — omitted fields take platform defaults. The mode field decides whether handler.py is required at the project root.

apiVersion: voicerun/v1
kind: Deployment
metadata:
  name: my-agent-deployment
spec:
  mode: coderunner            # 'coderunner' (handler.py sandbox) or 'relay'
  dedicated: false            # true = per-release image + dedicated pods
  region: us-central1-a
  variables:
    LOG_LEVEL: info
    FEATURE_FLAG: "true"
  stt:
    model: nova-3
    language: en
    failover:
      model: gpt-4o-mini-transcribe   # must be a DIFFERENT provider
  turnTaking:
    mode: smart_turn
    externalEndpointing: 300
    smartTurnVadStopSecs: 0.4
    smartTurnStopSecs: 3.0
    smartTurnTimeout: 5.0
  tts:
    provider: elevenlabs
    model: eleven_flash_v2_5
    voice: rachel             # voice NAME, not a provider UUID
    language: en
    speed: 1.0
  relay:
    url: wss://my-relay.example.com/ws/agent
  recording:
    enabled: false
    location: gs://my-bucket/recordings/
  redaction:
    enabled: false
  tracing:
    enabled: true

Top-level fields#

spec.relay#

Only honored when mode: relay. Optional failover swaps to a backup relay endpoint on connection errors.

The URL is not parsed or probed at release time — vr release snapshots it into the release manifest verbatim, and it is first used when a session starts. See Relay Mode for transport, TLS, and authentication details.

spec.stt#

spec.turnTaking#

Not every model accepts every mode. The Deepgram Flux models (flux-general-en, flux-general-multi) are provider-only, and smart_turn is offered by nova-3, qwen3-asr-flash-realtime-2026-02-10, voicerun-asr-v1, voicerun-asr-realtime-v1, and ink-whisper only. See Speech to Text for the per-model matrix.

spec.tts#

spec.recording#

spec.redaction#

spec.tracing#

Simulation#

A simulated caller used by vr simulate. The CLI submits only the simulation's metadata.name (plus agent, environment, and an optional release ID); the API resolves the entire spec from the release's manifest — the latest release for the agent and environment, or the one pinned with vr simulate --release <id>. The version that runs is always the released one, not whatever is on disk.

apiVersion: voicerun/v1
kind: Simulation
metadata:
  name: happy-path
spec:
  direction: inbound
  mode: direct                # 'direct' (WebSocket, default) or 'pstn' (real phone call)
  systemPrompt: |
    You are a customer calling this agent. Keep turns short and realistic.
  inputData:
    accountTier: premium
  numberOfSimulations: 5
  provider: gemini_live
  model: gemini-3.1-flash-live-preview
  voice: Aoede
  # Optional: pin delivery variation so a simulated caller is reproducible.
  varietySeed: 12345
  phases:
    - type: ring
      durationSecs: 8
    - type: message
      text: "Thank you for calling. All representatives are busy. Please hold."
    - type: holdMusic
      durationSecs: 30
  loopPhases: true
  humanPickupAfterSecs: 90

Top-level fields#

For direction: outbound, omit phases, loopPhases, and humanPickupAfterSecs. Outbound simulations model the callee answering immediately, so the API rejects pre-pickup phases for outbound manifests. direction: outbound is also rejected together with mode: pstn — a PSTN simulation always dials the agent, so the persona is the caller by construction.

Outbound example#

apiVersion: voicerun/v1
kind: Simulation
metadata:
  name: appointment-reminder
spec:
  direction: outbound
  systemPrompt: |
    You are Dana Lee. You just answered your phone and are willing to talk briefly.
  inputData:
    customerName: Dana Lee
    appointmentTime: Tuesday at 3pm
    reason: confirm upcoming appointment
  numberOfSimulations: 3

PSTN simulations#

mode: pstn swaps the WebSocket for a real outbound phone call. The simulator originates the call through its telephony integration and drives it with the same persona; the agent answers a genuine inbound call, so its own session, recording, and billing behave exactly as they do for a real caller.

apiVersion: voicerun/v1
kind: Simulation
metadata:
  name: pstn-smoke
spec:
  mode: pstn
  systemPrompt: |
    You are a customer calling support. Ask one question, then say goodbye.
  numberOfSimulations: 1

• Each run is a real, billable call. vr simulate always confirms before submitting a PSTN run — keep numberOfSimulations low.
• The dialed number defaults to the one assigned to the agent and environment. Override with toNumber only when you need a different one.
• direction: outbound is rejected with mode: pstn.
• The pre-created sessions anchor the simulated caller's side. The agent-side session is created by its telephony ingress, so vr simulate --wait is skipped for PSTN runs.

spec.realism#

Real-world call conditions applied to the simulated caller's leg. By default a simulated caller is unnaturally polite — the persona engine waits for a clean end of turn, and the simulator drops its audio while the agent is speaking, so it cannot talk over the agent. The line is pristine too. Omit the block and none of that changes.

spec:
  systemPrompt: |
    You are an impatient customer with a billing problem. Keep every turn to
    one short sentence. If the rep starts explaining at length, cut them off.
  realism:
    seed: 4242                # pin for a reproducible run; omit for fresh randomness
    bargeIn:
      technique: both         # nudge | clip | both
      probability: 0.45
      afterAgentSpeechMs: 1200
      cooldownSecs: 7
      maxPerCall: 6
    background:
      profile: cafe           # none | hiss | cafe | street
      levelDbfs: -34
      eventsPerMin: 8
      events:
        - kind: dogBark
          atSecs: 12
    effects:
      muffle: 0.5
      room: 0.4
      gainDb: -6
    impairments:
      packetLossPct: 3
      dropoutsPerMin: 12
      dropoutMs: [250, 800]
      clipping: 0.2

The chain runs in the order the physical world applies it: the persona's voice, plus the room the same microphone picks up, then the handset, then the network. So effects reach the background bed too — muffling a caller in a cafe muffles the cafe.

realism.bargeIn

realism.background

The bed is mixed into every frame the caller sends, including the silence between its own utterances, because the room a real caller is standing in does not go quiet when they stop talking. Every profile except hiss is a real field recording, looped for the length of the call.

Each events entry:

realism.effects

How the caller's audio sounds before the network touches it. Applies to their voice and the background bed together, because one microphone picks up both.

realism.impairments

Manifest keys are camelCase, as everywhere else in a spec. The API translates them to snake_case (barge_in, after_agent_speech_ms, level_dbfs, gain_db, packet_loss_pct, dog_bark, …) when it calls the simulator, which is the form you will see in simulator logs.

Every range above is enforced by the API when it accepts the rendered manifest at vr release time, not by vr validate — see Validation.

spec.phases#

Phase entries play before the simulated persona starts speaking — useful for warm-transfer testing where the outbound leg waits through ringing/queue/IVR before someone "answers".

ivrMenu phase

Webhook#

Session-end webhook delivery configuration. The destination URL must be http(s).

apiVersion: voicerun/v1
kind: Webhook
metadata:
  name: my-agent-webhook
spec:
  url: https://example.com/voicerun/session-webhook
  events:
    - session.ended
  signingToken: "{{ Secrets.organization.WEBHOOK_SIGNING_TOKEN }}"

Top-level fields#

Evaluator#

Scores or extracts data from a session after it completes. Results are surfaced through vr evaluation list and vr evaluation info.

apiVersion: voicerun/v1
kind: Evaluator
metadata:
  name: resolution-judge
spec:
  title: Resolution Judge
  evalType: judge
  targetFormat: transcript
  systemPrompt: |
    Score the session 1-5 on whether the agent resolved the caller's
    request. Respond with a JSON object matching the response schema.
  responseSchema:
    type: object
    properties:
      score: { type: integer, minimum: 1, maximum: 5 }
      reasoning: { type: string }
    required: [score, reasoning]
  successCriteria:
    score: { ">=": 4 }
  apiProvider: google
  model: gemini-3.5-flash

Common fields#

Judge provider and model#

apiProvider and model are not validated when you push or apply the resource — both are plain optional strings on the API request, so any value is accepted and stored. The gate is at evaluation time, when the completion is dispatched. A misconfigured evaluator therefore looks healthy until the first session it runs against, then fails per-evaluation.

Two independent checks run then:

1. The provider must be dispatchable. Only five values map to a completion path: openai, anthropic, google, vertex, and vertex_maas. Anything else throws Unknown completion apiProvider: <value>. Note that alibaba, deepseek, and voicerun are legal apiProvider values elsewhere in the platform (they exist for cost attribution) — an evaluator can be saved with one of them and will then throw at evaluation time. Do not use them here.
2. The model must be registered for that provider. The named model has to exist as a registered model definition for the resolved provider, or the call errors with Model <model> not supported for <PROVIDER> provider.

The defaults are model: gpt-5-mini and apiProvider: openai, and they are applied independently. This is the most common way to trip check 2: setting apiProvider: vertex_maas without also setting model leaves the default in place and fails with Model gpt-5-mini not supported for VERTEX_MAAS provider. Whenever you change apiProvider, set a model that belongs to it.

  # Runs: gemini-3.5-flash is registered for the google provider.
  apiProvider: google
  model: gemini-3.5-flash

  # Fails at evaluation time: apiProvider changed, model left at the default.
  apiProvider: vertex_maas

Credentials. The declarative Evaluator spec has no field for a provider key — manifest-defined evaluators always run on VoiceRun-managed credentials. Where an evaluator is configured with an organization secret through the API instead, note that it applies to openai, anthropic, and google only: vertex and vertex_maas always run on VoiceRun's own GCP credentials, and a supplied secret is routed into the OpenAI-key slot that neither Vertex path reads, so it is effectively ignored.

judge evaluators#

extraction evaluators#

deterministic evaluators#

A deterministic evaluator asserts on the derived session view rather than calling an LLM — same input, same result, zero token cost. Use for purely factual checks: did a specific tool get called, did the caller say a specific word, was the duration in range.

apiVersion: voicerun/v1
kind: Evaluator
metadata:
  name: inbound-cancellation-request
spec:
  title: Inbound caller mentioned cancellation
  evalType: deterministic
  assertion:
    direction: "inbound"
    events:
      $any:
        name: "transcript_part"
        data.role: "user"
        data.content: { $icontains: "cancel" }

Session view fields the assertion (or a precondition) can read:

Operators:

Dotted field paths walk nested objects. Mixing operators and field names at the same level is rejected at evaluation time.

Bare primitive vs array input. When a predicate's value is a primitive and the input field is an array, the engine does membership matching (equivalent to $inc). This lets tags: "billing" work without $inc, and lets environment: "production" match against [id, name] regardless of whether you wrote the name or the ID. Scalar-vs-scalar equality is unchanged.

Event-payload checks via $any — ask questions like "did the caller use a phrase" or "did the agent reach a particular closing" without flattening the event stream up front:

apiVersion: voicerun/v1
kind: Evaluator
metadata:
  name: refund-mentioned
spec:
  title: Caller mentioned refund
  evalType: deterministic
  assertion:
    events:
      $any:
        name: "transcript_part"
        data.role: "user"
        data.content: { $icontains: "refund" }

apiVersion: voicerun/v1
kind: Evaluator
metadata:
  name: agent-closed-with-goodbye
spec:
  title: Agent ended with a goodbye
  evalType: deterministic
  assertion:
    events:
      $any:
        name: "transcript_part"
        data.role: "agent"
        data.content: { $icontains: "goodbye" }

Preconditions#

Any evaluator type can declare a precondition to gate whether it runs. If the predicate doesn't satisfy, the evaluator is skipped — the row is persisted with status="skipped" and a skipReason naming the failing field, no LLM call is made. This protects you from running expensive "did the agent handle the objection well?" evals against 1-turn hangups while keeping the skip auditable.

apiVersion: voicerun/v1
kind: Evaluator
metadata:
  name: objection-handling
spec:
  title: Objection Handling
  evalType: judge
  targetFormat: transcript
  systemPrompt: …
  responseSchema: { type: object, properties: { score: { type: integer } } }
  successCriteria: { score: { $gte: 4 } }
  precondition:
    turn_count: { $gte: 3 }
    duration_seconds: { $gte: 30 }

Filter skipped rows with vr evaluation list --status skipped or the web dashboard's status filter.

Values and Secrets#

Values files#

.voicerun/values.yaml is the base values file used by Helm. Per-environment overlays (e.g. prod.yaml, staging.yaml) live alongside it and are pulled in with --values prod.yaml on vr release, vr render, or vr simulate.

# .voicerun/values.yaml
variables:
  LOG_LEVEL: info
region: us-central1-a
stt:
  model: flux-general-en
  language: en
tts:
  provider: elevenlabs
  model: eleven_flash_v2_5
  voice: rachel
recording:
  enabled: false
tracing:
  enabled: true
webhook:
  url: null            # leave null to skip the Webhook resource entirely
simulation:
  numberOfSimulations: 1
evaluator:
  apiProvider: google
  model: gemini-3.5-flash

Secret placeholders#

Anywhere a string value lands in the rendered manifest, you can reference an organization secret as:

signingToken: "{{ Secrets.organization.WEBHOOK_SIGNING_TOKEN }}"

Helm leaves the placeholder intact through rendering. The API resolves it against organization secrets at session start, so secrets never round-trip through the release record itself. Create secrets with vr create secret.

Validation#

Both vr validate and vr render run shape-only validation against rendered manifests. The validator checks that:

• Each document has a known kind (Deployment, Simulation, Webhook, Evaluator).
• spec contains only the allowed top-level keys for that kind.

That is the whole of the client-side check — vr validate does not look inside a spec. Required fields, enum membership, numeric bounds, and metadata.name uniqueness are all enforced by the API when it accepts the rendered manifest at vr release time. For Simulations that includes numberOfSimulations (1-100), humanPickupAfterSecs (0-600), toNumber (E.164, and only with mode: pstn), the direction: outbound rejections for both phases and mode: pstn, and every realism range.

A manifest with an out-of-range value therefore passes vr validate and fails at vr release, with an error naming the exact key path:

Simulation "impatient-caller": realism.background.levelDbfs must be a number between -90 and -12 (got -5)

Because a top-level spec key is all the CLI checks, an older CLI will also reject a manifest using a newer field: spec.mode needs 1.7.1 or later, and spec.realism needs 1.7.15 or later.

Validator-level checks don't hit the database either, so they don't catch missing organization secrets or unknown providers — those are surfaced at vr release time when the API processes the manifest.