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

# Create a new XUNA AI Conversational AI voice agent

> Use POST /v1/convai/agents to provision a voice agent with a name, TTS voice, system prompt, opening first message, and optional tags.

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

<ParamField body="name" type="string" required>
  A human-readable label for the agent. Shown in the dashboard and in list responses.
</ParamField>

<ParamField body="tags" type="string[]">
  Optional tags for organising agents. Useful for filtering in the dashboard.
</ParamField>

<ParamField body="conversation_config" type="object">
  Agent behaviour and voice settings.

  <Expandable title="conversation_config properties">
    <ParamField body="conversation_config.tts" type="object">
      Text-to-speech configuration.

      <Expandable title="tts properties">
        <ParamField body="conversation_config.tts.voice_id" type="string" required>
          The XUNA AI voice ID to use for the agent's speech.
        </ParamField>

        <ParamField body="conversation_config.tts.model_id" type="string">
          The TTS model to use. Defaults to `xuna_flash_v2` for low-latency responses.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="conversation_config.agent" type="object">
      Conversation behaviour settings.

      <Expandable title="agent properties">
        <ParamField body="conversation_config.agent.first_message" type="string">
          The opening line the agent speaks when a conversation starts.
        </ParamField>

        <ParamField body="conversation_config.agent.prompt" type="object">
          System prompt configuration.

          <Expandable title="prompt properties">
            <ParamField body="conversation_config.agent.prompt.prompt" type="string">
              The system prompt text that defines the agent's persona, goals, and constraints.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Example request

<CodeGroup>
  ```python Python theme={null}
  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": "xuna_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)
  ```

  ```typescript TypeScript theme={null}
  import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

  const client = new XunaAIClient({ apiKey: "YOUR_API_KEY" });

  const agent = await client.conversationalAi.agents.create({
      name: "My voice agent",
      tags: ["test"],
      conversationConfig: {
          tts: {
              voiceId: "aMSt68OGf4xUZAnLpTU8",
              modelId: "xuna_flash_v2",
          },
          agent: {
              firstMessage: "Hi, how can I help you today?",
              prompt: {
                  prompt: "You are a helpful assistant.",
              },
          },
      },
  });

  console.log("Agent ID:", agent.agentId);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.xuna.ai/v1/convai/agents \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My voice agent",
      "tags": ["test"],
      "conversation_config": {
        "tts": {
          "voice_id": "aMSt68OGf4xUZAnLpTU8",
          "model_id": "xuna_flash_v2"
        },
        "agent": {
          "first_message": "Hi, how can I help you today?",
          "prompt": {
            "prompt": "You are a helpful assistant."
          }
        }
      }
    }'
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6"
}
```

<ResponseField name="agent_id" type="string" required>
  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.
</ResponseField>

<Note>
  After creating an agent you can update any part of its configuration at any time using the [PATCH endpoint](/api-reference/agents/manage#update-an-agent).
</Note>