Skip to main content

​
Agent Builder

The Agent Builder service lets you create a fully configured AI voice agent from just a website URL, custom instructions, or both. It uses AI to analyze your website content and automatically generate a production-ready agent with personality, goals, guardrails, and tone — ready to handle calls. The process is asynchronous: you submit a job, then poll for the result.

​
Create Agent Builder Job

Submit an async job that analyzes a website and/or follows your instructions to generate a complete AI voice agent. 
POST /agent-builder

​
Request Body

FieldTypeRequiredDescription
website_urlstringNo*The website URL to analyze (e.g., https://example.com). Used to extract business info automatically
instructionsstringNo*Custom instructions to guide agent generation (e.g., “Focus on customer support for our SaaS product”)
* At least one of website_url or instructions must be provided.

​
Example Requests

With website URL only: 
{
  "website_url": "https://example.com"
}
With instructions only: 
{
  "instructions": "Create a customer support agent for a dental clinic. The agent should be warm, professional, and help callers book appointments, ask about services, and get directions."
}
With both: 
{
  "website_url": "https://example.com",
  "instructions": "Focus on customer support for our SaaS product. Emphasize our free trial offer."
}

​
Response

{
  "status": 201,
  "message": "Agent builder job created",
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued"
  }
}

​
Error Responses

StatusDescription
400Neither website_url nor instructions provided, or invalid URL
401Invalid or missing API key
429Rate limit exceeded (max 50 jobs per workspace per day)

​
Get Agent Builder Job Status

Poll the status of an agent builder job. When the status is completed, the response includes the agent_id of the newly created agent. 
GET /agent-builder/{job_id}

​
Parameters

ParameterTypeRequiredDescription
job_idstringYesThe agent builder job ID

​
Response — Processing

{
  "status": 200,
  "message": "Agent builder job status",
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing",
    "website_url": "https://example.com",
    "created_at": "2026-03-19T10:00:00.000Z"
  }
}

​
Response — Completed

{
  "status": 200,
  "message": "Agent builder job status",
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "agent_id": "e5f6g7h8-i9j0-1234-klmn-op5678901234",
    "website_url": "https://example.com",
    "created_at": "2026-03-19T10:00:00.000Z"
  }
}

​
Response — Failed

{
  "status": 200,
  "message": "Agent builder job status",
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "failed",
    "error": "Failed to analyze website",
    "website_url": "https://example.com",
    "created_at": "2026-03-19T10:00:00.000Z"
  }
}

​
Job Statuses

StatusDescription
queuedJob is in the queue waiting to be processed
processingJob is actively analyzing the website and generating the agent
completedAgent has been created successfully — agent_id is in the response
failedSomething went wrong — check the error field for details

​
Error Responses

StatusDescription
401Invalid or missing API key
404Job not found

​
How It Works

  1. Submit a website URL and/or instructions via POST /agent-builder.
  2. The service discovers relevant pages from your website (sitemap, robots.txt, or common paths).
  3. An AI model analyzes your website content and generates a complete agent configuration including personality, goals, guardrails, tone, and greeting.
  4. A new agent is created in your workspace, ready to receive calls.
  5. Poll GET /agent-builder/{job_id} until status is completed, then use the agent_id to assign phone numbers, start campaigns, or test calls.

​
What Gets Generated

The agent builder automatically configures:
  • Name — Derived from your website domain (e.g., acme-corp.com) or generated from instructions
  • Personality — How the agent presents itself, based on your brand voice
  • Goals — Conversation flow and objectives
  • Guardrails — Safety rules including never fabricating information
  • Tone — Communication style matched to your brand (Professional, Friendly, Casual, or Formal)
  • Greeting — A natural opening phrase that includes your company name
  • Voice — Set to the platform default voice

​
Rate Limits

Each workspace is limited to 50 agent builder jobs per day.