Vercel AI SDK Quickstart

​

Install

npm install @visiq/harness ai @ai-sdk/openai zod

​

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-...   # the sample agent calls an OpenAI model

​

Wrap your agent

import { visiq } from "@visiq/harness";
import { Experimental_Agent as Agent, stepCountIs, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

// Any function returning document-shaped results works as a RAG source.
const searchDocs = async (query: string) => [
  { pageContent: `Q3 revenue was $4.2M. (matched: ${query})`, metadata: { classification: "internal" } },
];

// Your tools — unchanged.
const tools = {
  issue_refund: tool({
    description: "Issue a refund to a customer",
    inputSchema: z.object({ customerId: z.string(), amount: z.number() }),
    execute: async ({ customerId, amount }) => `Refunded $${amount} to ${customerId}`,
  }),
  search_knowledge: tool({
    description: "Search the company knowledge base",
    inputSchema: z.object({ query: z.string() }),
    execute: async ({ query }) => searchDocs(query),
  }),
};

// ── One call — governance + per-run LLM telemetry activate here ──
const agent = visiq(
  new Agent({
    model: openai("gpt-4o"),
    instructions: "You are a helpful assistant.",
    tools,
    stopWhen: stepCountIs(8),
  }),
  { agentId: "support-bot" },
);

const result = await agent.generate({ prompt: "What was Q3 revenue?" });

​

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. Tool 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 hands the model [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. as the tool’s output, so the agent reads it and adjusts course.
• Approvals pause the call. An approval_required decision holds the tool 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 tool with the named arguments redacted; retrieval redaction masks document fields before the model sees them.
• Covered from the first call. Every workspace ships a curated catalog of 35 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 tool 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