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

# Create Agent

> Create a new AI agent with custom configuration

## Overview

Creates a new AI agent that can handle phone calls, SMS messages, and chat conversations. Agents are fully customizable with their own personality, voice, and capabilities.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token — either a Supabase JWT or a `mgp_` API key.
</ParamField>

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

### Body Parameters

<ParamField body="name" type="string" required>
  Display name for the agent.

  **Example:** `"Reception Agent"`

  **Constraints:**

  * 1-100 characters
</ParamField>

<ParamField body="greeting" type="string">
  The message the agent says when answering a call.

  **Example:** `"Hello, thanks for calling Acme Corp. How can I help you today?"`

  **Constraints:**

  * Maximum 500 characters
  * Should be under 15 seconds when spoken
</ParamField>

<ParamField body="system_prompt" type="string">
  Instructions that define the agent's personality, knowledge, and behavior. This is the most important setting for customizing agent responses.

  **Example:**

  ```
  You are Sarah, a friendly receptionist for Acme Corp.

  Your responsibilities:
  - Answer questions about our services
  - Help callers schedule appointments
  - Take messages when needed

  Business hours: Monday-Friday, 9am-5pm
  Location: 123 Main St, Vancouver BC

  Always be professional and helpful.
  ```

  **Constraints:**

  * Maximum 10,000 characters
  * Supports markdown formatting
</ParamField>

<ParamField body="voice_id" type="string">
  ID of the voice to use for phone calls. Use the [List Voices](/api-reference/endpoints/list-voices) endpoint to get all available options, including any cloned voices on your account.

  **ElevenLabs voices:**

  | Voice ID               | Name    | Description                   |
  | ---------------------- | ------- | ----------------------------- |
  | `EXAVITQu4vr4xnSDxMaL` | Sarah   | Professional, American female |
  | `MF3mGyEYCl7XYWbV9V6O` | Elli    | Youthful, American female     |
  | `TxGEqnHWrfWFTfGW9XjX` | Josh    | Strong, American male         |
  | `pFZP5JQG7iQjIQuC4Bku` | Lily    | Confident, British female     |
  | `nPczCjzI2devNBz1zQrb` | Brian   | Classy, American male         |
  | `onwK4e9ZLuTAKqWW03F9` | Daniel  | Formal, British male          |
  | `cjVigY5qzO86Huf0OWal` | Eric    | Friendly, American male       |
  | `cgSgspJ2msm6clMCkdW9` | Jessica | Expressive, American female   |
  | `XrExE9yKIg1WjnnlVkGX` | Matilda | Upbeat, American female       |
  | `CwhRBWXzGAHq8TQ4Fs17` | Roger   | Classy, American male         |
  | `FGY2WhTYpPnrIDTdsKH5` | Laura   | Sassy, American female        |
  | `IKne3meq5aSn9XLyUdCD` | Charlie | Hyped, Australian male        |
  | `JBFqnCBsd6RMkjVDRZzb` | George  | Mature, British male          |
  | `N2lVS1w4EtoT3dr4eOWO` | Callum  | Husky, American male          |
  | `SAz9YHcvj6GT2YYXdXww` | River   | Calm, neutral American        |
  | `SOYHLrjzK2X1ezoPC6cr` | Harry   | Rough, American male          |
  | `TX3LPaxmHKxFdv7VOQHJ` | Liam    | Confident, American male      |
  | `Xb7hH8MSUJpSbSDYk0k2` | Alice   | Professional, British female  |
  | `bIHbv24MWmeRgasZH58o` | Will    | Chill, American male          |
  | `hpp4J3VqNfWAUOO0d1Us` | Bella   | Professional, American female |
  | `iP95p4xoKVk53GoZ742B` | Chris   | Casual, American male         |
  | `pNInz6obpgDQGcFmaJgB` | Adam    | Deep, American male           |
  | `pqHfZKP75CvOlQylNhV4` | Bill    | Trustworthy, American male    |

  **OpenAI voices** (prefix `openai-`):

  | Voice ID         | Name    | Description           |
  | ---------------- | ------- | --------------------- |
  | `openai-alloy`   | Alloy   | Neutral, professional |
  | `openai-echo`    | Echo    | Warm, friendly        |
  | `openai-fable`   | Fable   | Expressive, dynamic   |
  | `openai-nova`    | Nova    | Bright, energetic     |
  | `openai-onyx`    | Onyx    | Deep, authoritative   |
  | `openai-shimmer` | Shimmer | Soft, calm            |

  **Default:** `EXAVITQu4vr4xnSDxMaL` (Sarah)
</ParamField>

<ParamField body="llm_model" type="string">
  LLM model for conversations. Use the [List Models](/api-reference/endpoints/list-models) endpoint to get all available options.

  | Model ID      | Description                                               |
  | ------------- | --------------------------------------------------------- |
  | `gpt-4.1`     | Recommended — best balance of speed and quality (default) |
  | `gpt-4o-mini` | Fast and cost-effective                                   |
  | `gpt-4o`      | Most capable, higher latency                              |

  **Default:** `gpt-4.1`
</ParamField>

<ParamField body="language" type="string">
  Primary language for the agent.

  **Default:** `en-US`

  **Supported:** `en-US`, `en-GB`, `es-ES`, `fr-FR`, `de-DE`
</ParamField>

<ParamField body="agent_type" type="string">
  The channel type this agent handles.

  | Value            | Description                            |
  | ---------------- | -------------------------------------- |
  | `inbound_voice`  | Answers incoming phone calls (default) |
  | `outbound_voice` | Places outgoing phone calls            |
  | `text`           | Handles SMS conversations              |
  | `chat_widget`    | Handles web chat widget conversations  |
  | `whatsapp`       | Handles WhatsApp messages              |
  | `email`          | Handles email conversations            |

  **Default:** `inbound_voice`
</ParamField>

<ParamField body="organization_name" type="string">
  Name of the organization the agent represents.

  **Example:** `"Acme Corp"`
</ParamField>

<ParamField body="owner_name" type="string">
  Name of the agent's owner.

  **Example:** `"Jane Smith"`
</ParamField>

<ParamField body="agent_role" type="string">
  Description of the agent's role.

  **Example:** `"Front desk receptionist"`
</ParamField>

<ParamField body="transfer_phone_number" type="string">
  Phone number to transfer calls to when requested.

  **Example:** `"+14155551234"`
</ParamField>

<ParamField body="is_active" type="boolean">
  Whether the agent is active and can receive calls.

  **Default:** `true`
</ParamField>

<ParamField body="temperature" type="number">
  LLM temperature for response creativity.

  **Default:** `0.7`

  **Range:** 0 to 1
</ParamField>

<ParamField body="functions" type="object">
  Configuration for agent functions (capabilities) the agent can use during calls.

  ### end\_call

  | Property      | Type    | Description                                                                                          |
  | ------------- | ------- | ---------------------------------------------------------------------------------------------------- |
  | `enabled`     | boolean | Allow agent to hang up when conversation is complete. Default: `true`                                |
  | `description` | string  | When to end calls. Default: "End the call when the conversation is complete or caller says goodbye." |

  ### transfer

  | Property      | Type    | Description                                                   |
  | ------------- | ------- | ------------------------------------------------------------- |
  | `enabled`     | boolean | Allow agent to transfer calls. Default: `false`               |
  | `numbers`     | array   | Transfer destinations. Each: `{ number, label, description }` |
  | `description` | string  | General instruction for transfer behavior                     |

  **Transfer number format:**

  ```json theme={null}
  {
    "number": "+14155551234",
    "label": "Sales",
    "description": "Transfer for sales inquiries"
  }
  ```

  ### sms

  | Property      | Type    | Description                                        |
  | ------------- | ------- | -------------------------------------------------- |
  | `enabled`     | boolean | Allow agent to send SMS messages. Default: `false` |
  | `description` | string  | When to send SMS                                   |
  | `templates`   | array   | Pre-defined message templates                      |

  ### extract\_data

  | Property      | Type    | Description                                                  |
  | ------------- | ------- | ------------------------------------------------------------ |
  | `enabled`     | boolean | Extract structured data from conversations. Default: `false` |
  | `schema`      | object  | JSON schema defining fields to extract                       |
  | `description` | string  | What data to collect                                         |

  ### booking

  | Property           | Type    | Description                                        |
  | ------------------ | ------- | -------------------------------------------------- |
  | `enabled`          | boolean | Allow agent to book appointments. Default: `false` |
  | `calendar_id`      | string  | Connected calendar ID                              |
  | `description`      | string  | Booking behavior instruction                       |
  | `get_availability` | object  | `{ enabled, description }` for availability checks |

  **Example:**

  ```json theme={null}
  {
    "end_call": {
      "enabled": true,
      "description": "End the call when the customer confirms their order or says goodbye."
    },
    "transfer": {
      "enabled": true,
      "numbers": [
        { "number": "+14155551234", "label": "Sales", "description": "Transfer for sales inquiries" },
        { "number": "+14155555678", "label": "Support", "description": "Transfer for technical issues" }
      ],
      "description": "Transfer when caller requests to speak with a specific department."
    },
    "sms": {
      "enabled": true,
      "description": "Send order confirmation via SMS after completing an order."
    }
  }
  ```
</ParamField>

<ParamField body="dynamic_variables" type="array">
  Dynamic variables for extracting structured data from conversations. These are stored separately from the agent config and define what information the AI should capture during calls.

  Each variable object:

  * `name` (string, required) — Variable name (e.g., `caller_name`)
  * `description` (string) — What to extract
  * `var_type` (string) — `text` (default), `number`, `boolean`, or `enum`
  * `enum_options` (array) — Required when `var_type` is `enum`

  ```json theme={null}
  [
    {"name": "caller_name", "description": "Full name of the caller", "var_type": "text"},
    {"name": "caller_email", "description": "Email address", "var_type": "text"},
    {"name": "priority", "description": "Call priority level", "var_type": "enum", "enum_options": ["low", "medium", "high"]}
  ]
  ```

  You can also manage dynamic variables independently via the [Dynamic Variables API](/api-reference/endpoints/create-dynamic-variable).
</ParamField>

## Response

Returns the full agent object wrapped in an `agent` key.

<ResponseField name="agent" type="object">
  <Expandable title="Agent object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the agent config row.
    </ResponseField>

    <ResponseField name="name" type="string">
      Agent display name.
    </ResponseField>

    <ResponseField name="greeting" type="string">
      Call greeting message.
    </ResponseField>

    <ResponseField name="system_prompt" type="string">
      Agent instructions.
    </ResponseField>

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

    <ResponseField name="is_active" type="boolean">
      Active status.
    </ResponseField>

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

    <ResponseField name="updated_at" type="string">
      ISO 8601 last update timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.magpipe.ai/functions/v1/create-agent" \
    -H "Authorization: Bearer mgp_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Reception Agent",
      "greeting": "Hello, thanks for calling! How can I help you today?",
      "system_prompt": "You are a friendly receptionist. Be helpful and professional.",
      "voice_id": "EXAVITQu4vr4xnSDxMaL"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.magpipe.ai/functions/v1/create-agent', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mgp_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Reception Agent',
      greeting: 'Hello, thanks for calling! How can I help you today?',
      system_prompt: 'You are a friendly receptionist. Be helpful and professional.',
      voice_id: 'EXAVITQu4vr4xnSDxMaL',
    }),
  });

  const data = await response.json();
  console.log(data.agent);
  ```

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

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/create-agent',
      headers={
          'Authorization': 'Bearer mgp_your_api_key',
          'Content-Type': 'application/json',
      },
      json={
          'name': 'Reception Agent',
          'greeting': 'Hello, thanks for calling! How can I help you today?',
          'system_prompt': 'You are a friendly receptionist. Be helpful and professional.',
          'voice_id': 'EXAVITQu4vr4xnSDxMaL',
      },
  )

  print(response.json()['agent'])
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "agent": {
    "id": "c72ea2b8-1234-5678-9abc-def012345678",
    "name": "Reception Agent",
    "greeting": "Hello, thanks for calling! How can I help you today?",
    "system_prompt": "You are a friendly receptionist. Be helpful and professional.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "llm_model": "gpt-4.1",
    "language": "en-US",
    "is_active": true,
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z",
    "dynamic_variables": []
  }
}
```

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": {
      "code": "missing_param",
      "message": "name is required"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  }
  ```
</ResponseExample>

## Related Endpoints

* [List Agents](/api-reference/endpoints/list-agents) - Get all agents
* [Get Agent](/api-reference/endpoints/get-agent) - Get agent details
* [Update Agent](/api-reference/endpoints/update-agent) - Modify an agent
* [Delete Agent](/api-reference/endpoints/delete-agent) - Remove an agent