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

# LlamaIndex.TS Quickstart

> Wrap a LlamaIndex.TS agent workflow with VisIQ governance in one function call.

<Note>
  **Prerequisites.** A VisIQ account ([sign in](https://app.visiqlabs.com)) with a
  harness key from **Settings → Harness Keys**, **Node 20+** (or **Python 3.9+**
  for the [Python](#python) path), 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).
</Note>

Add action governance, retrieval governance, and a full audit trail to a
[LlamaIndex.TS](https://ts.llamaindex.ai) agent workflow 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 llamaindex @llamaindex/workflow @llamaindex/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 { tool } from "llamaindex";
import { agent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/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 = [
  tool({
    name: "issue_refund",
    description: "Issue a refund to a customer",
    parameters: z.object({ customerId: z.string(), amount: z.number() }),
    execute: async ({ customerId, amount }) => `Refunded $${amount} to ${customerId}`,
  }),
  tool({
    name: "search_knowledge",
    description: "Search the company knowledge base",
    parameters: z.object({ query: z.string() }),
    execute: async ({ query }) => searchDocs(query),
  }),
];

// ── One call — governance + per-run session activate here ──
const supportAgent = visiq(
  agent({ name: "support", llm: openai({ model: "gpt-4o" }), tools, systemPrompt: "You are a helpful assistant." }),
  { agentId: "support-bot" },
);

const result = await supportAgent.run("What was Q3 revenue?");
console.log(result.data.result);
```

`runStream()` is governed identically to `run()`, and each run gets a fresh
session id so the dashboard correlates every decision in that run.

<Note>
  **Retrieval governance contract.** The harness governs a LlamaIndex workflow
  at the tool boundary: each tool's `call()` is gated, and per-document
  filtering applies to tools that return document-shaped results — array items
  with a string `pageContent`, `text`, or `content` field, plus optional
  `metadata` that retrieval rules match on (classification, data categories,
  …). A retriever wired directly into the workflow (e.g. `index.asRetriever()`)
  returns node objects the filter does not recognize — expose retrieval as a
  tool that maps retrieved nodes to `{ text, metadata }` documents before
  returning them, as in the snippet above.
</Note>

## Python

LlamaIndex ships a Python framework, and so does VisIQ: the
[`visiq`](https://pypi.org/project/visiq/) wheel — published on PyPI, compiled
from the same governance core. The Python API is **not** a `visiq()` wrapper.
You construct a `Governor` and route each tool call through its gate, so a policy
**deny** raises `ToolBlocked` and a `mask` verdict hands your callback only the
redacted arguments.

```bash theme={null}
pip install visiq "llama-index-core>=0.11,<0.13" "llama-index-llms-openai>=0.2,<0.4"
```

The `visiq` wheel reads its configuration from the **process environment** and
does not auto-load a project `.env` (that is the TypeScript harness) — so load it
yourself before constructing the `Governor`, or export the variables:

```python theme={null}
import asyncio
import functools
import inspect

from dotenv import load_dotenv          # pip install python-dotenv
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI

from visiq import Governor, ToolBlocked  # pip install visiq

load_dotenv()                            # VISIQ_API_KEY / VISIQ_AGENT_ID (+ VISIQ_ENDPOINT for onprem)

gov = Governor(agent_id="support-bot")


def governed(name, fn):
    # functools.wraps preserves the real signature so LlamaIndex builds a correct
    # per-parameter schema (a bare **kwargs wrapper would blind arg-matching rules).
    sig = inspect.signature(fn)

    @functools.wraps(fn)
    def tool_fn(*a, **kw):
        bound = sig.bind(*a, **kw)
        bound.apply_defaults()
        args = dict(bound.arguments)
        try:
            # gate_tool decides BEFORE the body runs; the callback receives the
            # EFFECTIVE (redacted-on-mask) arguments, never the originals.
            return gov.gate_tool(name, args, lambda effective: fn(**effective))
        except ToolBlocked as e:
            return f"[BLOCKED BY POLICY] {e.reason}"

    tool_fn.__name__ = name
    return tool_fn


def issue_refund(customer_id: str, amount: int) -> str:
    return f"Refunded ${amount} to {customer_id}"


def scenario_search(query: str) -> list:
    # A stand-in retrieval source — your real RAG store returns the same shape: a
    # list of {"page_content", "metadata"} dicts that gate_documents can filter,
    # drop, or redact before the model sees them.
    return [
        {"page_content": f"Q3 revenue was $4.2M. (matched: {query})",
         "metadata": {"classification": "internal"}},
    ]


def search_knowledge(query: str) -> str:
    # Retrieval governance: drop / redact documents before the model sees them.
    docs = gov.gate_documents(scenario_search(query), query=query)
    return "\n\n".join(d["page_content"] for d in docs)


tools = [
    FunctionTool.from_defaults(fn=governed("issue_refund", issue_refund),
                               name="issue_refund", description="Issue a refund to a customer"),
    FunctionTool.from_defaults(fn=search_knowledge, name="search_knowledge",
                               description="Search the company knowledge base"),
]


async def main():
    # Report the tool surface once (drives blast-radius inference).
    gov.start(tools=[{"name": t.metadata.name, "description": t.metadata.description} for t in tools])
    agent = FunctionAgent(tools=tools, llm=OpenAI(model="gpt-4o"),
                          system_prompt="You are a helpful assistant.")
    print(await agent.run("What was Q3 revenue?"))
    gov.flush()  # deliver any buffered audit events before the process exits


asyncio.run(main())
```

A complete, runnable version of this agent — same 13 tools, same RAG corpus —
lives in
[`examples/llamaindex-agent-py`](https://github.com/VISIQ-LABS/xy/tree/main/examples/llamaindex-agent-py).
The [LangChain](/quickstart/langchain) and
[OpenAI Agents SDK](/quickstart/openai-agents-sdk) quickstarts have Python
peers too.

## 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=<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. {/* 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

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