> ## 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.

# LangChain Quickstart

> Wrap a LangChain AgentExecutor or LangGraph graph with VisIQ governance in one function call.

Add action governance, retrieval governance, and a full audit trail to a
[LangChain](https://js.langchain.com) agent by passing your `AgentExecutor` to
`visiq()`. The same call detects and wraps a LangGraph `CompiledGraph`. 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 langchain @langchain/openai @langchain/core
```

## Set environment variables

```bash .env theme={null}
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
```

| 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`        | Yes      | Backend base URL — `https://api.visiqlabs.com` for production. There is no built-in default: if unset, no rules can load and the harness fails closed, denying every wrapped tool call.                            |
| `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 { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { createRetrieverTool } from "langchain/tools/retriever";
import { MemoryVectorStore } from "langchain/vectorstores/memory";
import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { DynamicTool } from "@langchain/core/tools";

// A small in-memory knowledge base so this snippet runs as pasted.
const vectorStore = await MemoryVectorStore.fromTexts(
  ["Q3 revenue was $4.2M.", "Refunds over $500 require manager approval."],
  [{ classification: "internal" }, { classification: "public" }],
  new OpenAIEmbeddings(),
);
const knowledgeRetriever = vectorStore.asRetriever();

// Your tools — unchanged.
const tools = [
  new DynamicTool({
    name: "issue_refund",
    description: "Issue a refund to a customer",
    func: async (input: string) => {
      const { customerId, amount } = JSON.parse(input);
      return `Refunded $${amount} to ${customerId}`;
    },
  }),
  createRetrieverTool(knowledgeRetriever, {
    name: "search_knowledge",
    description: "Search the company knowledge base",
  }),
];

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);
const llm = new ChatOpenAI({ model: "gpt-4o", temperature: 0 });
const agent = await createOpenAIToolsAgent({ llm, tools, prompt });

// ── One call — governance + audit trail activate here ──
const executor = visiq(new AgentExecutor({ agent, tools }), { agentId: "support-bot" });

const result = await executor.invoke({ input: "What was Q3 revenue?" });
```

Enforcement wraps each tool's `invoke`/`call`/`_call` dispatch methods
directly — LangChain callbacks cannot block a tool call — so it holds for any
agent constructor, and `executor.stream()` is governed identically to
`invoke()`.

<Note>
  **Per-document RAG governance.** `createRetrieverTool` captures its retriever
  in a closure and returns one joined string, so the harness falls back to
  reduced-fidelity governance for that tool: pattern and value-shape masking
  still apply to the string, but retrieval rules keyed on per-document
  `metadata` (classification, source, …) cannot fire — the SDK prints a one-time
  console warning when this happens. For full per-document governance, expose
  the retriever on the tool as a reachable `.retriever` property, or use a tool
  that returns a `Document[]`: any retriever the harness can reach (including a
  nested `.retriever`) is instrumented so each document is evaluated with its
  own metadata.
</Note>

## 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-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

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 Email under
  **Integration → Connectors** (Human-in-the-loop) — Slack and Microsoft
  Teams delivery is built and their connector cards open shortly.

## Next steps

<CardGroup cols={2}>
  <Card title="Full Quickstart" icon="rocket" href="/quickstart">
    All supported frameworks and what happens behind the scenes.
  </Card>

  <Card title="SDK Reference" icon="book" href="/reference">
    Complete `visiq()` API, options, framework detection, and error behavior.
  </Card>
</CardGroup>