Voice Agents

Create and manage reusable voice agent configurations for LiveKit + Gemini Live sessions.

A voice agent defines the persona, instructions, questions, and behaviors that drive a real-time voice session. You create an agent once and reuse it across many sessions. The backend compiles a system_instruction from your configuration when you create or update an agent.

Endpoints

Method	Path	Description
POST	/api/v1/voice/agents	Create a voice agent
GET	/api/v1/voice/agents	List agents
GET	/api/v1/voice/agents/:id	Get a specific agent
PATCH	/api/v1/voice/agents/:id	Update an agent
DELETE	/api/v1/voice/agents/:id	Soft-delete an agent

Authentication

Authorization: Bearer <your_api_key>

---

Create an agent

POST /api/v1/voice/agents

Creates a voice agent row and compiles the system_instruction from your configuration.

Request parameters

name · string · required

Display name for the agent. Maximum 200 characters.

instructions · string · required

The core system prompt for the agent — who it is, what it does, and how it should behave during a call. Minimum 1 character, maximum 16,000 characters.

language · string

BCP 47 language tag for the agent’s primary language (e.g. "en-US", "fr-FR"). Defaults to "en-US". Minimum 2 characters, maximum 32 characters.

purpose · string

Short description of the agent’s purpose (e.g. "Qualify inbound sales leads"). Maximum 200 characters.

questions · array

Structured questions the agent should ask during the session. Maximum 64 questions. Each question has the following fields:

Show Question fields

questions[].key · string · required

Identifier for this question in the extracted results. Must start with a letter and use only alphanumeric characters and underscores. Maximum 64 characters.

questions[].ask · string · required

The question text or instruction for the agent. Maximum 2,000 characters.

questions[].type · string · required

Expected answer type. One of: "text", "number", "boolean", "date", "enum".

questions[].options · string[]

Allowed answer values. Required when type is "enum". Maximum 64 options.

questions[].min · number

Minimum value. Applicable when type is "number".

questions[].max · number

Maximum value. Applicable when type is "number". Must be >= min.

behaviors · object

Fine-grained behavioral controls for the agent’s conversation style and session management.

Show Behavior fields

behaviors.greeting · string

Opening message the agent delivers at the start of the call. Maximum 2,000 characters.

behaviors.tone · string

Conversational tone. One of: "professional", "friendly", "neutral", "empathetic".

behaviors.max_duration_seconds · number

Default maximum call length in seconds for sessions using this agent. Range: 60–1800. Can be overridden per session via POST /api/v1/voice/sessions.

behaviors.allow_interruptions · boolean

Whether the agent allows the user to interrupt while it is speaking.

behaviors.end_conversation_after_questions · boolean

Whether the agent should end the call automatically after all questions are answered.

behaviors.speaking_pace · string

Delivery pace. One of: "slow", "normal", "fast".

behaviors.response_length · string

Preferred response verbosity. One of: "brief", "moderate", "detailed".

behaviors.escalation_phrase · string

Trigger phrase that causes the agent to escalate the conversation. Maximum 2,000 characters.

behaviors.follow_up_enabled · boolean

Whether the agent proactively asks follow-up questions.

behaviors.silence_timeout_seconds · number

Seconds of silence before the agent prompts the user. Range: 5–60.

behaviors.closing_message · string

Message the agent delivers before ending the session. Maximum 4,000 characters.

behaviors.require_all_questions · boolean

Whether the agent must collect answers to all questions before completing the session.

output_schema · object

Key-to-type-hint map for the fields the agent should extract from the conversation. Keys must start with a letter and use only alphanumeric characters and underscores (max 64 characters). Values are type hints: "text", "number", "boolean", "date", or "enum:opt1,opt2" (max 200 characters). Maximum 64 keys.

output_schema_strict · object

JSON Schema object (Gemini-supported subset) for constrained post-session extraction. When set, extraction uses constrained decoding and validates the result against this schema. Serialized size must be at most 48,000 characters.

extraction_model · string

Gemini model ID to use for the non-live post-session extraction call. Defaults to your orchestrator environment setting. Maximum 128 characters.

voice · object

Voice configuration for Gemini Live. Both subfields are optional.

Show Voice fields

voice.name · string

Name of a Gemini Live Chirp 3 HD prebuilt voice. Must be a value from GET /api/v1/voice/voices. Maximum 64 characters.

voice.language_code · string

BCP 47 language tag for speech output (e.g. "en-US", "fr-FR"). Must match the pattern ^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,3}$.

metadata · object

String map for your own tracking data. Maximum 32 keys; each value up to 500 characters.

Example request

curl

curl -X POST "https://api.trypi.ai/api/v1/voice/agents" \
  -H "Authorization: Bearer pi_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Qualifier",
    "language": "en-US",
    "purpose": "Qualify inbound sales leads",
    "instructions": "You are a friendly sales assistant. Your goal is to understand the prospect'\''s needs and budget before connecting them to the sales team.",
    "questions": [
      {
        "key": "company_size",
        "ask": "How many employees does your company have?",
        "type": "enum",
        "options": ["1-10", "11-50", "51-200", "201-1000", "1000+"]
      },
      {
        "key": "budget_usd",
        "ask": "What is your approximate monthly budget in USD?",
        "type": "number",
        "min": 0
      }
    ],
    "behaviors": {
      "tone": "friendly",
      "max_duration_seconds": 600,
      "speaking_pace": "normal",
      "require_all_questions": true,
      "closing_message": "Great, I'\''ll connect you with our team shortly."
    },
    "output_schema": {
      "company_size": "enum:1-10,11-50,51-200,201-1000,1000+",
      "budget_usd": "number",
      "main_pain_point": "text"
    },
    "voice": {
      "name": "Aoede",
      "language_code": "en-US"
    }
  }'

Response (200)

data.agent_id · string

UUID of the newly created agent.

data.name · string

Name of the agent.

data.created_at · number

Unix timestamp of when the agent was created.

---

List agents

GET /api/v1/voice/agents

Returns a paginated list of voice agents for your organization.

Query parameters

limit · number

Number of results to return. Range: 1–100. Default: 20.

offset · number

Pagination offset. Default: 0.

Example request

curl

curl -X GET "https://api.trypi.ai/api/v1/voice/agents?limit=20&offset=0" \
  -H "Authorization: Bearer pi_live_***"

Response fields (each agent)

agent_id · string

UUID of the agent.

name · string

Display name.

language · string

Primary language code.

purpose · string

Short purpose description.

is_active · boolean

false when the agent has been soft-deleted.

created_at · number

Unix timestamp of creation.

updated_at · number

Unix timestamp of the last update.

---

Get an agent

GET /api/v1/voice/agents/:id

Returns the full agent configuration, including output_schema_strict and extraction_model when set.

Path parameters

id · string · required

UUID of the voice agent.

---

Update an agent

PATCH /api/v1/voice/agents/:id

Partially updates the agent. Only the fields you provide are changed. The backend rebuilds system_instruction after every update.

Path parameters

id · string · required

UUID of the voice agent to update.

All fields from the create request are accepted and optional. Additionally:

is_active · boolean

Set to false to soft-delete the agent. Prefer DELETE /api/v1/voice/agents/:id for explicit soft-deletion.

output_schema_strict · object | null

Pass null to remove a previously set strict schema.

extraction_model · string | null

Pass null to reset to the environment default.

---

Delete an agent

DELETE /api/v1/voice/agents/:id

Soft-deletes the agent by setting is_active to false. The agent record is retained; existing sessions referencing it are not affected.

Path parameters

id · string · required

UUID of the voice agent to delete.

Response

data.deleted · boolean

Always true when the operation succeeds.