What Knova agents are
Knova is Knotie AI Pro’s native agent type. Unlike Retell or VAPI agents, Knova agents run entirely within the platform — no third-party API key is required. They support inbound and outbound phone calls, a configurable system prompt, knowledge bases, and custom tools.
Use Knova agents when:
- You want the fastest onboarding (no external provider setup)
- You are on the Free Forever plan (Knova agents are included)
- You want AI-assisted agent creation via the built-in Agent Builder Chat
Create a Knova agent
The Create Agent modal is a 5-tab sequential flow, not a flat Basic form. Each tab gates the next:
- Customer – Pick the customer this agent belongs to.
- Setup Mode – Choose AI Builder (chat-driven, recommended) or Manual (fill fields yourself). If you pick Manual, the AI Builder tab is hidden for the rest of the flow.
- Basic – Agent name, system prompt, greeting, voice (see Voice selection below). The Basic tab is replaced by the AI Builder chat panel if you chose AI Builder on the Setup Mode tab.
- Advanced – Tools, knowledge base, advanced config.
- Functions – Function calls / tool wiring.
To open the modal:
- In the Partner Portal, open AI Agents → Knova Agents.
- Click Create Agent (top right).
- Walk through tabs 1–5 in order; click Save on the Functions tab to create the agent.
The Build with AI button (top of the Knova agents page) also opens the modal, defaulting to the AI Builder chat on the Basic tab.
System prompt guidelines
The system prompt is the core of your agent’s behavior. It defines personality, scope, and rules.
Limits:
| Field | Maximum |
|---|
| System prompt length | 15,000 characters |
- Start with the agent’s role: “You are a friendly receptionist for Acme Plumbing…”
- Include what it should and should not do
- Specify how to handle transfers and escalations
- Use the AI Builder Chat to generate a first draft from your business context (see AI Agent Builder Chat)
Voice selection
Knova agents use one of two text-to-speech banks:
| Bank | Indicator |
|---|
| First TTS bank | Blue dot next to the voice name |
| Second TTS bank | Purple dot next to the voice name |
Resumable builder sessions
When you use the AI Agent Builder Chat to create an agent, the conversation is saved automatically as a Builder Session. You can resume the conversation later:
- Open an existing Knova agent in the Partner Portal.
- Click the AI Builder button (chat icon in the agent modal).
- The modal shows a list of recent builder sessions for this agent. Click a session card to resume from where you left off.
Each session card displays:
- The first message you sent (as a conversation preview)
- The model used
- The time of the last turn
- The current stage (
conversing, proposed, or applied)
Sessions from previous conversations are loaded when you open the Agent Builder — you do not need to start fresh every time.
Assign a phone number
After creating a Knova agent and assigning it to a customer (see Customer assignment in the knova-agent.mdx overview, or the kebab Assign Customer to Agent action), phone-number assignment is done in the customer’s own agent edit view — not in the Knova agent modal.
- Open the assigned customer’s record.
- Edit the agent from the customer’s Manage Agents view.
- Pick a provisioned number from the customer’s pool and click Assign.
The Knova agent modal itself does not have an “Assign Phone Number” step — that flow was removed in 2026. Phone numbers are bound to the customer + agent pair, not to the Knova agent alone.
Builder sessions API
The builder session history is accessible via the partner API for integrations:
List sessions for a customer
GET /api/partner/knova-agents/builder-sessions?customerId={customerId}
agentId — filter to sessions that produced a specific agent.
Response:
{
"sessions": [
{
"id": "session_cuid",
"currentStage": "applied",
"messageCount": 12,
"firstUserMessage": "Create a receptionist for an HVAC company...",
"resultingAgentId": "agent_abc123",
"createdAt": "2026-05-26T02:00:00.000Z",
"lastTurnAt": "2026-05-26T02:08:00.000Z"
}
]
}
currentStage | Meaning |
|---|
conversing | The conversation is in progress |
proposed | The AI has drafted an agent config; partner reviewing |
applied | The partner clicked “Apply” and saved the agent |
abandoned | Session closed without applying |
Fetch a single session
GET /api/partner/knova-agents/builder-sessions/{sessionId}
Telephony credit settings API
Partners can now read telephony credit settings via API in addition to writing them:
GET /api/partner/telephony-credits/settings
{
"success": true,
"data": {
"lowCreditThresholdCents": 1000,
"lowCreditThresholdDollars": 10.0,
"lowCreditNotificationsEnabled": true,
"autoTopUpEnabled": false,
"autoTopUpThresholdCents": 500,
"autoTopUpThresholdDollars": 5.0,
"autoTopUpAmountCents": 5000,
"autoTopUpAmountDollars": 50.0
}
}
POST /api/partner/telephony-credits/settings to update these values (see Telephony Credits for UI instructions).
If you use Knotie’s MCP server with AI coding tools like Cursor or Claude, note these updated tool schemas:
agents_create — field names updated:
| Old field | New field | Notes |
|---|
name | agentName | Agent display name |
config (nested object) | Top-level fields | systemPrompt, voiceId, voiceProvider, modelProvider, etc. |
invoices_create / invoices_update — field names updated:
| Old field | New field | Notes |
|---|
items (array) | title, amount | amount is in cents (min 50) |
notes | description | — |
invoices_recurring_create — field names updated: interval → recurringInterval; items → title, amount (in dollars for this route).
metered_plans_create — schema overhauled: unit/pricePerUnitCents replaced with metricType, metricName, pricingModel, pricingTiers (array), and billingCycle.
customer_credits_balance — now returns balance + recent transactions (additional data in the same call).
If you have existing MCP automations using these tools, update your prompts and tool calls to use the new field names.
Troubleshooting
- System prompt exceeds character limit — Split overly broad scopes into a multi-agent workflow. Each persona or use case should have its own agent.
- Voice not loading — Reload the page. If voices still don’t appear, check your internet connection and try a different browser.
- Builder session not resuming — Sessions are listed by
lastTurnAt (most recent first). If you don’t see a session, it may have been created for a different customer or on a different account.
- Agent config not updating after edit — The platform refreshes the agent’s live configuration after every save. If the agent’s phone number still uses the old settings, wait 30 seconds and call the number again. If it persists, contact support.
Related pages
