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

# Agent builder

# 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.

```http theme={null}
POST /agent-builder
```

### Request Body

| Field        | Type   | Required | Description                                                                                            |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| website\_url | string | No\*     | The website URL to analyze (e.g., `https://example.com`). Used to extract business info automatically  |
| instructions | string | No\*     | 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:**

```json theme={null}
{
  "website_url": "https://example.com"
}
```

**With instructions only:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "website_url": "https://example.com",
  "instructions": "Focus on customer support for our SaaS product. Emphasize our free trial offer."
}
```

### Response

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

### Error Responses

| Status | Description                                                       |
| ------ | ----------------------------------------------------------------- |
| 400    | Neither `website_url` nor `instructions` provided, or invalid URL |
| 401    | Invalid or missing API key                                        |
| 429    | Rate 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.

```http theme={null}
GET /agent-builder/{job_id}
```

### Parameters

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| job\_id   | string | Yes      | The agent builder job ID |

### Response — Processing

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

| Status     | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| queued     | Job is in the queue waiting to be processed                         |
| processing | Job is actively analyzing the website and generating the agent      |
| completed  | Agent has been created successfully — `agent_id` is in the response |
| failed     | Something went wrong — check the `error` field for details          |

### Error Responses

| Status | Description                |
| ------ | -------------------------- |
| 401    | Invalid or missing API key |
| 404    | Job 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**.