The create agent endpoint provisions a new voice agent and returns its agent_id. You pass the agent ID to start conversations, assign phone numbers, or launch batch calls.
Endpoint POST https://api.xuna.ai/v1/convai/agents
Request parameters A human-readable label for the agent. Shown in the dashboard and in list responses.
Optional tags for organising agents. Useful for filtering in the dashboard.
Agent behaviour and voice settings. Show conversation_config properties
Text-to-speech configuration. conversation_config.tts.voice_id
The XUNA AI voice ID to use for the agent’s speech.
conversation_config.tts.model_id
The TTS model to use. Defaults to eleven_flash_v2 for low-latency responses.
conversation_config.agent
Conversation behaviour settings. conversation_config.agent.first_message
The opening line the agent speaks when a conversation starts.
conversation_config.agent.prompt
System prompt configuration. conversation_config.agent.prompt.prompt
The system prompt text that defines the agent’s persona, goals, and constraints.
Example request from xuna_ai.client import XunaAI client = XunaAI( api_key = "YOUR_API_KEY" ) response = client.conversational_ai.agents.create( name = "My voice agent" , tags = [ "test" ], conversation_config = { "tts" : { "voice_id" : "aMSt68OGf4xUZAnLpTU8" , "model_id" : "eleven_flash_v2" , }, "agent" : { "first_message" : "Hi, how can I help you today?" , "prompt" : { "prompt" : "You are a helpful assistant." , }, }, }, ) print ( "Agent ID:" , response.agent_id)
Response { "agent_id" : "agent_7101k5zvyjhmfg983brhmhkd98n6" }
The unique identifier for the newly created agent. Store this value — you need it to start conversations, update the agent, or assign a phone number.
After creating an agent you can update any part of its configuration at any time using the PATCH endpoint . 
