On this page
Core concepts
A Cumulus agent describes a conversation: what to ask, which tool to call and where to go next. Cumulus runs that conversation; your application supplies the business services behind its tools.
Agent, draft, publication and run
Suppose you change a service agent's greeting. That edit updates its draft, not the calls already in progress. Publishing saves a numbered publication. Starting a call creates a run that keeps that version, even if someone later changes the greeting again. The head is the version new requests select when they do not name one.
| Term | Meaning |
|---|---|
| Agent definition | The prompts, steps, routing rules and tool contracts you edit in TypeScript or Studio. |
| Draft | The editable working copy, identified by a draft ID and revision number. |
| Publication | A saved version that cannot be edited. Its digest identifies the compiled content. |
| Head | The publication selected when a new request omits its version. Phone numbers have their own version assignments. |
| Run | One execution, identified by run_id. |
| Conversation | The conversation within a run. Tool requests carry its ID in call.call_id, alongside the different call.run_id. |
| Node and edge | One step in the conversation and a connection telling it where to go next. |
| Component | A reusable group of steps, such as availability, slot selection and booking confirmation. |
| Tool contract | The inputs, outputs, endpoint and execution policy for a business operation. |
| Environment binding | Connects a logical name such as customer_api to the endpoint or credential for one environment. |
| Integration | Connects an agent to caller context, phone numbers and events. |
| Project | Groups agent and integration definitions. |
| Effect | One attempted external operation, such as a booking request. Its identity is sent to your endpoint in Idempotency-Key. |
| Receipt | A saved record used to inspect or recover an operation. SDK receipts track authoring work; platform effect receipts track tool attempts. |
The tool contract belongs in the graph; its implementation stays in your application. See definitions and publication and recovery.
Environments and credentials
An environment keeps one set of agents, runs, secrets and numbers together. Sandbox and production use different resources. The API identifies the selected environment by its tenant ID. Check that ID before changing configuration or placing a call.
Run admission controls whether the environment can start work. Capacity is its concurrent-run limit. Model and speech credentials authorize the providers an agent uses. Your administrator configures those resources in workspace settings.
A secret reference names a stored credential and its version, so the graph can use it without containing the credential value. Your business endpoint still checks who may access a record and handles duplicate requests safely.
Testing and live effects
Local SDK validation checks a definition without contacting Cumulus. Remote preview reads configuration. Apply changes a draft; publish saves a version. Assigning a phone number and dialing are separate operations.
live: false creates a test publication, which requires test: true when run. Selecting it as head does not remove that restriction. A test phone run still dials real numbers and can call real tools. It is excluded from customer billing, lifecycle notifications and event triggers.
Simulation suites use mock responses for customer tools. Browser tests check speech without a carrier call. Private keypad verification and tokenization require telephone runs; see testing methods.
A cloud task's result is structured data copied from its declared variables. A JSON-looking reply in the transcript does not automatically become that result. Analysis extracts configured fields from the completed transcript. Check a booking or other business transaction through its tool response.
Concurrency and retries
A draft's revision changes when someone edits it. Send the revision you read as expected_revision; a conflict means you must review another author's changes before editing again. expected_head_version performs the same check when selecting a head.
An idempotency key identifies one intended request. If a booking request times out, the booking might already exist. Look it up or replay the same request with the same key; a new key could create another booking. See retry handling.