---
title: "Create an agent profile"
method: POST
path: "/v1/agents"
tags: ["Agents"]
---

# Create an agent profile

`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`

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.

## Request body

- AgentConfig: Writable agent fields. On update, present fields are set, `null` clears, absent fields are untouched.
  - `name` string: Display name. Required on create.
  - `persona_system_prompt` string, 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.
  - `greeting` string, 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_variants` string[], 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_id` string, 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_instruct` string, 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_model` string, nullable: Per-agent model selection. Omit for the platform default.
  - `barge_sensitivity` string, nullable: Deprecated compatibility field. Stored values are not applied to Omni runtime.
  - `ack_mode` string, 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_enabled` boolean, nullable: Enable stereo call recordings. Default false.
  - `consent_line` string, 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.
  - `metadata` object, nullable: Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars).
  - `vocabulary` string[], 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.
  - `keyterms` string[], nullable: Deprecated stored compatibility field. It does not affect speech recognition. Use `vocabulary`.
  - `goals` string[], nullable: Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries).
  - `extraction_schema` object, 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_url` string, 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.
  - `tools` AgentToolBinding[], nullable: Tool bindings for this agent profile (references tools from `GET /v1/tools`). Omni `configure.tools[]` may list hosted catalog names or client-loop schemas; server webhooks must be registered here. An inline configure `endpoint` is not supported.
    - `tool_id` string, required
    - `enabled` boolean
    - `config` object: Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value.
    - `name` string: Present on agent reads when the tool resolves.
    - `description` string
    - `input_schema` object: Per-call model argument schema. Present on agent reads when the tool resolves.
    - `execution` 'hosted' | 'server' | 'engine' | 'client': Resolved execution mode. Present on agent reads when the tool resolves.
  - `continuity` boolean, 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 `201`

Created agent

- Agent
  - `object` string
  - `agent_id` string
  - `name` string
  - `persona_system_prompt` string, nullable
  - `greeting` string, nullable
  - `greeting_variants` string[]
  - `voice_id` string, nullable
  - `voice_instruct` string: Effective TTS delivery direction for instruct-capable voice tiers. Renders PyAI's natural conversational pace when no override is stored.
  - `brain_model` string
  - `barge_sensitivity` string, nullable
  - `ack_mode` string, 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.
  - `role` string, nullable: Role archetype the agent runs as, or null. Writable on create and update.
  - `continuity` boolean: Whether this agent reuses a prior-call caller card when a caller key is available. Default false.
  - `recordings_enabled` boolean
  - `consent_line` string, 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.
  - `vocabulary` string[]: Sanitized Agent vocabulary. An empty list means speech-recognition biasing is off.
  - `keyterms` string[]
  - `goals` string[]
  - `metadata` object
  - `extraction_schema` object, nullable: Post-call extraction JSON Schema, or null.
  - `extraction_webhook_url` string, nullable: Signed delivery target for post-call extraction, or null.
  - `tools` AgentToolBinding[]
    - `tool_id` string, required
    - `enabled` boolean
    - `config` object: Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value.
    - `name` string: Present on agent reads when the tool resolves.
    - `description` string
    - `input_schema` object: Per-call model argument schema. Present on agent reads when the tool resolves.
    - `execution` 'hosted' | 'server' | 'engine' | 'client': Resolved execution mode. Present on agent reads when the tool resolves.
  - `created_at` integer: Unix seconds.

## Other responses

- `400`: Invalid field
- `401`: Missing or invalid API key (`code: unauthorized`)
- `403`: Key lacks the required scope or the origin is not allow-listed (`code: forbidden | origin_not_allowed`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)