> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vercel AI SDK Quickstart
> Wrap a Vercel AI SDK agent with VisIQ governance in one function call.
**Prerequisites.** A VisIQ account ([sign in](https://app.visiqlabs.com)) with a
harness key from **Settings → Harness Keys**, **Node 20+**, and an
`OPENAI_API_KEY` (the sample below calls an OpenAI model — any provider works).
Full setup and fixes: [Before you start](/quickstart#before-you-start) ·
[Troubleshooting](/troubleshooting).
Add action governance, retrieval governance, and a full audit trail to a
[Vercel AI SDK](https://ai-sdk.dev) agent by passing your `Agent` to `visiq()`.
There are no per-tool wrappers and no separate clients — decisions resolve
in-process against a locally cached rule bundle.
## Install
```bash theme={null}
npm install @visiq/harness ai @ai-sdk/openai zod
```
## Set environment variables
```bash .env theme={null}
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
```
| Variable | Required | Description |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VISIQ_API_KEY` | Yes | Harness key (`vq_prod_...` or `vq_test_...`) — create one under **Settings → Harness Keys** in the [dashboard](https://app.visiqlabs.com). |
| `VISIQ_ENDPOINT` | Optional | Backend base URL — defaults to `https://api.visiqlabs.com`. Set it only for onprem / self-hosted deployments. With just a key the harness reaches SaaS, loads a bundle, and governs automatically (monitor until the first bundle confirms). |
| `VISIQ_AGENT_ID` | No | Agent identity. Auto-derives from your `package.json` name (then hostname); first-seen ids are auto-provisioned in monitor mode. Set it — or the `agentId` option on `visiq()` — for a stable, rule-friendly name. |
| `VISIQ_TIMEOUT_MS` | No | Per-evaluation network timeout in ms (default `5000`). |
| `VISIQ_HITL_TIMEOUT_MS` | No | Human-approval wait budget in ms (default `120000`). |
## Wrap your agent
```typescript theme={null}
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?" });
```
`agent.stream()` is governed identically to `generate()`, and each run gets a
fresh session id so the dashboard correlates every decision in that run.
**Retrieval governance contract.** Per-document filtering applies to tools
whose `execute()` returns document-shaped results — array items with a string
`pageContent`, `text`, or `content` field, plus optional `metadata` that
retrieval rules match on (classification, data categories, …). Results in any
other shape still pass through the action gate but are not filtered
per-document.
## What happens at runtime
Wrapping is safe to try immediately — new agents start in **monitor** mode
(observe-only) until you flip them to **enforce** on the **Harness → Agents**
page.
* **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=] This tool call was NOT executed: it was denied by policy (). 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. {/* truth:count id=default-rules-seeded-enabled value=35 */}
Uncovered actions permit by default — no surprise breakage — and the
per-operation-type default can be tightened in settings.
## Verify it's working
Run the agent once, then open the [dashboard](https://app.visiqlabs.com):
* **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
All supported frameworks and what happens behind the scenes.
Complete `visiq()` API, options, framework detection, and error behavior.