Agents

Create an agent profile

Create an OPTIONAL agent profile (persona, greeting message, voice, language, recording disclosure, conversation knobs) so you can reference it by id instead of sending a full configure frame each call. Drive it with wss://api.pyai.com/v1/omni?session_label=agent_… (the profile id doubles as the opaque session label); per-call headers (X-PyAI-Voice, X-PyAI-Persona) and the configure frame override profile config. The engine speaks greeting at turn 0 and consent_line before recording when enabled. Requires the omni:session scope.

post/v1/agents

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/agents
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

namestring

Display name. Required on create.

persona_system_promptstring nullable

The agent's entire character, role, policies, and business context.

role'receptionist' | 'support' | 'sales' | 'collections' | 'ea' | 'concierge' | 'custom' | 'null' nullable

Role archetype. Adds PyAI's role operating standard beneath your persona and derives the runtime mode (receptionist, sales, and collections enable their matching deterministic conversation guards; everything else runs the default mode). Your stored persona is unchanged and remains authoritative for identity and business policy. Null clears the role.

greetingstring nullable

Greeting message, opening line spoken at turn 0 when a call connects (before the caller speaks). Stored on the agent profile; played automatically when connecting with session_label={agent_id}. May also be sent inline in the Omni configure frame.

greeting_variantsstring[] nullable

Approved opening-line variants. PyAI selects one for each newly resolved call profile; null or empty falls back to greeting. Recording consent is fixed and never rotated.

voice_idstring nullable

A stock voice_id, one of its permanent aliases from GET /v1/voices, or a cloned voice id. Omni reports the canonical served stock id in configured.voice_id.

voice_instructstring nullable

Stored delivery direction for instruct-capable voice tiers. Current Omni routes support neutral delivery only: omit or set null for neutral speech. A saved custom value is rejected when configuring Omni; an inline empty configure.voice_instruct resets it to neutral for that session.

brain_modelstring nullable

Per-agent model selection. Omit for the platform default.

barge_sensitivitystring nullable

Deprecated compatibility field. Stored values are not applied to Omni runtime.

ack_modestring nullable

Deprecated compatibility field. Stored values are not applied to Omni runtime.

idle_check_in'auto' | 'patient' | 'off' | 'null' nullable

How patient the agent is before checking in on a silent caller ("Sorry, are you still there?"). auto checks in after a few seconds of silence; patient waits far longer, for callers who routinely think, read, or look something up mid-call; off disables the check-in entirely, so the agent stays silent until the caller speaks. When unset, most roles render auto; support agents render patient. Independent of ack_mode. May also be sent inline in the Omni configure frame, which wins for that session.

persona_perspective'agent' | 'caller' | 'null' nullable

Which side of the call the persona is on. agent (default) means the persona is the business being called, so PyAI adds its conversation layer for handling a caller (capability honesty, handoffs, turn discipline). caller means the persona is the individual on the call instead, as in QA and simulation callers, mystery shopping, or training partners; PyAI drops that operator-voice layer so it cannot contradict an inverted persona. May also be sent inline in the Omni configure frame, which wins for that session.

recordings_enabledboolean nullable

Enable stereo call recordings. Default false.

consent_linestring nullable

Recording disclosure spoken before recording starts when recordings_enabled is true. Required for compliance when recordings are on and must contain a meaningful spoken phrase (at least 10 characters and 5 letters). Playback order: consent_line, then greeting, then conversation.

language'en' | 'fr' | 'es' | 'de' | 'hi' | 'zh' | 'it' | 'pt' | 'ja' | 'ko' | 'null' nullable

Requested language for this Agent's Omni sessions. null or absent means en. Availability is staged: public serving includes en, fr, es, hi, it, pt, ja, and ko; de and the legacy zh alias fall back to English unless explicitly enabled with qualified endpoints. Canonical staged route identifiers are exposed in x-staged-language-ids for internal integration only and are rejected by the public control plane until qualified. Inspect the session's configured.language_active and language_fallback fields before assuming the requested language is active. See the Language support reference.

metadataobject nullable

Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars).

vocabularystring[] nullable

Optional custom vocabulary for this Agent's Omni speech recognition. A non-empty list is the opt-in. PyAI keeps at most five effective terms, with at most five words per term. It trims whitespace, deduplicates without regard to case while preserving the first spelling and order, and drops common-only phrases. Set [] or null to turn it off. The list is fixed when a session starts. Organization Hear vocabulary is never applied to Omni.

keytermsstring[] nullable

Deprecated stored compatibility field. It does not affect speech recognition. Use vocabulary.

goalsstring[] nullable

Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries).

extraction_schemaobject nullable

JSON Schema of fields to capture from each completed call's transcript. When set with extraction_webhook_url, PyAI runs a post-call extraction pass and POSTs the structured JSON to your webhook (signed with X-PyAI-Signature). Null disables extraction.

extraction_webhook_urlstring uri nullable

HTTPS URL that receives the signed post-call extraction result (event omni.call.extracted). Requires extraction_schema. The call's agent is resolved from the connect-URL session_label when it equals this agent's id.

continuityboolean nullable

Reuse a tiny caller card on the next call when PyAI can resolve the caller (phone number or a signed customer id). The card is advisory — the agent may recall a name or open thread, and must not refund, book, or transfer from it. Default false.

Response

Created agent

objectstring
agent_idstring
namestring
persona_system_promptstring nullable
greetingstring nullable
greeting_variantsstring[]
voice_idstring nullable
voice_instructstring

Effective TTS delivery direction for instruct-capable voice tiers. Renders PyAI's natural conversational pace when no override is stored.

brain_modelstring
barge_sensitivitystring nullable
ack_modestring nullable
idle_check_in'auto' | 'patient' | 'off'

Idle check-in patience. Renders auto when unset, except support agents render patient.

persona_perspective'agent' | 'caller'

Which side of the call the persona is on. Renders the effective default (agent) when unset.

mode'default' | 'receptionist' | 'sales' | 'collections'

Read-only runtime mode derived from the agent's role (default, receptionist, sales, or collections). Set indirectly via the writable role field.

rolestring nullable

Role archetype the agent runs as, or null. Writable on create and update.

continuityboolean

Whether this agent reuses a prior-call caller card when a caller key is available. Default false.

recordings_enabledboolean
consent_linestring nullable
language'en' | 'fr' | 'es' | 'de' | 'hi' | 'zh' | 'it' | 'pt' | 'ja' | 'ko'

Session language for this agent's calls. Renders the effective default (en) when unset. Canonical staged route identifiers remain excluded from the public enum until qualification.

vocabularystring[]

Sanitized Agent vocabulary. An empty list means speech-recognition biasing is off.

keytermsstring[]
goalsstring[]
metadataobject
extraction_schemaobject nullable

Post-call extraction JSON Schema, or null.

extraction_webhook_urlstring nullable

Signed delivery target for post-call extraction, or null.

created_atinteger

Unix seconds.

Example response

{
  "object": "agent",
  "agent_id": "agent_7f3a0b12",
  "brain_model": "default",
  "mode": "default"
}

Changes

No recorded changes to this operation across all 1 revision of this API.