> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Agent

> Create a new saved voice agent with a specific configuration.

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.

<Warning>
  **Authentication Required:** You must include your API key in the `x-api-key` header to authenticate your request.
</Warning>

### 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.


## OpenAPI

````yaml post /agents
openapi: 3.0.3
info:
  title: Lyzr Voice LiveKit API
  version: 1.0.0
servers:
  - url: https://voice-livekit.studio.lyzr.ai/v1
security: []
paths:
  /agents:
    post:
      summary: Create Agent
      description: Create a new saved voice agent with a specific configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - config
              properties:
                config:
                  $ref: '#/components/schemas/AgentConfig'
      responses:
        '201':
          description: Agent created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 45da1ca5df31afac7c4417c9
                      config:
                        $ref: '#/components/schemas/AgentConfig'
                      createdAt:
                        type: string
                      updatedAt:
                        type: string
                      shared:
                        type: boolean
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  issues:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  example:
                    type: object
                    additionalProperties: true
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentConfig:
      type: object
      description: Comprehensive configuration settings for the agent.
      properties:
        agent_name:
          type: string
        agent_description:
          type: string
        engine:
          type: object
          properties:
            kind:
              type: string
            stt:
              type: string
            llm:
              type: string
            tts:
              type: string
            voice_id:
              type: string
            language:
              type: string
        engine_pipeline:
          type: object
        engine_realtime:
          type: object
        prompt:
          type: string
        agent_role:
          type: string
        agent_goal:
          type: string
        agent_instructions:
          type: string
        dynamic_variables:
          type: object
          additionalProperties:
            type: string
        dynamic_variable_defaults:
          type: object
          additionalProperties:
            type: string
        conversation_start:
          type: object
          properties:
            who:
              type: string
            greeting:
              type: string
        turn_detection:
          type: string
        noise_cancellation:
          type: object
        api_key:
          type: string
        knowledge_base:
          type: object
        managed_agents:
          type: object
        tools:
          type: array
          items:
            type: string
        lyzr_tools:
          type: array
          items:
            type: object
        agent_id:
          type: string
        user_id:
          type: string
        session_id:
          type: string
        preemptive_generation:
          type: boolean
        pronunciation_correction:
          type: boolean
        pronunciation_rules:
          type: object
        audio_recording_enabled:
          type: boolean
        vad_enabled:
          type: boolean
        avatar:
          type: object
        background_audio:
          type: object
        corrections:
          type: array
          items:
            type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````