> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotie-ai.pro/llms.txt
> Use this file to discover all available pages before exploring further.
# Knova AI Agent Builder
> Build voice and chat agents through a conversational interface. Paste a URL, describe your business, and the builder drafts a fully configured agent.
## What is the Knova AI Agent Builder?
The Knova AI Agent Builder is a conversational interface that lets partners and customers create a configured Knova voice or chat agent through natural language — no manual form-filling required. You describe the business, paste a website URL, or explain the use case, and the builder proposes an agent with a system prompt, voice, tools, and configuration already filled in.
Use the builder when you want to:
* Spin up an agent quickly from a business description
* Draft a system prompt from a live website (paste a URL)
* Configure multi-agent routing (triage + specialists)
* Iterate on a draft in plain English instead of editing fields
***
## Opening the builder
The **Create Agent** modal for Knova is a **5-tab sequential flow**, not a single Basic form:
1. **Customer** — pick the customer this agent belongs to.
2. **Setup Mode** — choose **AI Builder** (chat-driven) or **Manual** (fill fields yourself). If you pick Manual, the AI Builder tab is hidden for the rest of the flow.
3. **Basic** — agent name, system prompt, greeting, voice (only reached after you choose a Setup Mode).
4. **Advanced** — tools, knowledge base, advanced config.
5. **Functions** — function calls / tool wiring.
To open it:
1. In the Partner Portal, navigate to **AI Agents** (or open a customer record and click **Manage Agents**).
2. Click **+ Create Agent** (top right).
3. Walk through tabs 1–5 in order; each tab gates the next.
If you picked **AI Builder** on the Setup Mode tab, the Basic tab is replaced by a chat panel — describe the business and the builder drafts the system prompt, voice, and config. Click **Apply to form** to load the draft into the standard Basic tab for final tweaks.
***
## Building an agent
### Basic flow
1. **Describe the business or use case.** For example:
> *An inbound receptionist that books cleanings on Calendly and texts confirmations.*
2. **Paste a URL if you have one.** When the builder detects a URL in your message it will read the page automatically and use it to populate the agent.
> *Or paste your business URL and I'll read it.*
3. **Review the draft.** The builder streams its reasoning, then presents a proposed agent configuration.
4. **Refine or accept.** Ask for changes in plain English, or click **Accept** to save the agent.
### What's in the proposal
The builder produces a complete agent configuration with:
* Agent name and type (inbound, outbound, web, or multi-agent)
* Communication channel (phone or web)
* Agent mode (essential, moderate, or premium)
* System prompt and greeting message
* Function calls (tool integrations)
* Multi-agent personas and routing (if applicable)
Review the proposal in the chat. Give feedback if you want changes — the builder will revise and re-propose. When you are satisfied, click **Apply to form**. The proposal is loaded into the standard agent creation form, where you can make final tweaks before saving.
***
## Autonomous web access — no toggle required
The builder can read web pages and run searches on its own, without any partner-facing toggle. (Earlier "Web search" / "Keep Web search on" toggles have been removed.)
| Situation | What the builder does |
| ----------------------------------------------------- | ------------------------------------------------------------ |
| You paste a URL in your message | Reads the page content before proposing the agent |
| You name a website ("their site is ipswich.plumbing") | Reads the site at the URL it infers |
| The business profile already has a website on file | Reads it to pull current hours, services, and pricing detail |
| No URL is in scope and the builder needs to find one | Runs a web search to find the right page |
### URL detection indicator
When the builder detects a URL in your input field, a teal badge appears above the text area:
> **URL detected — the builder will read it**
This is informational only — no action is required. The builder will fetch the page as part of its reasoning.
### What happens when a fetch fails?
If a site blocks the crawler, returns a 4xx error, or times out, the builder:
* Acknowledges the failure briefly in its response
* Asks you to paste the relevant text in plain English
* Continues building the best draft it can without blocking
You do not need to retry or toggle anything.
***
## Progress indicators
While the builder is working, phase labels appear above the chat to show what it is doing:
| Phase label | What it means |
| ------------------------------------ | -------------------------------------------------- |
| *Reading your request* | Parsing your message |
| *Fetching the web page* | Loading a URL you provided or the business website |
| *Searching the web* | Running a web search to find a URL |
| *Reading your business profile* | Loading business context from the customer record |
| *Understanding the app integrations* | Inspecting available tool integrations |
| *Drafting the agent* | Composing the system prompt and configuration |
***
## Multi-agent configurations
The builder supports creating multi-agent setups where a routing agent hands off to specialised persona agents (e.g. sales, support, billing).
### Routing modes
| Mode | Description |
| ------------------- | ---------------------------------------------------------------------------------- |
| `triage_specialist` | A triage persona routes to one of several specialists based on the caller's intent |
| `linear` | Personas hand off in a fixed sequence |
| `freeform` | Each persona decides whether to hand off |
### Requirements for multi-agent proposals
* At least **2 personas** defined
* A **routing** setup with a valid mode
* An **entry persona** that takes the first turn
* Every persona named in the routing must exist in the persona list
When editing an existing multi-agent setup:
* All personas are loaded correctly into the builder
* The entry (routing) persona is preserved
* The builder can update individual personas or the routing logic
***
## AI Analytics gate
Knova agents support **AI Analytics** (call metrics and insights). The Partner Portal reflects your account's AI Analytics status:
* **Enabled**: you can configure and save metrics for any Knova agent.
* **Disabled**: the Configure Metrics modal shows a warning banner and the **Add / Save** buttons are disabled, so you know the settings won't take effect until AI Analytics is turned on at the partner level.
***
## Saving behaviour
* While the agent is being saved (the save operation is in flight), closing the modal does **not** trigger an "unsaved changes" confirmation. The save will complete normally.
* If you attempt to close the modal before saving, a confirmation dialog asks whether you want to discard your changes.
* Once the save completes, the modal closes automatically.
***
## Customer assignment after building
After the builder creates an agent, you map it to a customer from the agent's three-dot menu using **Assign Customer to Agent** (not a step inside the agent modal itself). The kebab entry opens a modal with a **Customer** dropdown and a **Profit Multiplier** field — no phone-number selection happens here.
Phone-number assignment is a separate step that happens later in the agent's edit flow **under the assigned customer** (not in the Knova agent modal).
When a phone number is assigned to a Knova agent, the phone numbers listing now correctly shows the associated customer — the number will no longer appear as "Unassigned" after the assignment is saved (the `PhoneNumber.customerId` is backfilled if it was previously unset).
***
## Builder reliability
* Simple single-agent builds typically complete in under 30 seconds.
* Complex multi-agent builds may take 60–90 seconds.
* If the builder appears stuck for more than 2 minutes, close the modal and try again.
### Proposal validation
Every proposal is checked before being presented:
| Rule | Detail |
| -------------------------- | ------------------------------------------------------- |
| System prompt length | Max 15,000 characters per persona |
| Multi-agent: persona count | Minimum 2 personas |
| Multi-agent: routing | Must include a valid routing setup and an entry persona |
| Persona references | Every persona named in the routing must exist |
If a proposal doesn't meet a rule, the builder corrects itself on the next turn rather than showing you an error.
***
## Troubleshooting
**Builder chat shows a spinner for a long time**
The builder is working through a multi-step turn. Wait up to 2 minutes before closing.
**Builder times out before finishing**
Complex multi-agent builds take longer. If you hit repeated timeouts, split the request into smaller steps — build one persona at a time for multi-agent setups.
**Input field has no cursor when the modal opens**
This has been fixed. The input now focuses automatically even when the builder is opened from inside another modal. If you still see this, make sure your browser is up to date.
**Fetch fails on every URL I paste**
Some sites block automated readers by design. Paste the relevant text from the page directly into the chat and the builder will use it.
**"No personas yet" when editing an existing multi-agent**
This has been fixed. Re-open the agent in the builder to reload the persona list.
**Applied proposal but form fields are empty**
Click **Apply to form** in the builder chat — the proposal does not populate the form automatically.
***
## Related pages
* [AI Agent Builder Chat](/agents/knova/agent-builder-chat) — Chat UX, session resume, rate limits, and the "Re-checked context" noise-reduction pill
* [Manage Knova agents](/agents/knova/manage-knova-agents) — Create, configure, and edit Knova agents
* [Knova AI Receptionist agent](/agents/knova/knova-agent) — How the agent runs in production (routing, tools, credits)
* [MCP Tokens](/partner-portal/ai-agents/mcp/tokens) — Manage agents programmatically via MCP