Connecting your first system, end to end
The full path from a bare API to a working assistant answer: a connector instance, a declared capability, and the gate that checks both before anything goes live.
Getting Kav to answer from a system it doesn't already know about is two separate acts: connecting to the system, and declaring what the assistant may ask it for. Keeping them separate is deliberate — a connector describes how to reach a system, a capability describes what a resident is allowed to ask, and neither one should have to know the other's details.
1. Register a connector instance
In Connectors, create a new instance. You'll give it:
- A slug — a stable, url-shaped name you'll reference later (
rlz-umbraco, not "Umbraco 2"). - A definition — which kind of system this is (the connector type your platform operator has made available).
- A base URL — an absolute
http(s)://address; a relative or file-scheme URL is refused, both here and again on the server. - A credential vault key — the name of a secret already stored in your key vault, never the secret itself. There is no field anywhere in the Studio that accepts a raw credential value.
A brand-new instance is created Draft and in Mock mode, and it cannot call anything in that state. That's by construction, not a missing feature — going live is a separate, deliberate, auditable step on the instance's own screen, so nothing you're still wiring up can accidentally reach a real system.
2. Declare the capability
In Catalogue, declare a new capability against that connector. This is where the three faces come in:
- Semantics (what the model reads): a summary, when to use it, when not to use it, and any disambiguation — the same in every language and every city.
- Contract: the input fields a resident's question resolves to, and the output fields the capability promises back — described as a table of name / type / required / description, not raw JSON, though the raw editor is always one click away for a shape the table can't hold.
- Policy: the assurance level required (A0 through A4), the data sensitivity class, an optional entitlement, caching, and — for a write capability — confirmation and an idempotency window, which are forced on rather than optional.
- Rendering: which hint the answer uses (Text, CardList, Table, Detail or Confirmation) and which fields are numeric, so the number is always drawn from your data and never typed by the model.
Watch the panel on the right as you type. It isn't a summary of validation — it's a live compile of the actual tool the assistant would be handed, description and all. If it says a field was stripped as an identity parameter, that's not a warning to dismiss; it's telling you the contract asked for something (like a resident id) that must never come from the caller.
3. Let the gate decide, not your own judgment
The save control is disabled while the compiled draft has any error-level diagnostic — not as a formality, but because the same check runs again, identically, the moment you actually try to declare it. There's no way to sneak past it by saving anyway.
Once it's green, save the capability. It's usable by the assistant from that point on, in every channel your organization has turned on — because a capability isn't wired to one channel, it's wired to the whole platform.