--- title: "Create Agent" method: POST path: "/v1/agents" tags: ["Agents"] --- # Create Agent `POST /v1/agents` ## Request - Base URL: `https://api.bey.dev` - URL: `https://api.bey.dev/v1/agents` - Auth: API key in header `x-api-key` Create a new agent. ## Request body - CreateAgentRequest: Request body to create an agent. - `name` string, required: Display name to use. Also used when addressed in conversations. - `avatar_id` string, required: ID of avatar to use. - `system_prompt` string, required: System prompt to use. - `language` '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': Language for communication. - `greeting` string, nullable: What to say when a call starts. - `max_session_length_minutes` integer, nullable: Maximum session length in minutes. - `capabilities` AgentCapability[] - union - WebcamVisionAgentCapability: Agent capability to see user camera feed. - `type` 'webcam_vision' - WakeupModeAgentCapability: Agent capability to wake up only on specific keywords. - `type` 'wakeup_mode' - `triggers` string[], required - `llm` union - LivekitAgentLlm: Configuration for LLMs supported via LiveKit Inference. - `type` 'livekit' - `model` string, nullable - `reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh', nullable - OpenaiAgentLlm: Configuration for OpenAI LLM. - `type` 'openai' - `model` 'gpt-5.4-mini' | 'gpt-4.1-mini' | 'gpt-4.1', nullable: Name of model to use. Defaults to GPT 5.4 mini. - OpenaiCompatibleAgentLlm: 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 - `type` 'openai_compatible' - `api_id` string, required - `model` string, required - `temperature` number, required - `headers` object - ElevenlabsAgentLlm: Configuration for running your own ElevenLabs agent. ElevenLabs runs the conversation with the agent's own prompt, voice, knowledge base and tools, so the agent cannot set a TTS or a greeting, nor use webcam vision, wakeup mode or dynamic avatar emotions. The ElevenLabs agent should send the `agent_response_complete` client event. - `type` 'elevenlabs_agent' - `api_id` string, required - `agent_id` string, required - `tts` union - LivekitAgentTts: Configuration for TTS supported via LiveKit Inference. - `type` 'livekit' - `model` string, nullable - `voice` string, nullable - CartesiaAgentTts: Configuration for Cartesia TTS. - `type` 'cartesia' - `model` string, nullable - `voice` string, nullable - ElevenlabsAgentTts: Configuration for Elevenlabs TTS. - `type` 'elevenlabs' - `voice` string, nullable - DeepgramAgentTts: Configuration for Deepgram TTS. - `type` 'deepgram' - `voice` string, nullable - OpenaiAgentTts: Configuration for OpenAI TTS. - `type` 'openai_tts' - `voice` string, nullable - GoogleAgentTts: Configuration for Google TTS. - `type` 'google_tts' - `voice` string, nullable - `knowledge_file_ids` string[]: IDs of knowledge files to refer to. ## Response `201` Created Agent with ID - AgentResponse: Response model for an agent. - `id` string, required: Unique identifier of the object in the database. - `name` string, required: Display name to use. Also used when addressed in conversations. - `avatar_id` string, required: ID of avatar to use. - `system_prompt` string, required: System prompt to use. - `language` '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': Language for communication. - `greeting` string, nullable: What to say when a call starts. - `max_session_length_minutes` integer, nullable: Maximum session length in minutes. - `capabilities` AgentCapability[] - union - WebcamVisionAgentCapability: Agent capability to see user camera feed. - `type` 'webcam_vision' - WakeupModeAgentCapability: Agent capability to wake up only on specific keywords. - `type` 'wakeup_mode' - `triggers` string[], required - `llm` union - LivekitAgentLlm: Configuration for LLMs supported via LiveKit Inference. - `type` 'livekit' - `model` string, nullable - `reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh', nullable - OpenaiAgentLlm: Configuration for OpenAI LLM. - `type` 'openai' - `model` 'gpt-5.4-mini' | 'gpt-4.1-mini' | 'gpt-4.1', nullable: Name of model to use. Defaults to GPT 5.4 mini. - OpenaiCompatibleAgentLlm: 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 - `type` 'openai_compatible' - `api_id` string, required - `model` string, required - `temperature` number, required - `headers` object - ElevenlabsAgentLlm: Configuration for running your own ElevenLabs agent. ElevenLabs runs the conversation with the agent's own prompt, voice, knowledge base and tools, so the agent cannot set a TTS or a greeting, nor use webcam vision, wakeup mode or dynamic avatar emotions. The ElevenLabs agent should send the `agent_response_complete` client event. - `type` 'elevenlabs_agent' - `api_id` string, required - `agent_id` string, required - `tts` union - LivekitAgentTts: Configuration for TTS supported via LiveKit Inference. - `type` 'livekit' - `model` string, nullable - `voice` string, nullable - CartesiaAgentTts: Configuration for Cartesia TTS. - `type` 'cartesia' - `model` string, nullable - `voice` string, nullable - ElevenlabsAgentTts: Configuration for Elevenlabs TTS. - `type` 'elevenlabs' - `voice` string, nullable - DeepgramAgentTts: Configuration for Deepgram TTS. - `type` 'deepgram' - `voice` string, nullable - OpenaiAgentTts: Configuration for OpenAI TTS. - `type` 'openai_tts' - `voice` string, nullable - GoogleAgentTts: Configuration for Google TTS. - `type` 'google_tts' - `voice` string, nullable - `knowledge_file_ids` string[]: IDs of knowledge files to refer to. ## Other responses - `401`: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid. - `402`: The plan's usage limit has been reached, or the requested feature requires a plan upgrade. - `403`: The API key is valid but not permitted to perform this action, because the resource belongs to someone else. - `404`: The requested resource does not exist or is not accessible with this API key. - `422`: The request is malformed. `detail` lists each field that failed validation, where it was located, and why. - `429`: The plan's limit on the number of concurrent sessions has been reached. ## Changes - **2026-10-20** `0469e200c235`: 1 info - added the non-success response with the status `402` - **2026-10-16** `c8f80740b51c`: 1 info - endpoint added [Operation history](https://skmtc.dev/bey-dev/apis/beyond-presence-api/changes/v1/agents/post.md) --- [API](https://skmtc.dev/bey-dev/apis/beyond-presence-api.md) - [All operations](https://skmtc.dev/bey-dev/apis/beyond-presence-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bey-dev/apis/beyond-presence-api/revisions/2d37d86bc5c1?raw)