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

# Create Agent

> Create a prompt-based voice agent

Creates a prompt-based voice agent and deploys it immediately — the returned
`agent_id` can be used right away as `override_agent_id` on [Dial](/api-reference/call-dial).

<Note>
  Only prompt-based agents can be created via the API. Flow agents (multi-step
  conversational flows with branching, function calls, and knowledge bases) are
  built in the [dashboard](https://app.voicy.co).
</Note>

## Body Parameters

<ParamField body="name" type="string" required>Agent display name.</ParamField>

<ParamField body="prompt" type="string" required>
  System prompt that defines the agent's behavior.
</ParamField>

<ParamField body="language" type="string" default="he">Language code, e.g. `he` or `en`.</ParamField>

<ParamField body="voice" type="string" default="Keren">
  Voice display name. One of `Keren`, `Karmit`, `Kobi`, `Kfir`, `Dana`, `Dafna`, `Dorin`, `Dan`, `Dor`, `David`, `Sapir`, `Steve`.
</ParamField>

<ParamField body="welcome_message" type="string">
  Message the agent speaks first when it answers. When empty, the agent opens
  the conversation from the prompt.
</ParamField>

<ParamField body="variables_provided" type="array">
  Variables to supply at call time (via `vars_provided` on Dial).

  <Expandable title="Variable properties">
    <ParamField body="name" type="string" required>Variable name.</ParamField>
    <ParamField body="description" type="string">Human-readable description.</ParamField>
    <ParamField body="default" type="string">Default value if not supplied at call time.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="variables_extracted" type="array">
  Variables the agent should extract from the conversation after the call.

  <Expandable title="Variable properties">
    <ParamField body="name" type="string" required>Variable name.</ParamField>
    <ParamField body="description" type="string">Human-readable description.</ParamField>
    <ParamField body="required" type="boolean">Whether extraction is required.</ParamField>
  </Expandable>
</ParamField>

## Response

The created [Agent](/api-reference/models/agent) object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voicy.co/functions/v1/agent-create \
    -H "Authorization: Bearer voicy_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Appointment Booker",
      "language": "he",
      "prompt": "You are a friendly receptionist that books appointments.",
      "voice": "Keren",
      "welcome_message": "שלום, איך אפשר לעזור?",
      "variables_provided": [{ "name": "customer_name", "description": "The caller'\''s name" }],
      "variables_extracted": [{ "name": "appointment_date", "description": "The date the caller chose", "required": true }]
    }'
  ```

  ```javascript JavaScript theme={null}
  const agent = await (await fetch('https://api.voicy.co/functions/v1/agent-create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer voicy_sk_live_xxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Appointment Booker',
      language: 'he',
      prompt: 'You are a friendly receptionist that books appointments.',
      voice: 'Keren',
      welcome_message: 'שלום, איך אפשר לעזור?',
    }),
  })).json();
  ```

  ```python Python theme={null}
  import requests
  agent = requests.post(
      'https://api.voicy.co/functions/v1/agent-create',
      headers={'Authorization': 'Bearer voicy_sk_live_xxx'},
      json={
          'name': 'Appointment Booker',
          'language': 'he',
          'prompt': 'You are a friendly receptionist that books appointments.',
          'voice': 'Keren',
          'welcome_message': 'שלום, איך אפשר לעזור?',
      },
  ).json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Appointment Booker",
    "language": "he",
    "voice": "Keren",
    "agent_type": "singlePrompt",
    "active": true,
    "prompt": "You are a friendly receptionist that books appointments.",
    "welcome_message": "שלום, איך אפשר לעזור?",
    "variables_provided": [
      { "name": "customer_name", "description": "The caller's name" }
    ],
    "variables_extracted": [
      { "name": "appointment_date", "description": "The date the caller chose" }
    ],
    "created_at": "2026-06-06T10:00:00Z",
    "updated_at": "2026-06-06T10:00:00Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "status": "error",
    "message": "Invalid voice \"Bob\". Valid voices: Keren, Karmit, Kobi, Kfir, Dana, Dafna, Dorin, Dan, Dor, David, Sapir, Steve"
  }
  ```
</ResponseExample>