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

# Create Agent

> Create a new AI voice agent

## Request

Create a new AI voice agent with custom personality, voice, and behavior settings.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="name" type="string" required>
  A friendly name for the agent (e.g., "Sales Assistant")
</ParamField>

<ParamField body="system_prompt" type="string" required>
  The instructions defining the agent's personality, goals, and behavior
</ParamField>

<ParamField body="voice_id" type="string" required>
  The voice to use for the agent. See [available voices](/concepts/agents#voices).
</ParamField>

<ParamField body="first_message" type="string">
  The greeting message the agent says when the call connects
</ParamField>

<ParamField body="language" type="string" default="en-US">
  Primary language for the agent (e.g., `en-US`, `es-ES`, `fr-FR`)
</ParamField>

<ParamField body="model" type="string" default="gpt-4o">
  The LLM to use: `gpt-4o`, `gpt-4o-mini`, `claude-3-sonnet`
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
  Creativity level (0.0-1.0). Lower = more focused, higher = more creative.
</ParamField>

<ParamField body="max_tokens" type="integer" default="150">
  Maximum tokens per response (affects verbosity)
</ParamField>

<ParamField body="interruption_threshold" type="number" default="0.5">
  How easily the user can interrupt (0.0-1.0). Higher = easier to interrupt.
</ParamField>

<ParamField body="end_call_phrases" type="array">
  Phrases that will end the call (e.g., `["goodbye", "that's all"]`)
</ParamField>

<ParamField body="metadata" type="object">
  Custom key-value pairs for your reference
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the agent
</ResponseField>

<ResponseField name="name" type="string">
  The agent's name
</ResponseField>

<ResponseField name="voice_id" type="string">
  The voice ID
</ResponseField>

<ResponseField name="status" type="string">
  Agent status: `active`, `inactive`
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ringyo.ai/v1/agents \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sales Assistant",
      "system_prompt": "You are Sarah, a friendly sales assistant for Acme Corp. Your goal is to qualify leads and schedule demos. Be professional but warm. Ask about their current challenges and how Acme can help.",
      "voice_id": "sarah-professional",
      "first_message": "Hi! This is Sarah from Acme Corp. I'\''m reaching out to see if we can help with your business needs. Do you have a moment to chat?",
      "language": "en-US",
      "model": "gpt-4o"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.ringyo.ai/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Sales Assistant',
      system_prompt: `You are Sarah, a friendly sales assistant for Acme Corp. 
        Your goal is to qualify leads and schedule demos. Be professional but warm.`,
      voice_id: 'sarah-professional',
      first_message: "Hi! This is Sarah from Acme Corp...",
      language: 'en-US',
      model: 'gpt-4o'
    })
  });

  const agent = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ringyo.ai/v1/agents',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'name': 'Sales Assistant',
          'system_prompt': 'You are Sarah, a friendly sales assistant...',
          'voice_id': 'sarah-professional',
          'first_message': 'Hi! This is Sarah from Acme Corp...',
          'language': 'en-US',
          'model': 'gpt-4o'
      }
  )

  agent = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "id": "agent_abc123",
    "name": "Sales Assistant",
    "system_prompt": "You are Sarah, a friendly sales assistant...",
    "voice_id": "sarah-professional",
    "first_message": "Hi! This is Sarah from Acme Corp...",
    "language": "en-US",
    "model": "gpt-4o",
    "temperature": 0.7,
    "max_tokens": 150,
    "interruption_threshold": 0.5,
    "end_call_phrases": [],
    "status": "active",
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": {
      "code": "invalid_voice_id",
      "message": "The specified voice_id does not exist"
    }
  }
  ```

  ```json 402 - Limit Reached theme={null}
  {
    "error": {
      "code": "agent_limit_reached",
      "message": "You have reached the maximum number of agents for your plan"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                    | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `invalid_voice_id`      | The specified voice does not exist                    |
| `agent_limit_reached`   | Your plan's agent limit has been reached              |
| `invalid_system_prompt` | System prompt is too long or contains invalid content |
| `invalid_language`      | The specified language is not supported               |