Legacy Workflows

This is the only documentation page for VoiceRun's legacy agent runtime model. Use it only to maintain an agent created before the organization-scoped environment, release, and entrypoint architecture.

New agents use:

1. An organization-scoped Environment, shared across agents.
2. Declarative resources in .voicerun/templates/, including kind: Deployment for runtime configuration.
3. Organization-scoped secrets referenced as {{ Secrets.organization.NAME }}.
4. A release that snapshots an agent, function, environment, and rendered manifest.
5. An entrypoint that routes phone, web, or native traffic to one or more releases.

kind: Deployment is a current declarative resource. The legacy term deployment on this page means the old function-to-AgentEnvironment deployment record created by vr deploy.

Migration map#

For a new project, follow Project Management, Declarative Resources, and Resource Management.

Legacy CLI reference#

Commands that accept an AGENT argument infer it from .voicerun/agent.lock when possible.

Per-agent environments#

vr get agentenvironments [AGENT] [NAME_OR_ID]
vr describe agentenvironment [AGENT] <NAME_OR_ID>
vr create agentenvironment [AGENT] <NAME>
vr delete agentenvironment [AGENT] <NAME_OR_ID>

vr create agentenvironment accepts:

The get, describe, create, and delete commands print a deprecation warning in interactive output. JSON output suppresses the warning so stdout stays machine-readable. Deleting a per-agent environment prompts for y/N; use --yes or -y to skip the prompt.

Deploying a function#

vr deploy <ENVIRONMENT>
vr deploy production --yes

vr deploy creates a legacy deployment against a per-agent environment. It shows a Deploying and prewarming sandbox... spinner while the API prewarms the selected function. A failed prewarm does not undo the deployment; the first call falls back to an on-demand build.

After a function version has been referenced by a legacy deployment, a later vr push creates a child function version and updates .voicerun/agent.lock. Existing deployments continue serving the old immutable function version until the new version is deployed.

Debugging a legacy agent#

vr debug pushes local code unless --skip-push is set and uses the per-agent debug environment by default.

Legacy variables#

Legacy variables are database resources merged into context.variables at session start. Organization variables are visible to every agent. An AgentEnvironmentVariable is visible only in its agent environment and overrides an organization variable with the same case-sensitive key.

vr get variables --org
vr get variables --agent <agent> --environment <environment>
vr describe variable <name-or-id> --org
vr describe variable <name-or-id> --agent <agent> --environment <environment>
vr create variable SUPPORT_EMAIL help@example.com --org
vr create variable GREETING_VOICE nova --agent <agent> --environment production
vr delete variable <name-or-id> --org
vr delete variable <name-or-id> --agent <agent> --environment production

--masked hides a value in CLI listings and the web UI while still injecting the real value at runtime. vr get variables --json returns organizationVariables and environmentVariables; the latter is null when no agent-environment scope was queried.

For current projects, place non-sensitive values under Deployment.spec.variables and reference organization secrets for credentials.

Phone-number assignments#

An assignment stores agentId and agentEnvironmentId on a phone-number record so inbound calls route to a legacy agent environment.

vr get assignments [AGENT] [PHONE_OR_ID]
vr describe assignment <PHONE_NUMBER>
vr create assignment [AGENT] <ENVIRONMENT> <PHONE_NUMBER_ID>
vr create assignment [AGENT] <ENVIRONMENT> <PHONE_NUMBER_ID> --configure
vr delete assignment <PHONE_NUMBER>
vr delete assignment <PHONE_NUMBER> --skip-unconfigure

Without --configure, VoiceRun records the assignment but does not reconfigure the telephony provider. --configure updates the provider so inbound calls route to the agent. --skip-unconfigure removes the assignment without changing the provider.

Current projects use vr create entrypoint phone and route the entrypoint to a release.

Agent-level telephony#

Legacy outbound session events selected the provider stored directly on the agent:

vr update agent <NAME_OR_ID> --telephony <PROVIDER_NAME_OR_ID>
vr update agent <NAME_OR_ID> --clear-telephony

The reserved platform IDs voicerun and voicerun-sbc[:region] were accepted without provider lookup. Current outbound calls use the provider and caller ID configured on a phone entrypoint.

Legacy dashboard workflow#

The old dashboard workflow was:

1. Create an agent from Agents.
2. Open the agent's Environments tab and add a per-agent environment.
3. Create and save a function under Functions.
4. Choose Deploy Version and select the per-agent environment.
5. From Environments, choose Add Phone Number to assign a number.

Configuration such as STT, recording, tracing, webhooks, variables, and failover was saved directly on that environment. Saving an environment setting did not require redeploying its function.

Legacy HTTP routes#

Starting an inbound call#

Telephony providers sent inbound calls directly to an agent and per-agent environment:

POST https://api.voicerun.com/v1/agents/<AGENT_ID>/call?environment=<ENVIRONMENT_NAME>

AGENT_ID came from the agent details URL. ENVIRONMENT_NAME was the lowercase per-agent environment name. Twilio or Infobip numbers were configured in the provider dashboard to send a POST request to this URL.

Current phone traffic enters through a phone entrypoint.

Environment-configured session webhooks#

The old dashboard stored a session webhook URL and generated signing secret on each per-agent environment under Agents → [Agent] → Environments → Webhook Settings.

The API updated or removed that configuration with:

PATCH /v1/agents/{agentId}/environments/{environmentId}

Example request body to enable delivery:

{"webhookUrl": "https://your-api.com/webhooks/voicerun"}

The response returned data.webhookSecret, which was shown once. The secret could be rotated with:

POST /v1/agents/{agentId}/environments/{environmentId}/regenerate-webhook-secret

The webhook was disabled by patching both webhookUrl and webhookSecret to null.

Current projects declare a kind: Webhook resource and supply its signingToken through an organization secret.

Legacy observability fields#

Legacy sessions store their environment in agentEnvironmentId. The session-list filter is:

filters[agentEnvironmentId]=<AGENT_ENVIRONMENT_ID>

Current sessions use the organization-scoped environmentId. Evaluator session views may encounter either value when they process historical sessions.

Legacy agent-to-agent session events#

The legacy agent transfer form targeted an agent and per-agent environment directly:

yield TransferSessionEvent(
    agent_id="technical_support_agent",
    environment="production",
    data={"conversation_context": "payment_issue"},
)

StartSessionEvent also started a session with an agent and environment:

class StartSessionEvent(Event):
    def __init__(
        self,
        agent_id: str = "",
        environment: str = "",
        input_type: str = "",
        input_parameters: dict = {},
        parameters: dict = {},
    )

For input_type="phone", input_parameters accepted toPhoneNumber, fromPhoneNumber, timeout, timeLimit, statusCallbackUrl, statusCallbackMethod, and byoc. If fromPhoneNumber was omitted, the environment's assigned number was used. input_type="mic" accepted an empty mapping. parameters became initial session context.

Use an outbound phone entrypoint and vr outbound call <ENTRYPOINT> for the current outbound flow.

Legacy error fallback#

Error Fallback is a per-agent-environment safety net for live phone calls. It transfers a failing call to a number or invokes a webhook. This is separate from handler-level completion retries and fallbacks.

Triggers#

1. No-response timeout: after caller input, the runtime waits for the agent to begin responding. A timeout records one occurrence per session. Occurrences are counted across the same agent and environment in a sliding window and cleared as soon as the agent responds successfully.
2. Call or stream error: a hard telephony or stream error invokes the fallback immediately for that call.

Dashboard configuration#

Open Agents → [Agent] → Environments, open Failover on the environment, choose a type and value, tune the timing fields, and save.

With Phone, VoiceRun transfers the active call through its Twilio or Telnyx provider. With Disabled, no fallback action runs and the failed session ends.

With Webhook, VoiceRun sends the call parameters as JSON and appends the URL-encoded error message as an error query parameter:

POST https://your-app.example.com/voicerun/error?error=<url-encoded-error-message>
Content-Type: application/json

A 2xx response containing TwiML takes over the active call. Any other response body is ignored, a non-2xx response is treated as failure, and the call proceeds toward termination.

Fallback webhooks use the standard HMAC-SHA256 headers:

VoiceRun generated a per-environment secret prefixed with whsec_ and returned it as errorFallbackWebhookSecret. Older environments without a secret sent unsigned fallback requests. The secret was rotated with:

POST /v1/agents/{agentId}/environments/{environmentId}/regenerate-error-fallback-webhook-secret

Rotation invalidated the old secret immediately. Cloning an environment generated a different secret for the clone.

Occurrence behavior#

• A session contributes at most one timeout occurrence.
• Occurrences outside the configured window are discarded.
• Below the threshold, the call keeps waiting.
• At the threshold, the fallback runs and the session fails.
• A successful response clears occurrences for that agent and environment.

Reasonable starting values were an 8–15 second timeout, threshold 5, and 300-second window. Webhooks supported dynamic routing; phone fallbacks supported a fixed handoff.