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

# Create Agent

> Create a new agent.



## OpenAPI

````yaml /openapi.json post /v1/agents
openapi: 3.1.0
info:
  title: Beyond Presence API
  summary: Create, configure, and run interactive real-time avatars.
  description: >
    The Beyond Presence API lets you build lifelike, real-time avatars.


    ## Authentication


    Authenticate every request with your API key in the `x-api-key` header:


    ```

    x-api-key: <your-api-key>

    ```


    You can create and manage API keys in the dashboard, and verify a key with

    `GET /v1/auth/verify`.


    ## Pagination


    List endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to
    control

    the page size and `cursor` to fetch the next page. Each response includes a

    `next_cursor` when more results are available.


    ## Errors


    Errors return the appropriate HTTP status code with a JSON body containing a

    `detail` message with more information.


    ## Rate limits


    Usage and concurrency limits are tied to your plan and surfaced as HTTP
    `429`

    responses.
  version: 0.3.0
servers:
  - url: https://api.bey.dev
security: []
paths:
  /v1/agents:
    post:
      tags:
        - Agents
      summary: Create Agent
      description: Create a new agent.
      operationId: create_agent_v1_agents_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Created Agent with ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          description: >-
            Authentication failed. The `x-api-key` header is missing or the
            provided API key is invalid.
          content:
            application/json:
              examples:
                missing:
                  summary: Missing API key
                  value:
                    detail: API key is required.
                invalid:
                  summary: Invalid API key
                  value:
                    detail: Invalid API key.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The API key is valid but not permitted to perform this action,
            either because the resource belongs to someone else or because the
            requested feature requires a plan upgrade.
          content:
            application/json:
              examples:
                permission:
                  summary: Not permitted
                  value:
                    detail: You do not have permission to access this resource.
                plan:
                  summary: Plan upgrade required
                  value:
                    detail: >-
                      This feature is not available on your current plan. Please
                      upgrade your plan.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The requested resource does not exist or is not accessible with this
            API key.
          content:
            application/json:
              example:
                detail: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            The request is malformed. `detail` lists each field that failed
            validation, where it was located, and why.
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - name
                    msg: Field required
                    type: missing
        '429':
          description: >-
            A plan limit has been exceeded, either the usage limit or the number
            of concurrent sessions.
          content:
            application/json:
              examples:
                usage:
                  summary: Usage limit exceeded
                  value:
                    detail: Usage limit exceeded. Please upgrade your plan.
                concurrency:
                  summary: Concurrency limit exceeded
                  value:
                    detail: >-
                      You have reached your concurrency limit. Please upgrade
                      your plan or stop other ongoing sessions.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    CreateAgentRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Display name to use. Also used when addressed in conversations.
          examples:
            - Jarvis
            - HAL 9000
        avatar_id:
          type: string
          maxLength: 100
          minLength: 1
          title: Avatar Id
          description: ID of avatar to use.
          examples:
            - 01234567-89ab-cdef-0123-456789abcdef
        system_prompt:
          type: string
          maxLength: 10000
          minLength: 1
          title: System Prompt
          description: System prompt to use.
          examples:
            - You are a helpful assistant.
        language:
          anyOf:
            - $ref: '#/components/schemas/Language'
            - type: 'null'
          description: Language to use.
          examples:
            - en
            - en-US
            - de
        greeting:
          anyOf:
            - type: string
              maxLength: 1000
              minLength: 1
            - type: 'null'
          title: Greeting
          description: What to say when a call starts.
          examples:
            - Hello!
        max_session_length_minutes:
          anyOf:
            - type: integer
              maximum: 90
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Session Length Minutes
          description: Maximum session length in minutes.
          examples:
            - 30
        capabilities:
          $ref: '#/components/schemas/AgentCapabilityList'
          description: Extra capabilities to manage calls.
          examples:
            - - type: webcam_vision
              - triggers:
                  - hey agent
                  - hi pal
                type: wakeup_mode
        llm:
          anyOf:
            - $ref: '#/components/schemas/AgentLlm'
            - type: 'null'
          description: Configuration for LLM to use.
          examples:
            - type: openai
            - api_id: 01234567-89ab-cdef-0123-456789abcdef
              model: gpt-4o-mini
              temperature: 0.7
              type: openai_compatible
        tts:
          anyOf:
            - $ref: '#/components/schemas/AgentTts'
            - type: 'null'
          description: Configuration for TTS to use.
          examples:
            - type: elevenlabs
              voice: 21m00Tcm4TlvDq8ikWAM
        knowledge_file_ids:
          items:
            type: string
            minLength: 1
          type: array
          uniqueItems: true
          title: Knowledge File Ids
          description: IDs of knowledge files to refer to.
      type: object
      required:
        - name
        - avatar_id
        - system_prompt
      title: CreateAgentRequest
      description: Request body to create an agent.
    AgentResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier of the object in the database.
          examples:
            - 01234567-89ab-cdef-0123-456789abcdef
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Display name to use. Also used when addressed in conversations.
          examples:
            - Jarvis
            - HAL 9000
        avatar_id:
          type: string
          maxLength: 100
          minLength: 1
          title: Avatar Id
          description: ID of avatar to use.
          examples:
            - 01234567-89ab-cdef-0123-456789abcdef
        system_prompt:
          type: string
          maxLength: 10000
          minLength: 1
          title: System Prompt
          description: System prompt to use.
          examples:
            - You are a helpful assistant.
        language:
          anyOf:
            - $ref: '#/components/schemas/Language'
            - type: 'null'
          description: Language to use.
          examples:
            - en
            - en-US
            - de
        greeting:
          anyOf:
            - type: string
              maxLength: 1000
              minLength: 1
            - type: 'null'
          title: Greeting
          description: What to say when a call starts.
          examples:
            - Hello!
        max_session_length_minutes:
          anyOf:
            - type: integer
              maximum: 90
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Session Length Minutes
          description: Maximum session length in minutes.
          examples:
            - 30
        capabilities:
          $ref: '#/components/schemas/AgentCapabilityList'
          description: Extra capabilities to manage calls.
          examples:
            - - type: webcam_vision
              - triggers:
                  - hey agent
                  - hi pal
                type: wakeup_mode
        llm:
          anyOf:
            - $ref: '#/components/schemas/AgentLlm'
            - type: 'null'
          description: Configuration for LLM to use.
          examples:
            - type: openai
            - api_id: 01234567-89ab-cdef-0123-456789abcdef
              model: gpt-4o-mini
              temperature: 0.7
              type: openai_compatible
        tts:
          anyOf:
            - $ref: '#/components/schemas/AgentTts'
            - type: 'null'
          description: Configuration for TTS to use.
          examples:
            - type: elevenlabs
              voice: 21m00Tcm4TlvDq8ikWAM
        knowledge_file_ids:
          items:
            type: string
            minLength: 1
          type: array
          uniqueItems: true
          title: Knowledge File Ids
          description: IDs of knowledge files to refer to.
      type: object
      required:
        - id
        - name
        - avatar_id
        - system_prompt
      title: AgentResponse
      description: Response model for an agent.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable description of the error.
          examples:
            - Invalid API key.
      type: object
      required:
        - detail
      title: ErrorResponse
      description: >-
        Standard error response body.


        Carries a single human-readable `detail` message describing what went

        wrong. This is the shape of every error response except validation
        errors

        (`422`), which instead return a list of per-field error objects.
    Language:
      type: string
      enum:
        - ar
        - ar-SA
        - bn
        - bg
        - zh
        - cs
        - da
        - nl
        - en
        - en-AU
        - en-GB
        - en-US
        - fi
        - fr
        - fr-CA
        - fr-FR
        - de
        - el
        - hi
        - hu
        - id
        - it
        - ja
        - kk
        - ko
        - ms
        - 'no'
        - pl
        - pt
        - pt-BR
        - pt-PT
        - ro
        - ru
        - sk
        - es
        - sv
        - tr
        - uk
        - ur
        - vi
      title: Language
      description: Language for communication.
    AgentCapabilityList:
      items:
        $ref: '#/components/schemas/AgentCapability'
      type: array
    AgentLlm:
      oneOf:
        - $ref: '#/components/schemas/LivekitAgentLlm'
        - $ref: '#/components/schemas/OpenaiAgentLlm'
        - $ref: '#/components/schemas/OpenaiCompatibleAgentLlm'
      discriminator:
        propertyName: type
        mapping:
          livekit:
            $ref: '#/components/schemas/LivekitAgentLlm'
          openai:
            $ref: '#/components/schemas/OpenaiAgentLlm'
          openai_compatible:
            $ref: '#/components/schemas/OpenaiCompatibleAgentLlm'
    AgentTts:
      oneOf:
        - $ref: '#/components/schemas/LivekitAgentTts'
        - $ref: '#/components/schemas/ElevenlabsAgentTts'
        - $ref: '#/components/schemas/DeepgramAgentTts'
        - $ref: '#/components/schemas/OpenaiAgentTts'
        - $ref: '#/components/schemas/GoogleAgentTts'
      discriminator:
        propertyName: type
        mapping:
          deepgram:
            $ref: '#/components/schemas/DeepgramAgentTts'
          elevenlabs:
            $ref: '#/components/schemas/ElevenlabsAgentTts'
          google_tts:
            $ref: '#/components/schemas/GoogleAgentTts'
          livekit:
            $ref: '#/components/schemas/LivekitAgentTts'
          openai_tts:
            $ref: '#/components/schemas/OpenaiAgentTts'
    AgentCapability:
      oneOf:
        - $ref: '#/components/schemas/WebcamVisionAgentCapability'
        - $ref: '#/components/schemas/WakeupModeAgentCapability'
      discriminator:
        propertyName: type
        mapping:
          wakeup_mode:
            $ref: '#/components/schemas/WakeupModeAgentCapability'
          webcam_vision:
            $ref: '#/components/schemas/WebcamVisionAgentCapability'
    LivekitAgentLlm:
      properties:
        type:
          type: string
          const: livekit
          title: Type
          default: livekit
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - low
                - medium
                - high
                - xhigh
            - type: 'null'
          title: Reasoning Effort
      type: object
      title: LivekitAgentLlm
      description: Configuration for LLMs supported via LiveKit Inference.
    OpenaiAgentLlm:
      properties:
        type:
          type: string
          const: openai
          title: Type
          default: openai
        model:
          anyOf:
            - type: string
              enum:
                - gpt-5.4-mini
                - gpt-4.1-mini
                - gpt-4.1
            - type: 'null'
          title: Model
          description: Name of model to use. Defaults to GPT 5.4 mini.
      type: object
      title: OpenaiAgentLlm
      description: Configuration for OpenAI LLM.
    OpenaiCompatibleAgentLlm:
      properties:
        type:
          type: string
          const: openai_compatible
          title: Type
          default: openai_compatible
        api_id:
          type: string
          title: Api Id
        model:
          type: string
          title: Model
        temperature:
          type: number
          title: Temperature
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      type: object
      required:
        - api_id
        - model
        - temperature
      title: OpenaiCompatibleAgentLlm
      description: >-
        Configuration for an LLM provided by an OpenAI-compatible API.


        The notion of "OpenAI-compatible API" is somewhat fuzzy, there is no

        agreed upon standard for what it means.

        In practice, we care if the API is compatible with how LiveKit's openai

        plugin interacts with it, i.e. a subset of OpenAI's API specification
        that

        provides chat completions:

        https://platform.openai.com/docs/api-reference/completions
    LivekitAgentTts:
      properties:
        type:
          type: string
          const: livekit
          title: Type
          default: livekit
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
      type: object
      title: LivekitAgentTts
      description: Configuration for TTS supported via LiveKit Inference.
    ElevenlabsAgentTts:
      properties:
        type:
          type: string
          const: elevenlabs
          title: Type
          default: elevenlabs
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
      type: object
      title: ElevenlabsAgentTts
      description: Configuration for Elevenlabs TTS.
    DeepgramAgentTts:
      properties:
        type:
          type: string
          const: deepgram
          title: Type
          default: deepgram
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
      type: object
      title: DeepgramAgentTts
      description: Configuration for Deepgram TTS.
    OpenaiAgentTts:
      properties:
        type:
          type: string
          const: openai_tts
          title: Type
          default: openai_tts
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
      type: object
      title: OpenaiAgentTts
      description: Configuration for OpenAI TTS.
    GoogleAgentTts:
      properties:
        type:
          type: string
          const: google_tts
          title: Type
          default: google_tts
        voice:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice
      type: object
      title: GoogleAgentTts
      description: Configuration for Google TTS.
    WebcamVisionAgentCapability:
      properties:
        type:
          type: string
          const: webcam_vision
          title: Type
          default: webcam_vision
      type: object
      title: WebcamVisionAgentCapability
      description: Agent capability to see user camera feed.
    WakeupModeAgentCapability:
      properties:
        type:
          type: string
          const: wakeup_mode
          title: Type
          default: wakeup_mode
        triggers:
          items:
            type: string
          type: array
          title: Triggers
      type: object
      required:
        - triggers
      title: WakeupModeAgentCapability
      description: Agent capability to wake up only on specific keywords.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Your Beyond Presence API Key.
      in: header
      name: x-api-key

````

## Related topics

- [Managed Agent Quickstart](/get-started/quickstart/managed-agent.md)
- [External LLM](/concepts/agents/external-llm.md)
- [Extra Capabilities](/concepts/agents/extra-capabilities.md)
- [Just-in-Time Context](/concepts/agents/just-in-time-context.md)
- [Speech-to-Video Quickstart](/get-started/quickstart/speech-to-video.md)