Trillet AI logo

Create Call Agent

Create a new agent for a workspace.

POSThttps://api.trillet.ai/v1/api/agents

An agent holds the voice, speech-to-text and language model a call flow speaks with. Create the agent first, then pass its _id as agent when you create a call flow.

Phone numbers are not attached here. Once the agent belongs to a call flow, attach a number with Assign Phone Number to Agent.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

namestringrequired

Name of the agent being created.

ttsModelobjectrequired

Text-to-Speech (TTS) configuration for the agent. provider and voiceId are both required.

fallbackTtsModelobject

Optional second voice, used if the primary TTS provider fails during a call. Same fields as ttsModel.

sttProviderobject

Speech-to-text provider, as { "id": "...", "name": "...", "description": "..." }. id is one of deepgram-nova-2, deepgram-nova-3, deepgram-nova-3-medical, deepgram-flux, deepgram-flux-multi, speechmatics, speechmatics-medical, whisper, gladia, xai, google-chirp-3, elevenlabs-scribe, assemblyai-universal-pro, gemini-transcribe-live.

fallbackSttProviderobject

Optional speech-to-text provider to fall back to. Same shape as sttProvider.

llmModelstringdefault: platform-llm

Language model the agent uses to generate responses.

Defaults to platform-llm, the managed platform model. It is tuned for voice agents and kept current without any change to your configuration, and it is what agents created in the dashboard start on.

To pin a specific model instead, pass its id, for example gpt-4.1 or gemini-2.5-flash. The models on offer change over time, so call List Available Models for the current set rather than hardcoding one. A model that isn't on offer, or the retired trillet-llm, fails with 400.

fallbackLlmModelstring

Optional model to fall back to if the primary model fails. Checked the same way as llmModel.

smartCallbackbooleandefault: false

Enable smart callback functionality for the agent.

maxAttemptsForSmartCallbacknumberdefault: 5

Maximum number of callback attempts when smart callback is enabled.

gapBetweenEachAttemptForSmartCallbackarray

Array of time intervals between each callback attempt. Each item contains days and hours. Defaults to five gaps of one day. An item outside the ranges below is reset to { "days": 1, "hours": 0 }.

typestringdefault: voice

voice or chat.

settingsobject

Voice and model tuning. Stored exactly as sent: the API applies no defaults, and if you leave it out it stays unset. The dashboard starts new agents on { "speed": 0, "volume": 1, "temperature": 0.3 }.

phoneNumberIds and variables are ignored on create. Attach numbers with Assign Phone Number to Agent.

Response

200 with the saved agent.

_idstring

Unique identifier for the newly created agent. Pass it as agent when you create a call flow to link the two. The agent then shows up inside that call flow and on the Phone Numbers page. An agent serves one call flow, so create a new agent for each flow.

workspaceIdstring

Workspace ID associated with the agent.

userIdstring

User ID of the agent creator.

namestring

Name of the agent.

ttsModelobject

Text-to-Speech configuration for the agent, as sent (provider, voiceId, name, language, rimeModel, elevenLabsModel and any BYO key fields).

fallbackTtsModelobject | null

Fallback voice, or null.

sttProviderobject | null

Speech-to-text provider, or null.

llmModelstring

Language model used by the agent. platform-llm if you didn't send one.

fallbackLlmModelstring | null

Fallback language model, or null.

smartCallbackboolean

Whether smart callback is enabled for the agent.

maxAttemptsForSmartCallbacknumber

Maximum number of callback attempts.

gapBetweenEachAttemptForSmartCallbackarray

Array of time intervals between callback attempts.

typestring

voice or chat.

phoneNumberIdsarray

Always empty on a new agent.

activeSessionsarray

Array of active sessions for the agent.

settingsobject

Settings as sent, or absent if you didn't send any.

statusstring

ready for a new agent.

createdAtstring

Timestamp when the agent was created.

updatedAtstring

Timestamp when the agent was last updated.

Errors

StatusBodyWhen
400{"error": "Workspace ID is required"}No x-workspace-id
400{"message", "code": "TTS_MODEL_INVALID"}ttsModel is missing, or has no provider or voiceId
400{"message", "code": "LLM_MODEL_INVALID"}llmModel or fallbackLlmModel isn't an available model, or is the retired trillet-llm
500{"error": "..."}Unexpected server error
{
  "name": "Customer Support Agent",
  "ttsModel": {
    "provider": "rime",
    "voiceId": "mistv3_wildflower",
    "name": "Wildflower",
    "rimeModel": "mistv3",
    "language": "en"
  },
  "llmModel": "platform-llm",
  "smartCallback": true,
  "maxAttemptsForSmartCallback": 3,
  "gapBetweenEachAttemptForSmartCallback": [
    { "days": 1, "hours": 2 },
    { "days": 2, "hours": 0 },
    { "days": 3, "hours": 6 }
  ],
  "settings": {
    "speed": 0,
    "volume": 1,
    "temperature": 0.3
  }
}
{
  "_id": "d5d5d5d5d5d5d5d5d5d5d5d5",
  "workspaceId": "d1d1d1d1d1d1d1d1d1d1d1d1",
  "userId": "a0a0a0a0a0a0a0a0a0a0a0a0",
  "name": "Customer Support Agent",
  "ttsModel": {
    "provider": "rime",
    "voiceId": "mistv3_wildflower",
    "name": "Wildflower",
    "language": "en",
    "rimeModel": "mistv3",
    "elevenLabsModel": null,
    "elevenLabsApiKeySecret": null,
    "cartesiaApiKeySecret": null
  },
  "fallbackTtsModel": null,
  "sttProvider": null,
  "llmModel": "platform-llm",
  "fallbackLlmModel": null,
  "smartCallback": true,
  "maxAttemptsForSmartCallback": 3,
  "gapBetweenEachAttemptForSmartCallback": [
    { "days": 1, "hours": 2 },
    { "days": 2, "hours": 0 },
    { "days": 3, "hours": 6 }
  ],
  "type": "voice",
  "settings": { "speed": 0, "volume": 1, "temperature": 0.3 },
  "fallbackSettings": null,
  "status": "ready",
  "phoneNumberIds": [],
  "activeSessions": [],
  "createdAt": "2026-10-29T10:00:00.000Z",
  "updatedAt": "2026-10-29T10:00:00.000Z"
}

Last updated on