CumulusDocs
Open Studio
On this page

Agents

An agent defines how a conversation or task proceeds: what to ask, which business system to call and what to do with the result. For example, a service agent can check the caller, reserve a technician visit or transfer to dispatch.

Edit the agent’s draft, validate it and publish a version. Runs use that published version, so editing a draft does not change an active call.

Author the same graph as code with SDK 0.3.4, or use Studio. Your customer-hosted tools stay in your application; the SDK publishes their contracts, not function bodies.

Create an agent

Choose a template for the channel you need. You can also clone an existing agent or import a Retell conversation flow. Each create, clone or import request requires an Idempotency-Key.

TemplateChannelStarts as
blankcloud or phoneOne conversation node with an empty prompt.
cloud_taskcloudA task: takes the run input, works through it, ends. Task mode.
cloud_chatcloudA conversation over messages you send to the run. Chat mode.
phone_outboundphoneAn outbound call: greet, say who it is calling for, ask how to help. Records both channels.

POST /api/v1/agents takes name, template, channels and languages (en, es). A template must match a channel you choose. POST /api/v1/agents/{agent_id}/clone copies an agent's head, a version you name, or its draft if it was never published, into a new agent's first draft.

OperationMCP toolKey rolePurpose
GET /api/v1/agentsagents_listviewerList agents with their live version, open draft and most recent run. Use the query fields to search, filter and sort.
GET /api/v1/agents/{agent_id}agents_getviewerRead an agent’s settings, live version and draft status.
POST /api/v1/agentsagents_creatememberCreate an agent from a template. The response includes its first draft; publish a version before running it.
DELETE /api/v1/agents/{agent_id}agents_deletememberArchive an agent to prevent new drafts, publications and runs. Its existing history is retained.
POST /api/v1/agents/{agent_id}/cloneagents_clonememberCopy an agent’s live version, a selected publication or its never-published draft into a new agent’s first draft.
POST /api/v1/agents/importagents_importmemberImport a Retell conversation-flow export into a draft. Review diagnostics and test the imported behavior before publishing.
POST /api/v1/agents/import/inspectagents_import_inspectmemberPreview a Retell import without writing changes. The response reports diagnostics, the target agent and any draft changes the import would replace.

The flow graph

A flow starts at one node and follows transitions between nodes. A global prompt defines instructions for the whole flow; each node supplies the instructions for its own step.

In the service example, the agent asks what Alex needs, extracts the answer and routes to booking, dispatch or follow-up. Transitions can use a model-evaluated instruction, an equation on variables (==, contains, is_set, …) or an unconditional path.

Node kindUse it to
conversationAsk a question or say fixed text.
extract_dynamic_variablesSave typed values from the conversation.
branchChoose a path based on conditions.
functionCall an HTTP action; phone publication requires waiting for its result.
transfer_callRequest a supported phone transfer to a predefined number or explicit variable binding; inferred destinations are refused.
componentRun a reusable sub-flow, such as checking availability and confirming a visit.
endEnd the call or conversation.

Use {{variables}} in prompts to insert run data. A phone run is refused if required variables are missing; see Dynamic variables. Moving nodes on the Studio canvas changes their layout, not the published behavior or digest.

Drafts: edit and validate

For example, a service agent can follow greeting → account lookup → explain result → end. Each arrow is a transition; a failed lookup needs its own route, such as lookup → apologize → end. Choose the next node from the returned account facts rather than asking the model to invent them.

An agent has one editable draft. Open it with POST /api/v1/agents/{agent_id}/draft, based on the live version or a chosen base_version.

Send changes to PATCH …/draft with its draft_id and expected_revision. Each request accepts up to 100 typed edits. If another editor has changed the draft, the API returns 409 conflict; read the current draft before applying your changes again.

Edit a draft

Example
PATCH /api/v1/agents/{agent_id}/draft
{
  "draft_id": "5b0e…",
  "expected_revision": 4,
  "edits": [
    { "type": "flow.prompt", "text": "You are calling on behalf of Acme Equipment Care about service at {{site_name}}." },
    { "type": "languages.set", "languages": ["en", "es"] },
    { "type": "agent.telephony", "value": { "trunkId": "my-twilio-trunk", "from": "+14155550100" } }
  ]
}

Use Edit a draft for the complete edit schemas. Common changes are:

ChangeEdit types
Instructions and routingflow.prompt, node.instruction, node.transitions, node.configure
Nodes and reusable flowsnode.create, node.remove, component.create, component.start
Models, voice and channel settingsagent.provider, agent.settings, agent.telephony, agent.recording, channels.set, languages.set
Business integrationsaction.put, notification.put, trigger.put, knowledge.set, phone.inbound_context
Structured task input and outputcloud.io.set
Post-run fieldsagent.analysis

Validate before publishing with POST …/draft/validate. The response contains ok, the proposed version and digest, and warning or error diagnostics. Errors block publication.

When a diagnostic includes fixes, submit the chosen fix’s edits against the revision you validated, then validate again. If the draft changed meanwhile, the fix is refused with 409 conflict.

OperationMCP toolKey rolePurpose
GET /api/v1/agents/{agent_id}/draftdrafts_getviewerRead the agent’s open draft and current revision. Use that revision when editing or validating it.
POST /api/v1/agents/{agent_id}/draftdrafts_openmemberOpen a working draft from the live publication or a selected version.
PATCH /api/v1/agents/{agent_id}/draftdrafts_editmemberApply typed edits to a draft in order. Send the revision you last read to prevent overwriting another editor’s changes.
DELETE /api/v1/agents/{agent_id}/draftdrafts_discardmemberRemove the open draft. Send its current revision; published versions are unaffected.
POST /api/v1/agents/{agent_id}/draft/rebasedrafts_rebasememberUpdate the draft’s base after the live version changes, keeping the draft’s definition. A further live-version change returns head_moved.
POST /api/v1/agents/{agent_id}/draft/validatedrafts_validatememberCompile a draft and read its diagnostics, next version number and digest. Resolve error diagnostics before publishing.

Publish and roll back

POST …/publications with the draft_id, expected_revision and the next version (0 for the first) compiles the draft into an immutable publication. By default it becomes the head: the version selected when a new run omits version. Options:

  • "live": false publishes a test version: you can run it by version, but the head does not move and its triggers are not registered. Current Go admission requires test: true to run that publication. Repeating the same test publication request can return its existing version; retain the actual response.
  • "keep_draft": true keeps the draft open for more changes.

Validate, publish a candidate with "live": false and test supported paths against that version. For ordinary non-test execution, publish the reviewed graph through the revision-checked live: true workflow. Read the publication's test flag before routing a number or starting a non-test run.

POST …/head moves the head to any existing version: promote a test version, or roll back. It takes expected_head_version, the head you saw (null for none), and refuses the move with 409 conflict if the head has moved since. Runs already admitted keep the version they started with. Promotion selects the head; a test publication still requires test: true. Publish with live: true before using that behavior for regular runs.

Promotion applies within the current environment; sandbox and production have separate agents and resource references. Incoming phone numbers pin their assigned publication: after promotion or rollback, an admin must reassign the number and verify inbound_agent_version before expecting incoming calls to use the changed head.

OperationMCP toolKey rolePurpose
POST /api/v1/agents/{agent_id}/publicationspublications_publishmemberCompile a draft into an immutable version. Set live: false to create a test version; the default makes it live for new runs.
GET /api/v1/agents/{agent_id}/publicationspublications_listviewerList the agent’s published versions.
GET /api/v1/agents/{agent_id}/publications/{version}publications_getviewerRead a publication and its compiled plan to inspect the behavior a run executes.
POST /api/v1/agents/{agent_id}/headpublications_promotememberMake an existing version live or roll back to an earlier one. Send the live version you last read; a named open draft is rebased in the same transaction.

Actions and receipts

An agent uses actions to work with your systems and manage the call: reserve a visit through an HTTP endpoint, transfer to dispatch, search documents or send a webhook.

An action request creates an effect: a record of that particular attempted operation. Before sending it, Cumulus checks whether the run is still authorized. The receipt tracks intended → sending → succeeded | failed | uncertain. A denied action sends nothing. uncertain means the system cannot confirm the outcome; it is not automatically resent. Read the receipts with GET /api/v1/runs/{run_id}/effects.

Built-in actionWhat it does
webhook.deliverDeliver run webhook
http.requestCustomer HTTP action
call.transferTransfer call
run.endEnd call or conversation
call.voicemailHandle voicemail
knowledge.searchSearch knowledge
call.dialDial outbound call
run.analyzeExtract configured transcript-backed analysis fields

Use an HTTP action when the agent needs your application to do work, such as read an account or reserve an appointment. Your endpoint returns the facts that the next node needs. Transfer and end nodes handle their own platform operations.

Your own HTTP actions (action.put) call HTTPS endpoints with none, bearer, basic or header authentication, the credential held as a secret. Use response_variables to map fields from the action’s 2xx JSON response into flow variables. For example, an endpoint returns {"booking":{"reference":"BOOK-DEMO-7"}}. The mapping {"booking_reference":"$.booking.reference"} copies that field into booking_reference, so the next node can say “Your reference is {{booking_reference}}.” An error route should explain that the booking could not be confirmed.

The native POST envelope includes args and call, with distinct call.call_id (conversation) and call.run_id identities. Customer endpoints authenticate, validate and durably deduplicate Idempotency-Key. See customer HTTP adapters for the complete envelope and explicit compatibility policies.

Mappings require every declared output by default. For a lookup with conditional fields, set response_variable_policy: "replace_available". Each successful response replaces the mapped variable set with its present scalar values and clears omitted or null fields. This prevents a retry from retaining another account's values. Objects and arrays still fail mapping; use a path to a scalar field. Set the policy to "required" to restore strict mapping. Omitting it preserves the current policy.

Set speak_after_execution: false on action.put to continue routing after the result without an extra generated reply, or true to enable that reply. Omitting the field preserves the current setting. It applies to the action’s root and component tools; Studio exposes it as Speak after result. Response-variable mappings remain unchanged unless supplied.

OperationMCP toolKey rolePurpose
GET /api/v1/actionsactions_listviewerList the actions an agent can be configured to use. An action must be supported and configured for your workspace before the agent can execute it; validate the draft after adding it.
GET /api/v1/voicesvoices_listviewerList available speech models and text-to-speech voices for agent configuration.
POST /api/v1/voices/previewvoices_previewmemberPreview a fixed English or Spanish line with configured voice, model, speed and expressiveness; does not run an agent

Test before going live

Use Test an agent for simulated caller suites, verdicts and browser voice sessions. Follow the publish-and-test recipe before promotion.

Try it in the browser

Talk to a phone agent in Studio before placing a carrier call. POST /api/v1/test-sessions starts a browser voice test of a chosen version, admits a web run marked as a test and returns a short-lived room token. Reusing the same Idempotency-Key rejoins an active test with a fresh token.

Browser sessions do not dial or transfer over the carrier, but customer HTTP actions use the publication's configured endpoints and credentials. Use an isolated agent with sandbox endpoints; testing methods explains which effects each test can perform.

OperationMCP toolKey rolePurpose
POST /api/v1/test-sessionstest_sessions_creatememberStart a browser voice test of a published phone agent. The response includes a web run and a short-lived room token; replaying the key rejoins the live test with a fresh token.

Import from Retell

Import a Retell conversation-flow export with POST /api/v1/agents/import. It creates or replaces a draft and leaves the live version unchanged. Single-prompt Retell LLM agents are not accepted.

First call POST /api/v1/agents/import/inspect with the same body. It writes nothing and reports diagnostics, the target agent and any draft changes the import would replace.

Split the export into flow (its conversationFlow) and agent (the remaining object). Set agent_version to the Retell version for provenance. A new reference.id creates an agent; an existing ID targets that agent’s draft. If the draft has unpublished changes, include replace_draft with its draft_id and expected_revision.

Resolve the diagnostics, import, then validate and publish a test version.

POST /api/v1/agents/import

Example
{
  "reference": { "tenant_id": "<your environment's tenant_id>", "kind": "agent", "id": "support-agent" },
  "agent_version": 6,
  "agent": { …the Retell agent object without conversationFlow, "version": 6, "webhook_url": null… },
  "flow": { …the export's conversationFlow: conversation_flow_id, version, nodes, tools… },
  "config": {
    "providers": {
      "llm": { "provider": "openai", "model": { "model_id": "gpt-5.4-mini", "provider": "openai", "tier": "cumulus-served" } },
      "stt": { "provider": "elevenlabs", "model": "scribe_v2_realtime" },
      "tts": { "provider": "elevenlabs", "model": "eleven_flash_v2_5", "voiceId": "<a voice_id from GET /api/v1/voices>" }
    },
    "recording": { "required": true, "channels": "dual" }
  },
  "model_bindings": {
    "$.flow.model_choice": { "model": { "model_id": "gpt-5.4-mini", "provider": "openai", "tier": "cumulus-served" } },
    "$.agent.post_call_analysis_model": { "model": { "model_id": "gpt-5.4-mini", "provider": "openai", "tier": "cumulus-served" } }
  }
}
  • reference.tenant_id is your environment's: GET /api/v1/environments lists production and sandbox with their tenant_id and which one your key is in (current).
  • config.providers chooses the models the agent runs on: a ready chat model from GET /api/v1/models for llm (using the model identity and provider returned by the selected environment), and a speech model and voice from GET /api/v1/voices. The Retell voice is replaced by that voice (warning voice_rebound).
  • model_bindings maps each model the export declares to a catalog model. Run inspect with an empty object first: every model_binding_required diagnostic names one path to bind (usually $.flow.model_choice and $.agent.post_call_analysis_model).
  • Set agent.webhook_url to null, or pin the same URL as config.webhook ({ url, secretRef: "<secret id>@<version>" }, a webhook_signing secret); a different URL is refused with webhook_mismatch.
  • config.telephony ({ trunkId, from }) is optional. Leave it out until your trunk and numbers exist, then add them with the agent.telephony edit (Phone).
  • Retell tools become HTTP actions. Inline secrets in tool headers or query values, and custom SIP headers, are refused (private_inline_value): move them to a secret.
  • Locales other than English and Spanish are dropped with a warning.
  • Replacing a draft with unpublished changes needs replace_draft with that draft's draft_id and revision (expected_revision); without it the import is refused with 409 conflict, reason draft_has_changes, so no client discards work by accident.
  • Importing the same body onto its unedited draft again returns that draft (200) and writes nothing.
  • By default, publication blockers refuse the import. To preserve a structurally valid source without dropping unsupported settings, send allow_blocked: true (Studio: Keep as blocked draft). The imported draft stays unpublished; the response's validation reports the blockers. Inline credentials and malformed sources are still refused. Revalidate after editing or before publishing; an unchanged replay may omit validation. This option never bypasses publication or admission checks.
Content version d58335aeCustomer SDKMarkdown source
Agents · Cumulus developer docs