Manage Knova agents

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

Knova Create Agent modal — Tab 1 (Customer) selected, showing 5-tab sequential flow (Customer, Setup Mode, Basic, Advanced, Functions) and a customer list with 3 example customers. Tabs gate the next one.

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

If your use case is very broad, consider splitting it into multiple agents rather than one large prompt — each agent handles a focused scope, which improves response quality and makes prompts easier to maintain. Tips:

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

Note: You pick the voice, not the provider behind it. Your existing agent voice settings are preserved when the platform upgrades its underlying voice models. The platform periodically upgrades its default voices for better quality and broader language coverage. These upgrades don’t change the voice catalog — Ashley, Edward, Olivia, and other named voices continue to work exactly as before.

Knova Edit Agent modal — Basic tab Voice section with a search box and voice list (Abby Female, Alex Male, Anjali Female) each with a coloured dot indicator and a play preview button. First TTS bank voices have blue dots; second TTS bank voices have purple dots.

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.

Inbound calls to that number will now be handled by this agent.

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}

Optional query parameter: 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"
    }
  ]
}

Session stages:

`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}

Returns the full message history and draft proposal for that session.

Telephony credit settings API

Partners can now read telephony credit settings via API in addition to writing them:

GET /api/partner/telephony-credits/settings

Response:

{
  "success": true,
  "data": {
    "lowCreditThresholdCents": 1000,
    "lowCreditThresholdDollars": 10.0,
    "lowCreditNotificationsEnabled": true,
    "autoTopUpEnabled": false,
    "autoTopUpThresholdCents": 500,
    "autoTopUpThresholdDollars": 5.0,
    "autoTopUpAmountCents": 5000,
    "autoTopUpAmountDollars": 50.0
  }
}

Use POST /api/partner/telephony-credits/settings to update these values (see Telephony Credits for UI instructions).

MCP tool changes

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.

AI Agent Builder Chat – How to use the AI-powered chat builder
Telephony Credits – Manage credits for phone calls
MCP Tokens – Set up MCP access for AI coding tools
Agent Analytics – View call and usage statistics

Getting started

Account & security

Customer onboarding

Customer portal features

Partner Portal

Customer Management

AI Agents & Analytics

AI Gateway & Experiences

Credits, Billing & Telephony

AI Memory & Knowledge

Platform Settings

Team & Growth

App Marketplace

Nexus & VPS

Knova Agent

Third-Party Agents

n8n Automation

Agent Tools & Setup

What Knova agents are

Create a Knova agent

System prompt guidelines

Voice selection

Resumable builder sessions

Assign a phone number

Builder sessions API

List sessions for a customer

Fetch a single session

Telephony credit settings API

MCP tool changes

Troubleshooting

​What Knova agents are

​Create a Knova agent

​System prompt guidelines

​Voice selection

​Resumable builder sessions

​Assign a phone number

​Builder sessions API

​List sessions for a customer

​Fetch a single session

​Telephony credit settings API

​MCP tool changes

​Troubleshooting

​Related pages

What Knova agents are

Create a Knova agent

System prompt guidelines

Voice selection

Resumable builder sessions

Assign a phone number

Builder sessions API

List sessions for a customer

Fetch a single session

Telephony credit settings API

MCP tool changes

Troubleshooting

Related pages