Skip to main content
POST
/
agents
Create Agent
curl --request POST \
  --url https://voice-livekit.studio.lyzr.ai/v1/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "config": {
    "agent_name": "<string>",
    "agent_description": "<string>",
    "engine": {
      "kind": "<string>",
      "stt": "<string>",
      "llm": "<string>",
      "tts": "<string>",
      "voice_id": "<string>",
      "language": "<string>"
    },
    "engine_pipeline": {},
    "engine_realtime": {},
    "prompt": "<string>",
    "agent_role": "<string>",
    "agent_goal": "<string>",
    "agent_instructions": "<string>",
    "dynamic_variables": {},
    "dynamic_variable_defaults": {},
    "conversation_start": {
      "who": "<string>",
      "greeting": "<string>"
    },
    "turn_detection": "<string>",
    "noise_cancellation": {},
    "api_key": "<string>",
    "knowledge_base": {},
    "managed_agents": {},
    "tools": [
      "<string>"
    ],
    "lyzr_tools": [
      {}
    ],
    "agent_id": "<string>",
    "user_id": "<string>",
    "session_id": "<string>",
    "preemptive_generation": true,
    "pronunciation_correction": true,
    "pronunciation_rules": {},
    "audio_recording_enabled": true,
    "vad_enabled": true,
    "avatar": {},
    "background_audio": {},
    "corrections": [
      {}
    ]
  }
}
'
import requests

url = "https://voice-livekit.studio.lyzr.ai/v1/agents"

payload = { "config": {
        "agent_name": "<string>",
        "agent_description": "<string>",
        "engine": {
            "kind": "<string>",
            "stt": "<string>",
            "llm": "<string>",
            "tts": "<string>",
            "voice_id": "<string>",
            "language": "<string>"
        },
        "engine_pipeline": {},
        "engine_realtime": {},
        "prompt": "<string>",
        "agent_role": "<string>",
        "agent_goal": "<string>",
        "agent_instructions": "<string>",
        "dynamic_variables": {},
        "dynamic_variable_defaults": {},
        "conversation_start": {
            "who": "<string>",
            "greeting": "<string>"
        },
        "turn_detection": "<string>",
        "noise_cancellation": {},
        "api_key": "<string>",
        "knowledge_base": {},
        "managed_agents": {},
        "tools": ["<string>"],
        "lyzr_tools": [{}],
        "agent_id": "<string>",
        "user_id": "<string>",
        "session_id": "<string>",
        "preemptive_generation": True,
        "pronunciation_correction": True,
        "pronunciation_rules": {},
        "audio_recording_enabled": True,
        "vad_enabled": True,
        "avatar": {},
        "background_audio": {},
        "corrections": [{}]
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    config: {
      agent_name: '<string>',
      agent_description: '<string>',
      engine: {
        kind: '<string>',
        stt: '<string>',
        llm: '<string>',
        tts: '<string>',
        voice_id: '<string>',
        language: '<string>'
      },
      engine_pipeline: {},
      engine_realtime: {},
      prompt: '<string>',
      agent_role: '<string>',
      agent_goal: '<string>',
      agent_instructions: '<string>',
      dynamic_variables: {},
      dynamic_variable_defaults: {},
      conversation_start: {who: '<string>', greeting: '<string>'},
      turn_detection: '<string>',
      noise_cancellation: {},
      api_key: '<string>',
      knowledge_base: {},
      managed_agents: {},
      tools: ['<string>'],
      lyzr_tools: [{}],
      agent_id: '<string>',
      user_id: '<string>',
      session_id: '<string>',
      preemptive_generation: true,
      pronunciation_correction: true,
      pronunciation_rules: {},
      audio_recording_enabled: true,
      vad_enabled: true,
      avatar: {},
      background_audio: {},
      corrections: [{}]
    }
  })
};

fetch('https://voice-livekit.studio.lyzr.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://voice-livekit.studio.lyzr.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'config' => [
        'agent_name' => '<string>',
        'agent_description' => '<string>',
        'engine' => [
                'kind' => '<string>',
                'stt' => '<string>',
                'llm' => '<string>',
                'tts' => '<string>',
                'voice_id' => '<string>',
                'language' => '<string>'
        ],
        'engine_pipeline' => [
                
        ],
        'engine_realtime' => [
                
        ],
        'prompt' => '<string>',
        'agent_role' => '<string>',
        'agent_goal' => '<string>',
        'agent_instructions' => '<string>',
        'dynamic_variables' => [
                
        ],
        'dynamic_variable_defaults' => [
                
        ],
        'conversation_start' => [
                'who' => '<string>',
                'greeting' => '<string>'
        ],
        'turn_detection' => '<string>',
        'noise_cancellation' => [
                
        ],
        'api_key' => '<string>',
        'knowledge_base' => [
                
        ],
        'managed_agents' => [
                
        ],
        'tools' => [
                '<string>'
        ],
        'lyzr_tools' => [
                [
                                
                ]
        ],
        'agent_id' => '<string>',
        'user_id' => '<string>',
        'session_id' => '<string>',
        'preemptive_generation' => true,
        'pronunciation_correction' => true,
        'pronunciation_rules' => [
                
        ],
        'audio_recording_enabled' => true,
        'vad_enabled' => true,
        'avatar' => [
                
        ],
        'background_audio' => [
                
        ],
        'corrections' => [
                [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://voice-livekit.studio.lyzr.ai/v1/agents"

	payload := strings.NewReader("{\n  \"config\": {\n    \"agent_name\": \"<string>\",\n    \"agent_description\": \"<string>\",\n    \"engine\": {\n      \"kind\": \"<string>\",\n      \"stt\": \"<string>\",\n      \"llm\": \"<string>\",\n      \"tts\": \"<string>\",\n      \"voice_id\": \"<string>\",\n      \"language\": \"<string>\"\n    },\n    \"engine_pipeline\": {},\n    \"engine_realtime\": {},\n    \"prompt\": \"<string>\",\n    \"agent_role\": \"<string>\",\n    \"agent_goal\": \"<string>\",\n    \"agent_instructions\": \"<string>\",\n    \"dynamic_variables\": {},\n    \"dynamic_variable_defaults\": {},\n    \"conversation_start\": {\n      \"who\": \"<string>\",\n      \"greeting\": \"<string>\"\n    },\n    \"turn_detection\": \"<string>\",\n    \"noise_cancellation\": {},\n    \"api_key\": \"<string>\",\n    \"knowledge_base\": {},\n    \"managed_agents\": {},\n    \"tools\": [\n      \"<string>\"\n    ],\n    \"lyzr_tools\": [\n      {}\n    ],\n    \"agent_id\": \"<string>\",\n    \"user_id\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"preemptive_generation\": true,\n    \"pronunciation_correction\": true,\n    \"pronunciation_rules\": {},\n    \"audio_recording_enabled\": true,\n    \"vad_enabled\": true,\n    \"avatar\": {},\n    \"background_audio\": {},\n    \"corrections\": [\n      {}\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://voice-livekit.studio.lyzr.ai/v1/agents")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"config\": {\n    \"agent_name\": \"<string>\",\n    \"agent_description\": \"<string>\",\n    \"engine\": {\n      \"kind\": \"<string>\",\n      \"stt\": \"<string>\",\n      \"llm\": \"<string>\",\n      \"tts\": \"<string>\",\n      \"voice_id\": \"<string>\",\n      \"language\": \"<string>\"\n    },\n    \"engine_pipeline\": {},\n    \"engine_realtime\": {},\n    \"prompt\": \"<string>\",\n    \"agent_role\": \"<string>\",\n    \"agent_goal\": \"<string>\",\n    \"agent_instructions\": \"<string>\",\n    \"dynamic_variables\": {},\n    \"dynamic_variable_defaults\": {},\n    \"conversation_start\": {\n      \"who\": \"<string>\",\n      \"greeting\": \"<string>\"\n    },\n    \"turn_detection\": \"<string>\",\n    \"noise_cancellation\": {},\n    \"api_key\": \"<string>\",\n    \"knowledge_base\": {},\n    \"managed_agents\": {},\n    \"tools\": [\n      \"<string>\"\n    ],\n    \"lyzr_tools\": [\n      {}\n    ],\n    \"agent_id\": \"<string>\",\n    \"user_id\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"preemptive_generation\": true,\n    \"pronunciation_correction\": true,\n    \"pronunciation_rules\": {},\n    \"audio_recording_enabled\": true,\n    \"vad_enabled\": true,\n    \"avatar\": {},\n    \"background_audio\": {},\n    \"corrections\": [\n      {}\n    ]\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://voice-livekit.studio.lyzr.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"config\": {\n    \"agent_name\": \"<string>\",\n    \"agent_description\": \"<string>\",\n    \"engine\": {\n      \"kind\": \"<string>\",\n      \"stt\": \"<string>\",\n      \"llm\": \"<string>\",\n      \"tts\": \"<string>\",\n      \"voice_id\": \"<string>\",\n      \"language\": \"<string>\"\n    },\n    \"engine_pipeline\": {},\n    \"engine_realtime\": {},\n    \"prompt\": \"<string>\",\n    \"agent_role\": \"<string>\",\n    \"agent_goal\": \"<string>\",\n    \"agent_instructions\": \"<string>\",\n    \"dynamic_variables\": {},\n    \"dynamic_variable_defaults\": {},\n    \"conversation_start\": {\n      \"who\": \"<string>\",\n      \"greeting\": \"<string>\"\n    },\n    \"turn_detection\": \"<string>\",\n    \"noise_cancellation\": {},\n    \"api_key\": \"<string>\",\n    \"knowledge_base\": {},\n    \"managed_agents\": {},\n    \"tools\": [\n      \"<string>\"\n    ],\n    \"lyzr_tools\": [\n      {}\n    ],\n    \"agent_id\": \"<string>\",\n    \"user_id\": \"<string>\",\n    \"session_id\": \"<string>\",\n    \"preemptive_generation\": true,\n    \"pronunciation_correction\": true,\n    \"pronunciation_rules\": {},\n    \"audio_recording_enabled\": true,\n    \"vad_enabled\": true,\n    \"avatar\": {},\n    \"background_audio\": {},\n    \"corrections\": [\n      {}\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "agent": {
    "id": "45da1ca5df31afac7c4417c9",
    "config": {
      "agent_name": "<string>",
      "agent_description": "<string>",
      "engine": {
        "kind": "<string>",
        "stt": "<string>",
        "llm": "<string>",
        "tts": "<string>",
        "voice_id": "<string>",
        "language": "<string>"
      },
      "engine_pipeline": {},
      "engine_realtime": {},
      "prompt": "<string>",
      "agent_role": "<string>",
      "agent_goal": "<string>",
      "agent_instructions": "<string>",
      "dynamic_variables": {},
      "dynamic_variable_defaults": {},
      "conversation_start": {
        "who": "<string>",
        "greeting": "<string>"
      },
      "turn_detection": "<string>",
      "noise_cancellation": {},
      "api_key": "<string>",
      "knowledge_base": {},
      "managed_agents": {},
      "tools": [
        "<string>"
      ],
      "lyzr_tools": [
        {}
      ],
      "agent_id": "<string>",
      "user_id": "<string>",
      "session_id": "<string>",
      "preemptive_generation": true,
      "pronunciation_correction": true,
      "pronunciation_rules": {},
      "audio_recording_enabled": true,
      "vad_enabled": true,
      "avatar": {},
      "background_audio": {},
      "corrections": [
        {}
      ]
    },
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "shared": true
  }
}
{
  "error": "<string>",
  "issues": [
    {}
  ],
  "example": {}
}
Use this endpoint to create a new, saved Voice Agent. Building an agent requires passing a detailed config object in your request payload. This configuration dictates everything from the agent’s core personality to its visual avatar and integrated tools.
Authentication Required: You must include your API key in the x-api-key header to authenticate your request.

​
Understanding the config Payload

Because Voice Agents are highly customizable, the config object contains many parameters. Below is a breakdown of the most critical sections you will need to configure when creating a new agent.

​
Core Identity

These parameters define who your agent is and how it behaves.
  • agent_name & agent_description: Internal identifiers for your team.
  • agent_role, agent_goal, & agent_instructions: The fundamental prompt blocks that guide the LLM’s logic and behavior.

​
The Engine

The engine object determines the specific models powering the agent’s brain, ears, and mouth.
  • stt (Speech-to-Text): The model used to transcribe user audio (e.g., Deepgram, Whisper).
  • llm (Large Language Model): The reasoning engine (e.g., GPT-4o, Claude 3).
  • tts (Text-to-Speech) & voice_id: The model and specific voice clone used to generate the agent’s audio response (e.g., ElevenLabs).

​
Capabilities & Integrations

You can empower your agent with external knowledge and actions.
  • knowledge_base: Connect a Lyzr RAG or Agentic RAG system so your agent can answer questions based on your proprietary documents.
  • tools & lyzr_tools: Equip your agent with APIs (like checking order status, booking appointments, or sending emails) that it can trigger mid-conversation.

​
Avatars & Environment

If your agent is being deployed in a visual interface, you can configure its appearance and surroundings.
  • avatar: Select a provider (like HeyGen, Simli, or Tavus) and pass the corresponding avatar_id to render a digital human.
  • background_audio: Enable ambient noise or sound effects (like typing or a cafe background) to make the call feel more natural.

​
Next Steps

Once your agent is created, the API will return a 201 Created status along with the unique id of your new agent. You will use this id when initiating LiveKit sessions.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
config
object
required

Comprehensive configuration settings for the agent.

Response

Agent created successfully.

​
agent
object