Agents

An agent is the core unit of LYRE. It defines who the AI is, how it sounds, what models it uses, which tools it can call, and how it complies with Australian regulations.

Agent overview

Every agent has four layers of configuration:

•Identity — name, first message, system prompt
•Voice stack — STT, LLM, and TTS provider + model selection
•Tools — external functions the agent can call mid-conversation
•Compliance — AI disclosure, recording consent, DNCR

Full agent JSON schema

The complete schema accepted by POST /v1/agents and PATCH /v1/agents/:id.

Agent schema (JSON)

{
  "name": "string — required, display name",
  "first_message": "string — optional, greeting spoken at call start",
  "system_prompt": "string — required, personality and instructions",

  "stt": {
    "provider": "deepgram | groq | scx | google | azure | speechmatics | assemblyai",
    "model": "string — e.g. nova-2, whisper-large-v3",
    "language": "string — BCP-47, e.g. en-AU (default: en-AU)",
    "keywords": ["string — optional boost words"],
    "endpointing_ms": "number — silence threshold, default 300"
  },

  "llm": {
    "provider": "groq | scx | gemini | mistral | together | fireworks | cerebras",
    "model": "string — e.g. llama-3.3-70b-versatile",
    "temperature": "number — 0.0-2.0, default 0.7",
    "max_tokens": "number — default 1024",
    "fallback": {
      "provider": "string — optional failover provider",
      "model": "string — optional failover model"
    }
  },

  "tts": {
    "provider": "elevenlabs | cartesia | google | azure | deepgram",
    "model": "string — e.g. eleven_flash_v2_5",
    "voice_id": "string — provider-specific voice identifier",
    "speed": "number — 0.5-2.0, default 1.0",
    "stability": "number — 0.0-1.0 (ElevenLabs only)",
    "similarity_boost": "number — 0.0-1.0 (ElevenLabs only)"
  },

  "tools": [
    {
      "type": "function",
      "function": {
        "name": "string — unique tool name",
        "description": "string — when to use this tool",
        "parameters": { "...JSON Schema..." },
        "url": "string — webhook URL to call",
        "method": "GET | POST",
        "headers": { "string": "string" },
        "timeout_ms": "number — default 10000"
      }
    }
  ],

  "compliance": {
    "ai_disclosure": "boolean — play AI disclosure at start (default true)",
    "ai_disclosure_message": "string — custom disclosure text",
    "recording_consent": "all_party | single_party | none",
    "recording_consent_message": "string — custom consent prompt",
    "dncr_check": "boolean — check DNCR before outbound calls (default true)",
    "calling_hours": {
      "timezone": "string — IANA timezone, default Australia/Sydney",
      "weekday_start": "string — HH:MM, default 09:00",
      "weekday_end": "string — HH:MM, default 20:00",
      "saturday_start": "string — HH:MM, default 09:00",
      "saturday_end": "string — HH:MM, default 17:00",
      "sunday": "boolean — default false (no Sunday calls)"
    }
  },

  "metadata": { "string": "string — arbitrary key-value pairs" }
}

System prompt

The system prompt defines the agent's personality, knowledge, and behavioral constraints. It is sent as the system message to the LLM on every turn.

Example system prompt

You are Ava, a friendly and professional customer service agent for
Acme Solar. You speak Australian English. Your role is to:

1. Answer questions about solar panel installations
2. Schedule consultations with the sales team
3. Provide quotes based on roof size and location

Rules:
- Never discuss competitor products
- Always confirm the customer's suburb before quoting
- If you don't know something, say so and offer to transfer to a human
- Keep responses concise (under 3 sentences when possible)

First message

The first_message is spoken by the agent immediately when a call connects, before the user says anything. If omitted, the agent waits for the user to speak first.

"first_message": "G'day! This is Ava from Acme Solar. How can I help you today?"

Voice settings (STT / LLM / TTS)

STT (Speech-to-Text)

Controls how spoken audio is transcribed. The endpointing_ms setting determines how long a silence must last before the system considers the user finished speaking. Lower values make the agent more responsive but risk cutting off the user.

"stt": {
  "provider": "deepgram",
  "model": "nova-2",
  "language": "en-AU",
  "keywords": ["Acme", "kilowatt"],
  "endpointing_ms": 250
}

LLM (Language Model)

The brain of the agent. LYRE supports multiple LLM providers, each with different speed/quality trade-offs. Set a fallback to automatically switch providers if the primary is unavailable.

"llm": {
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "temperature": 0.6,
  "max_tokens": 512,
  "fallback": {
    "provider": "gemini",
    "model": "gemini-2.0-flash"
  }
}

TTS (Text-to-Speech)

Converts the LLM response into speech. Voice selection is provider-specific; use the provider's voice library to find the right voice_id.

"tts": {
  "provider": "elevenlabs",
  "model": "eleven_flash_v2_5",
  "voice_id": "pFZP5JQG7iQjIQuC4Bku",
  "speed": 1.05,
  "stability": 0.7,
  "similarity_boost": 0.8
}

Tool calling

Agents can call external functions during a conversation. When the LLM decides a tool is needed, LYRE pauses speech, calls your webhook, and feeds the result back into the conversation.

Example tool definition

"tools": [
  {
    "type": "function",
    "function": {
      "name": "check_availability",
      "description": "Check available appointment slots for a given date and suburb",
      "parameters": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "suburb": { "type": "string" }
        },
        "required": ["date", "suburb"]
      },
      "url": "https://api.acme.com/availability",
      "method": "POST",
      "headers": { "X-Api-Key": "acme_key_..." },
      "timeout_ms": 5000
    }
  }
]

LYRE sends a POST to your URL with the tool arguments as the JSON body. Your endpoint must return JSON within the timeout. If the call fails, the agent tells the user it could not complete the action.

Compliance settings

Australian law requires specific disclosures and consent for automated calls. LYRE enforces these at the platform level. See the compliance guide for full details.

Field	Default	Description
ai_disclosure	true	Announce that the caller is speaking to an AI
recording_consent	all_party	Request consent before recording (all_party is safest)
dncr_check	true	Wash numbers against the Do Not Call Register for outbound
calling_hours	ACMA defaults	Restrict outbound calls to permitted hours

API operations

Method	Endpoint	Description
POST	/v1/agents	Create a new agent
GET	/v1/agents	List all agents
GET	/v1/agents/:id	Get agent by ID
PATCH	/v1/agents/:id	Update agent (partial)
DELETE	/v1/agents/:id	Delete agent

Next: Providers →