Skip to main content
POST
/
functions
/
v1
/
create-agent
Create Agent
curl --request POST \
  --url https://api.magpipe.ai/functions/v1/create-agent \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "greeting": "<string>",
  "system_prompt": "<string>",
  "voice_id": "<string>",
  "llm_model": "<string>",
  "language": "<string>",
  "agent_type": "<string>",
  "organization_name": "<string>",
  "owner_name": "<string>",
  "agent_role": "<string>",
  "transfer_phone_number": "<string>",
  "is_active": true,
  "temperature": 123,
  "functions": {},
  "dynamic_variables": [
    {}
  ]
}
'
{
  "error": {
    "code": "missing_param",
    "message": "name is required"
  }
}

​
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

​
Authorization
string
required
Bearer token — either a Supabase JWT or a mgp_ API key.
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
name
string
required
Display name for the agent.Example: "Reception Agent"Constraints:
  • 1-100 characters
​
greeting
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
​
system_prompt
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
​
voice_id
string
ID of the voice to use for phone calls. Use the List Voices endpoint to get all available options, including any cloned voices on your account.ElevenLabs voices:
Voice IDNameDescription
EXAVITQu4vr4xnSDxMaLSarahProfessional, American female
MF3mGyEYCl7XYWbV9V6OElliYouthful, American female
TxGEqnHWrfWFTfGW9XjXJoshStrong, American male
pFZP5JQG7iQjIQuC4BkuLilyConfident, British female
nPczCjzI2devNBz1zQrbBrianClassy, American male
onwK4e9ZLuTAKqWW03F9DanielFormal, British male
cjVigY5qzO86Huf0OWalEricFriendly, American male
cgSgspJ2msm6clMCkdW9JessicaExpressive, American female
XrExE9yKIg1WjnnlVkGXMatildaUpbeat, American female
CwhRBWXzGAHq8TQ4Fs17RogerClassy, American male
FGY2WhTYpPnrIDTdsKH5LauraSassy, American female
IKne3meq5aSn9XLyUdCDCharlieHyped, Australian male
JBFqnCBsd6RMkjVDRZzbGeorgeMature, British male
N2lVS1w4EtoT3dr4eOWOCallumHusky, American male
SAz9YHcvj6GT2YYXdXwwRiverCalm, neutral American
SOYHLrjzK2X1ezoPC6crHarryRough, American male
TX3LPaxmHKxFdv7VOQHJLiamConfident, American male
Xb7hH8MSUJpSbSDYk0k2AliceProfessional, British female
bIHbv24MWmeRgasZH58oWillChill, American male
hpp4J3VqNfWAUOO0d1UsBellaProfessional, American female
iP95p4xoKVk53GoZ742BChrisCasual, American male
pNInz6obpgDQGcFmaJgBAdamDeep, American male
pqHfZKP75CvOlQylNhV4BillTrustworthy, American male
OpenAI voices (prefix openai-):
Voice IDNameDescription
openai-alloyAlloyNeutral, professional
openai-echoEchoWarm, friendly
openai-fableFableExpressive, dynamic
openai-novaNovaBright, energetic
openai-onyxOnyxDeep, authoritative
openai-shimmerShimmerSoft, calm
Default: EXAVITQu4vr4xnSDxMaL (Sarah)
​
llm_model
string
LLM model for conversations. Use the List Models endpoint to get all available options.
Model IDDescription
gpt-4.1Recommended — best balance of speed and quality (default)
gpt-4o-miniFast and cost-effective
gpt-4oMost capable, higher latency
Default: gpt-4.1
​
language
string
Primary language for the agent.Default: en-USSupported: en-US, en-GB, es-ES, fr-FR, de-DE
​
agent_type
string
The channel type this agent handles.
ValueDescription
inbound_voiceAnswers incoming phone calls (default)
outbound_voicePlaces outgoing phone calls
textHandles SMS conversations
chat_widgetHandles web chat widget conversations
whatsappHandles WhatsApp messages
emailHandles email conversations
Default: inbound_voice
​
organization_name
string
Name of the organization the agent represents.Example: "Acme Corp"
​
owner_name
string
Name of the agent’s owner.Example: "Jane Smith"
​
agent_role
string
Description of the agent’s role.Example: "Front desk receptionist"
​
transfer_phone_number
string
Phone number to transfer calls to when requested.Example: "+14155551234"
​
is_active
boolean
Whether the agent is active and can receive calls.Default: true
​
temperature
number
LLM temperature for response creativity.Default: 0.7Range: 0 to 1
​
functions
object
Configuration for agent functions (capabilities) the agent can use during calls.

​
end_call

PropertyTypeDescription
enabledbooleanAllow agent to hang up when conversation is complete. Default: true
descriptionstringWhen to end calls. Default: “End the call when the conversation is complete or caller says goodbye.”

​
transfer

PropertyTypeDescription
enabledbooleanAllow agent to transfer calls. Default: false
numbersarrayTransfer destinations. Each: { number, label, description }
descriptionstringGeneral instruction for transfer behavior
Transfer number format:
{
  "number": "+14155551234",
  "label": "Sales",
  "description": "Transfer for sales inquiries"
}

​
sms

PropertyTypeDescription
enabledbooleanAllow agent to send SMS messages. Default: false
descriptionstringWhen to send SMS
templatesarrayPre-defined message templates

​
extract_data

PropertyTypeDescription
enabledbooleanExtract structured data from conversations. Default: false
schemaobjectJSON schema defining fields to extract
descriptionstringWhat data to collect

​
booking

PropertyTypeDescription
enabledbooleanAllow agent to book appointments. Default: false
calendar_idstringConnected calendar ID
descriptionstringBooking behavior instruction
get_availabilityobject{ enabled, description } for availability checks
Example:
{
  "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."
  }
}
​
dynamic_variables
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
[
  {"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.

​
Response

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

​
Example Request

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"
  }'

​
Example Response

{
  "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

{
  "error": {
    "code": "missing_param",
    "message": "name is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}