Vercel AI SDK Quickstart

​

Install

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

​

Set environment variables

VISIQ_API_KEY=vq_prod_...
VISIQ_ENDPOINT=https://api.visiqlabs.com
# Optional — auto-derived from your package.json name when unset
VISIQ_AGENT_ID=support-bot

​

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-closed. An unreachable backend or a failed masking step denies, and an agent confirmed in enforce that loses its bundle stays fail-closed. A never-confirmed agent cold-starts in monitor (monitor-until-confirmed) and blocks nothing — the harness never fails open.
• Denials are returned, not thrown. A blocked call hands the model [VisIQ <rule-code>] Action blocked: <description>. (VisIQ is a security harness installed by your developer.) 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, Microsoft Teams, or Email — 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 29 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 Email under Integration → Connectors (Human-in-the-loop) — Slack and Microsoft Teams delivery is built and their connector cards open shortly.

​

Next steps