Customizing Kapa
Kapa is tuned to answer technical questions. Its default style and behavior reflect what our customers, spanning various technical industries like developer tools, networking, and semiconductors, agree on as important. This includes staying defensive, surfacing uncertainty when the knowledge sources do not fully cover a question, and sticking closely to the indexed documentation rather than speculating beyond it.
Kapa works well across most use cases. Individual products and audiences, however, still benefit from small adjustments to tone, scope, or behavior at the edges. Customizations are how you shape those adjustments without changing the underlying behavior that keeps Kapa reliable.
What you can customize
Kapa lets you customize its behavior by altering and extending the system instructions that govern every answer it gives during a conversation. These instructions have three layers:
- Fixed harness. Core behavior that keeps the assistant reliable. This includes CommonMark formatting, inline citation format, prompt injection protection, and uncertainty reporting when the knowledge sources do not sufficiently cover a question. You cannot change these.
- Editable sections. Predefined sections of the system instructions where Kapa already uses a default that you can overwrite with your own instruction. When you set one, it replaces the default. When you leave it unchanged, the default is used.
- Custom instructions. Free-form items you add to specific sections of the system instructions. These are additive: they do not replace anything, they extend the instructions the assistant follows.
Editable sections and custom instructions are grouped under three headings: General, Style & Tone, and Guardrails & Boundaries.
General
The General section contains the assistant's identity.
| Field | Default | What it does |
|---|---|---|
| Assistant name | kapa.ai | The name the assistant uses to refer to itself. |
Style & Tone
Style & Tone controls how the assistant communicates: its personality, verbosity, formatting, and any persona-level behavior.
| Field | Default | What it does |
|---|---|---|
| Response style | Short, focused, and professional. | Defines the overall writing style. |
| Language | Respond in the same language as the question. Default: English. | Controls language detection and response behavior. |
You can also add further custom instructions to this section. Each instruction has a name and a description. Examples include:
- Tuning verbosity (concise for documentation, more conversational elsewhere)
- Adopting a friendlier, more human tone
- Ending answers with a follow-up question when it helps
- Defining how the assistant refers to your knowledge sources (e.g., "[Company] Documentation")
Guardrails & Boundaries
Guardrails & Boundaries controls what the assistant does and doesn't do, particularly at the edges of its knowledge.
This section has no predefined fields. You add further custom instructions only. Examples include:
- Whether the assistant should suggest contacting support when it cannot answer
- Whether it should include a call to action (e.g. prompting users to leave an email)
- Topics the assistant should refuse to answer
Setup
- Go to the Customizations page in your project on app.kapa.ai.
- Click New customization.
- Give it a name (e.g. "Marketing site", "Developer docs") and optionally a description.
- Select a chat model version (see below).
- Configure the sections:
- Edit the editable sections (assistant name, response style, language) if you want to override the defaults. Fields show a "Default" or "Custom" badge to indicate their state. You can revert any field to its default.
- Add further custom instructions under Style & Tone or Guardrails & Boundaries by clicking "Add item". Each instruction has a name and a description.
- Use the preview panel on the right to verify your instructions. The preview shows a curated view of the system instructions with your changes applied in real time, so you can confirm what the assistant will actually read before saving. Note that the preview does not show the full system instructions; the fixed harness is omitted.
- Click Create customization to save.
You can create multiple customizations per project, each tailored to a different use case (e.g. one for your docs site, one for your marketing page).
Chat model versions
Without customizations, Kapa automatically uses its latest chat model, which defines the AI models, retrieval strategy, and system instructions behind the scenes. When you create a customization, it is pinned to a specific chat model version (e.g. kapa-chat-1.0) that you select at creation time. Behavior can vary slightly between chat model versions, and pinning ensures your configuration stays stable rather than shifting when Kapa releases new versions.
The Kapa research team invests heavily in keeping customizations as a concept stable across versions, and the default Kapa experience improves automatically over time. When upgrading to a new chat model version, it is up to you to verify that Kapa still handles your specific custom instructions in the desired way.
The version is immutable after creation. This prevents accidental changes to a customization that may be actively used by live integrations. The schema itself (which editable sections and fields exist) can also change between chat model versions. The intended upgrade path is to create a new customization on the new version, test it, then swap your integration to use the new one.
Chat model versions go through a lifecycle:
- Active: Available for new customizations. This is the current recommended version.
- Deprecated: Existing customizations continue to work, but you cannot create new ones on this version. The platform will show a warning encouraging you to upgrade.
- Retired: The customization is silently ignored and standard Kapa behavior is used instead. Requests that include a retired customization will receive normal responses as if no customization was set. No error is returned. This ensures existing widget deployments are not broken when a version is retired.
You will be notified both in the platform and by email ahead of schedule when a chat model version changes status, so you have time to plan and test upgrades.
| Version | Status |
|---|---|
kapa-chat-1.0 | Active |
Using a customization
Customizations are never applied at the Project level. They take effect only when you explicitly attach one to a specific prebuilt integration or pass one on a per-request basis via the API. This means the same Project can run different customizations across different prebuilt integrations, or no customization at all.
Customizations are not available for the Retrieval API, the MCP server, or the Agent SDK (which is fully custom by design).
Website Widget
Add the data-customization-id attribute to your widget script tag:
<script
async
src="https://widget.kapa.ai/kapa-widget.bundle.js"
data-website-id="YOUR_WEBSITE_ID"
data-project-name="Your Project"
data-project-color="#6306B6"
data-project-logo="https://example.com/logo.png"
data-customization-id="YOUR_CUSTOMIZATION_ID"
></script>
You can find the customization ID on the customization detail page in app.kapa.ai.
Chat SDK
Pass the customizationId prop to the KapaProvider component:
<KapaProvider
integrationId="YOUR_INTEGRATION_ID"
customizationId="YOUR_CUSTOMIZATION_ID"
callbacks={{...}}
>
<YourApplication />
</KapaProvider>
API
Pass customization_id in the request body when calling the Chat endpoint:
{
"query": "How do I get started?",
"customization_id": "YOUR_CUSTOMIZATION_ID"
}
Writing effective instructions
The tips below are based on experimentation and are not exhaustive. They cover the most common pitfalls we have seen when writing custom instructions.
Be specific
Vague instructions leave too much room for interpretation. The more precisely you describe the behavior you want, the more reliably the assistant will follow it.
Ask clarifying questions when needed.
When a user asks a question that could apply to multiple products in our catalog, list the products it could refer to and ask the user to specify which one before answering.
Be careful with "never"
Absolute prohibitions can backfire. When given a hard constraint, AI models tend to find the nearest workaround that technically complies with the wording but misses the point. If you say "never use bullet points," the model may switch to numbered lists instead.
When you prohibit a behavior, also specify what the assistant should do instead:
Never use bullet points.
Do not use bulleted or numbered lists in your answers. Write in flowing prose instead.
Set reasonable scope
An instruction like "always respond in exactly three sentences" will produce poor results for complex technical questions. When setting constraints, calibrate to what is realistic across the full range of questions your users ask.
Always respond in exactly three sentences.
Keep answers concise. Use only as much length as the question genuinely needs.
Write each instruction to stand on its own
Instructions are not meant to trigger or reference each other. If two behaviors are related, express them together in a single instruction rather than splitting them across two.
Instruction A: When users ask about competitor products, do not provide comparisons.
Instruction B: When you decline to answer a question, suggest the user contact our sales team for more information.
When users ask about competitor products, do not provide comparisons. Suggest they contact our sales team for more information instead.
Use customizations sparingly
Every instruction added to the system instructions competes for the model's attention. A customization with a long list of instructions is harder for the model to follow consistently than one with a short, focused list.
The more instructions you add, the further you take Kapa from its default behavior, which means your customization is less covered by Kapa's extensive evaluations and testing. This also makes version upgrades harder, since more custom behavior needs to be re-verified each time. Use customizations sparingly and only add an instruction when you have a clear, recurring need. Whenever possible, not using a customization at all is preferable.
Common patterns
The examples below are starting points that you can take and adapt to your use case.
Formatting and terminology
Customizing formatting is useful when the assistant's default style does not match your brand voice, or when your product has a defined vocabulary that should not be translated.
Never use bulleted lists or numbered lists in your answer. Write in prose instead.
When responding in Chinese, the following technical terms must always remain in English and must not be translated: [term1], [term2], [term3].
When referring to the knowledge sources you draw from, call them "[Company] Documentation" rather than "the docs" or "the knowledge sources".
Adjusting tone
The two most common tone adjustments are conciseness and warmth, and they are not mutually exclusive. Pick one as your baseline and layer the other only if you have a reason.
Developers reading documentation often want direct, concise answers:
Keep answers as concise as possible. Skip preamble, don't restate the question, no closing pleasantries. Prefer omitting non-essential context over omitting the core answer.
For consumer-facing products where warmth matters:
Adopt a warm, conversational tone. Speak directly to the user in the second person. After answering, when a follow-up question would naturally help the user make progress, end with one short follow-up question.
Setting a deployment context
You can tell the assistant where it is deployed and who it is talking to. This is most useful when the assistant is embedded somewhere other than a standard documentation site, for example on a marketing page, in an onboarding flow, or in an internal tool.
You are on [Company]'s marketing website, talking to potential customers who are evaluating the product. When unsure about a detail, do not hedge with 'the docs don't state' language. Answer what you know and invite the user to connect with the team.
Act as an onboarding companion for [Product]. Be welcoming, encouraging, and patient. Prefer 'getting started' resources over deep technical references when both would answer the question.
Handling out-of-scope questions
Users rarely stay perfectly on topic. When a question falls outside what your assistant should handle, the right response is a clear redirect rather than silence or a hallucinated answer. For example, if a user asks a legal question that should go to your legal team, it is better to acknowledge the boundary explicitly and point them to the right contact than to let the assistant speculate.
Do not answer legal questions (terms of service, contracts, liability, compliance, etc.). Briefly tell the user that legal topics fall outside what you can help with and direct them to email legal@[company].com.
Do not tell the user to contact support, open a support ticket, or email the team. If the knowledge sources do not contain enough information to answer, state the limitation directly and stop.
What customizations cannot do
- They do not add knowledge. If a topic is not covered in your connected knowledge sources, the assistant will not be able to answer it. To fill specific gaps, use Custom Q&A.
- They cannot override the fixed harness. The CommonMark formatting, citation format, prompt injection protection, and uncertainty reporting are required for Kapa to function correctly. Do not attempt to override these via custom instructions; the behavior is not supported and will lead to unreliable results.
- They do not guarantee deterministic behavior. AI language models are probabilistic. Instructions set strong tendencies, not hard rules. If a behavior is business-critical, test it against a representative sample of real questions.