Skip to main content

Customizations

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:

  1. 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.
  2. 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.
  3. 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.

FieldDefaultWhat it does
Assistant namekapa.aiThe 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.

FieldDefaultWhat it does
Response styleShort, focused, and professional.Defines the overall writing style.
LanguageRespond 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. 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

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.

VersionStatus
kapa-chat-1.0Active

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.

Guides​