Create agent

Persists a reusable voice persona — `systemPrompt`, optional `voice`, routing `intent`, and optional `llmOptions` — keyed by `name` within the authenticated organization. Pass the returned `id` as `agentId` on `POST /v1/sessions` to seed a session from this agent.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-readable display name. Does not need to be unique — agents are identified by id.

Length1 <= length <= 120

systemPrompt*string

Initial agent instructions used as the session-level systemPrompt default.

Length1 <= length

voice?string

Default TTS voice id. Omit to let the router pick per provider.

intent*

Routing defaults stored on an agent row. Hydrated into a session's RoutingIntent when the session is created with agentId and no inline intent. Note: agents accept a smaller optimizeFor enum than the per-session RoutingIntent.

llmOptions?

Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.

stackPreferences?

Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.

turnHandling?

Per-agent turn-taking posture, stored on the agent and forwarded to every call it runs. A per-call turnHandling on POST /v1/sessions or POST /v1/sessions/phone REPLACES this object wholesale — the two are not merged per field.

audioOutput?

Static gain in dB on the agent's own speech, applied before the audio reaches the call (and so before a phone leg), whichever TTS provider spoke. Negative is quieter: -6 roughly halves the amplitude, for voices mastered hotter than telephone speech. Boost saturates at full scale, so it clips a voice that already peaks near 0 dBFS. 0 is a passthrough. Background audio is not affected.

backgroundAudio?

endCall?

firstMessage?string

Lengthlength <= 2000

idleRePrompts?

inboundFirstMessage?string

Lengthlength <= 2000

languageRouting?

outboundFirstMessage?string

Lengthlength <= 2000

promptVariables?array<>

Itemsitems <= 100

runMode?string

Value in"cascade" | "s2s"

graphClassifier?string

Which judge answers llm edge conditions in graph mode. llm (the default) runs a temperature-0 one-shot on this agent's own cascade model. jev routes the decision through TypeSafe's System One as a choice over the candidate edges, returning a calibrated confidence per branch. Ignored by agents with no graph. gpt-live walks the graph on the agent's own GPT-Live speech-to-speech session; a call that runs on the cascade judges with llm. Any failure of the jev judge falls back to the llm path rather than failing the call.

Default"llm"

Value in"llm" | "jev" | "gpt-live"

runtime?string

Managed-agent runtime. It is chosen for the whole organization, not per agent: omit it, or send the organization's current runtime — any other value is refused with 409 RUNTIME_CONTROLLED_BY_ORGANIZATION. The pipecat runtime runs runMode: cascade only.

Value in"livekit" | "pipecat"

speechNormalization?

sttMissRecovery?

sttOptions?

ttsOptions?

voiceInstructions?string

Lengthlength <= 2000

webhooks?

timezone?string

Length1 <= length <= 64

extractionFields?array<>

Itemsitems <= 30

Response Body

`application/json`

{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 1,
    "model": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ],
      "s2s": [
        "openai:gpt-realtime-2.1"
      ]
    }
  },
  "turnHandling": {
    "profile": "conversational",
    "endpointing": {
      "minDelay": 0,
      "maxDelay": 0
    },
    "interruption": {
      "mode": "adaptive",
      "minDuration": 0,
      "minWords": 0
    },
    "turnDetection": true,
    "contextThreshold": true,
    "dtmfToolDescription": "string",
    "amdPrompt": "string",
    "waitForCallee": true,
    "onMachine": "hangup",
    "voicemailMessage": "string"
  }
}

{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`