CumulusDocs
Open Studio
On this page

Build and test recipes

Use these short sequences to save a test version, simulate a caller, release reviewed behavior or roll back a change. Each step links to its request and response fields. For a complete phone workflow, start with the equipment-service guide.

Prerequisites

Connect your coding agent or the API with a sandbox member or admin key. Check the selected environment with environments.list. Use IDs returned by requests, and retain an idempotency key for each mutation. Simulations require open run admission; check runs.capacity and contact Cumulus if the environment has not been configured.

Create and publish without going live

  1. agents.create: create from a template. The response supplies the agent ID and draft identity/revision.
  2. drafts.edit: send typed edits with that draft ID and expected_revision. Carry the returned revision forward.
  3. drafts.validate: fix errors and validate again. Keep the next version returned by validation.
  4. publications.publish: pass the draft ID, current revision, validated version and live: false. Use the actual version returned, including on an idempotent replay.
  5. agents.get: verify the live head did not change.

Result: a test publication exists. New API-started runs that omit a version still use the previous head; incoming numbers retain their assigned publication. A new agent may have no live head yet.

Always send live: false when publishing a test version. Leaving it out can change the live head. Editing a draft does not change an existing publication.

Import and simulate a phone agent

  1. agents.import_inspect: inspect the Retell export and resolve model-binding and secret diagnostics. See Import from Retell.
  2. agents.import: import the resolved configuration. This creates a draft.
  3. Validate and publish the test version using the workflow above.
  4. test_suites.create: define simulated callers and assertions appropriate to the agent. Read the schema for the suite kind and case fields.
  5. test_runs.estimate: inspect the estimate before starting work.
  6. test_runs.create: run the suite against the selected agent version.
  7. Poll test_runs.get until it completes or is cancelled, then inspect test_runs.results and failing test_runs.trial transcripts.

Result: the assertions produce a verdict for the selected version without dialing a phone. A trunk and number are not required for text simulations.

Release the tested behavior

A test publication requires test: true when run. To release the behavior for regular calls or tasks:

  1. Read the current draft and confirm it contains the changes you tested.
  2. Validate it and keep the next version returned by validation.
  3. Publish with that draft ID, revision and version, and live: true.
  4. Read the publication and verify its version and digest. New requests that omit version select this head.
  5. For incoming calls, reassign the number and check its returned publication version.

Promotion changes which existing publication is the head. It does not remove a test publication's test-only restriction. Use it to select an earlier live version during rollback; review a conflict instead of guessing a newer head.

Start and follow a cloud run

Read runs.create, choose a published version, supply the required input and start a cloud run. Follow runs.events or poll runs.get. Once ended, read runs.result, the transcript and usage.

Use the complete curl, TypeScript and Python examples to carry the run ID from creation into subsequent requests.

Result: the run reaches a terminal state under a fixed publication version. Read the result’s state before using its output. If run creation returns outcome_unknown, retry the same creation request with its original idempotency key.

Roll back the live head

List publications, inspect the intended earlier version and read the current head. Promote the earlier version with the current expected_head_version, then verify the new head with agents.get.

Result: subsequent API-started runs that omit a version use the earlier publication. For incoming calls, reassign the number after rollback and verify its publication pin. Rollback does not rewrite completed or in-flight runs.

Diagnose a refused call

Read the error’s code and details.reason. Check the selected environment, run capacity, trunk, caller-ID number and required dynamic variables. Troubleshooting lists the recovery for each refusal. Fix the cause before retrying.

Phone tests dial real numbers: runs.create with channel phone places a call even when test: true. Use simulations for testing without a call.

Content version af23481dCustomer SDKMarkdown source
Build and test recipes · Cumulus developer docs