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:
  systemPrompt: |
    You are a customer calling this agent. Keep turns short and realistic.
  numberOfSimulations: 5
  provider: gemini_live
  model: gemini-3.1-flash-live-preview
  voice: Aoede
  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#

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: openai
  model: gpt-4o

Common fields#

judge evaluators#

extraction evaluators#

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: openai
  model: gpt-4o

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).
• 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.