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.
| Template | Channel | Starts as |
|---|---|---|
| blank | cloud or phone | One conversation node with an empty prompt. |
| cloud_task | cloud | A task: takes the run input, works through it, ends. Task mode. |
| cloud_chat | cloud | A conversation over messages you send to the run. Chat mode. |
| phone_outbound | phone | An 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.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/agents | agents_list | viewer | List 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_get | viewer | Read an agent’s settings, live version and draft status. |
POST /api/v1/agents | agents_create | member | Create an agent from a template. The response includes its first draft; publish a version before running it. |
DELETE /api/v1/agents/{agent_id} | agents_delete | member | Archive an agent to prevent new drafts, publications and runs. Its existing history is retained. |
POST /api/v1/agents/{agent_id}/clone | agents_clone | member | Copy an agent’s live version, a selected publication or its never-published draft into a new agent’s first draft. |
POST /api/v1/agents/import | agents_import | member | Import a Retell conversation-flow export into a draft. Review diagnostics and test the imported behavior before publishing. |
POST /api/v1/agents/import/inspect | agents_import_inspect | member | Preview 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 kind | Use it to |
|---|---|
conversation | Ask a question or say fixed text. |
extract_dynamic_variables | Save typed values from the conversation. |
branch | Choose a path based on conditions. |
function | Call an HTTP action; phone publication requires waiting for its result. |
transfer_call | Request a supported phone transfer to a predefined number or explicit variable binding; inferred destinations are refused. |
component | Run a reusable sub-flow, such as checking availability and confirming a visit. |
end | End 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
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:
| Change | Edit types |
|---|---|
| Instructions and routing | flow.prompt, node.instruction, node.transitions, node.configure |
| Nodes and reusable flows | node.create, node.remove, component.create, component.start |
| Models, voice and channel settings | agent.provider, agent.settings, agent.telephony, agent.recording, channels.set, languages.set |
| Business integrations | action.put, notification.put, trigger.put, knowledge.set, phone.inbound_context |
| Structured task input and output | cloud.io.set |
| Post-run fields | agent.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.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/agents/{agent_id}/draft | drafts_get | viewer | Read the agent’s open draft and current revision. Use that revision when editing or validating it. |
POST /api/v1/agents/{agent_id}/draft | drafts_open | member | Open a working draft from the live publication or a selected version. |
PATCH /api/v1/agents/{agent_id}/draft | drafts_edit | member | Apply 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}/draft | drafts_discard | member | Remove the open draft. Send its current revision; published versions are unaffected. |
POST /api/v1/agents/{agent_id}/draft/rebase | drafts_rebase | member | Update 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/validate | drafts_validate | member | Compile 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": falsepublishes a test version: you can run it by version, but the head does not move and its triggers are not registered. Current Go admission requirestest: trueto run that publication. Repeating the same test publication request can return its existing version; retain the actual response."keep_draft": truekeeps 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.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
POST /api/v1/agents/{agent_id}/publications | publications_publish | member | Compile 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}/publications | publications_list | viewer | List the agent’s published versions. |
GET /api/v1/agents/{agent_id}/publications/{version} | publications_get | viewer | Read a publication and its compiled plan to inspect the behavior a run executes. |
POST /api/v1/agents/{agent_id}/head | publications_promote | member | Make 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 action | What it does |
|---|---|
| webhook.deliver | Deliver run webhook |
| http.request | Customer HTTP action |
| call.transfer | Transfer call |
| run.end | End call or conversation |
| call.voicemail | Handle voicemail |
| knowledge.search | Search knowledge |
| call.dial | Dial outbound call |
| run.analyze | Extract 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.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/actions | actions_list | viewer | List 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/voices | voices_list | viewer | List available speech models and text-to-speech voices for agent configuration. |
POST /api/v1/voices/preview | voices_preview | member | Preview 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.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
POST /api/v1/test-sessions | test_sessions_create | member | Start 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
{
"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_idis your environment's:GET /api/v1/environmentslists production and sandbox with theirtenant_idand which one your key is in (current).config.providerschooses the models the agent runs on: areadychat model fromGET /api/v1/modelsforllm(using the model identity and provider returned by the selected environment), and a speech model and voice fromGET /api/v1/voices. The Retell voice is replaced by that voice (warningvoice_rebound).model_bindingsmaps each model the export declares to a catalog model. Run inspect with an empty object first: everymodel_binding_requireddiagnostic names one path to bind (usually$.flow.model_choiceand$.agent.post_call_analysis_model).- Set
agent.webhook_urltonull, or pin the same URL asconfig.webhook({ url, secretRef: "<secret id>@<version>" }, awebhook_signingsecret); a different URL is refused withwebhook_mismatch. config.telephony({ trunkId, from }) is optional. Leave it out until your trunk and numbers exist, then add them with theagent.telephonyedit (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_draftwith that draft'sdraft_idand revision (expected_revision); without it the import is refused with409 conflict, reasondraft_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'svalidationreports the blockers. Inline credentials and malformed sources are still refused. Revalidate after editing or before publishing; an unchanged replay may omitvalidation. This option never bypasses publication or admission checks.