Semantic Kernel Quickstart

​

Install

npm install @visiq/harness semantic-kernel

​

Set environment variables

VISIQ_API_KEY=vq_prod_...
# VISIQ_ENDPOINT defaults to https://api.visiqlabs.com — set only for onprem/self-hosted
# Optional — auto-derived from your package.json name when unset
VISIQ_AGENT_ID=support-bot
OPENAI_API_KEY=sk-...   # only if the kernel calls an OpenAI model

​

Wrap your kernel

import { visiq } from "@visiq/harness";
import { Kernel, kernelFunction, KernelArguments } from "semantic-kernel";

// Your kernel — build it exactly as you normally would (add an AI service,
// register plugins/functions). Nothing here is VisIQ-specific.
const kernel = new Kernel();

// A tool the agent can call.
const issueRefund = kernelFunction(
  ({ customerId, amount }) => `Refunded $${amount} to ${customerId}`,
  {
    name: "issue_refund",
    pluginName: "billing",
    description: "Issue a refund to a customer",
    schema: {
      type: "object",
      properties: {
        customerId: { type: "string" },
        amount: { type: "number" },
      },
      required: ["customerId", "amount"],
    },
  },
);

// A retrieval source — a function whose result is document-shaped.
const searchKnowledge = kernelFunction(
  ({ query }) => [
    { content: `Q3 revenue was $4.2M. (matched: ${query})`, metadata: { classification: "internal" } },
  ],
  {
    name: "search_knowledge",
    pluginName: "kb",
    description: "Search the company knowledge base",
    schema: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"],
    },
  },
);

// ── One call — governance + per-run audit trail activate here ──
const governedKernel = visiq(kernel, { agentId: "support-bot" });

// Invoke functions exactly as before — every call is now governed.
const result = await issueRefund.invoke(
  governedKernel,
  new KernelArguments({ customerId: "cust_42", amount: 500 }),
);
console.log(result.value);

​

Connect a model

// After kernel.addService(...) and registering your plugins:
const governedKernel = visiq(kernel, { agentId: "support-bot" });

// Every KernelFunction the model invokes now runs through governance.

​

What happens at runtime

• Decisions are local. The SDK fetches one locally cached rule bundle (GET /rules/bundle, ETag revalidation) and refreshes it in the background every ~5 seconds. Function calls evaluate in-process; the only decision-path network call is waiting on a human approval.
• Fail-open by default, loudly — strict deny is opt-in. Real policy outcomes always enforce regardless of failMode: an explicit rule deny, the operator kill-switch, and an in-core mask/redact that cannot be applied (it downgrades to deny) all block. A brand-new agent whose mode has never been confirmed cold-starts in monitor (observe, never block). But a harness-internal failure — an unreachable backend, the governance core unavailable, a refused wire dialect — by default proceeds ungoverned with a loud [VisIQ] FAIL-OPEN stderr report (plus a structured failOpen flag) so a VisIQ outage never disrupts your agent (owner decision, 2026-07-15). Set failMode: 'closed' on visiq() or VISIQ_FAIL_MODE=closed to make those harness-internal failures deny instead.
• Denials are returned, not thrown. A blocked call replaces the function’s result with [VisIQ decision=deny code=<rule-code>] This tool call was NOT executed: it was denied by policy (<description>). VisIQ is a security harness installed by your developer. Report this reason to the user verbatim; do not invent a different one. so the model reads it and adjusts course — the function body never runs.
• Approvals pause the call. An approval_required decision holds the function while a human decides via Slack or Email (Microsoft Teams delivery is built server-side; its connector card is coming soon) — the SDK polls for up to 120 seconds (VISIQ_HITL_TIMEOUT_MS), then fails closed.
• Mask proceeds, redacted. A mask decision runs the function with the named arguments redacted before it sees them; retrieval redaction masks document fields (and rendered-prompt content) before the model sees them.
• Covered from the first call. Every workspace ships a curated catalog of default rules. Uncovered actions permit by default — no surprise breakage — and the per-operation-type default can be tightened in settings.

​

Verify it’s working

• Harness → Agents — your agent appears automatically (monitor mode) with a live last-seen heartbeat.
• Harness → Runtime Enforcement — a decision row for every governed function call, with the matched rule and outcome.
• Harness → Escalations — pending approvals. Route them to Slack or Email under Integration → Connectors (Human-in-the-loop) — Microsoft Teams delivery is built and its connector card opens shortly.

​

Next steps