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'
  region: us-central1-a
  variables:
    LOG_LEVEL: info
    FEATURE_FLAG: "true"
  stt:
    model: flux-general-en
    language: en
    failover:
      model: nova-3
  turnTaking:
    mode: smart_turn
    externalEndpointing: 300
    smartTurnVadStopSecs: 0.4
    smartTurnStopSecs: 3.0
    smartTurnTimeout: 5.0
  tts:
    provider: cartesia
    model: sonic-2
    voice: lyric
    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.

spec.stt#

spec.turnTaking#

spec.tts#

spec.recording#

spec.redaction#

spec.tracing#

Simulation#

A simulated caller used by vr simulate. The CLI submits the simulation's metadata.name; the API resolves spec from the active release's manifest, so 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
  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.

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

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 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: cartesia
  model: sonic-2
  voice: lyric
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.
• Required fields are present (e.g. Webhook.spec.url, Evaluator.spec.systemPrompt for judge, Evaluator.spec.assertion for deterministic).
• precondition and assertion (when present) are plain objects.
• Bounded fields are in range (e.g. numberOfSimulations is 1-100).
• metadata.name is unique per kind within a manifest.

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