On this page
Core concepts
Use these names consistently in prompts, code and API requests.
Agent, draft, publication and run
| Term | Meaning |
|---|---|
| Agent | A named resource with cloud and/or phone behavior. |
| Draft | The one editable working copy; updates compare the expected revision. |
| Publication | An immutable numbered version identified by a compiled-plan digest. |
| Head | The live publication used by runs that do not specify a version. |
| Run | One execution pinned to the publication admitted when it started. |
| Semantic event | A recorded business event in the run history; diagnostic traces do not replace it. |
Environments and credentials
A key belongs to one organization environment. Sandbox and production have separate agents, secrets, numbers and tests. A viewer reads; a member authors and runs; an admin also manages access and configuration. Cumulus staff own platform admission and concurrent capacity.
Testing and live effects
Simulation suites evaluate a published version without dialing. Browser voice tests let a person talk to an agent. test: true on a run excludes it from billing, webhooks and triggers; it does not make a phone call simulated.
Concurrency and retries
expected_revision prevents lost draft edits. expected_head_version prevents an unintended promotion over a changed head. An idempotency key identifies one logical command: reuse it after an unknown outcome.
Next: Agent lifecycle, Run lifecycle, and Build and test recipes.