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

# OpenAI Agents SDK Quickstart

> Wrap an OpenAI Agents SDK agent 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 an
[OpenAI Agents SDK](https://openai.github.io/openai-agents-js) 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 @openai/agents 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 { Agent, run, tool } from "@openai/agents";
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 telemetry activate here ──
const agent = visiq(
  new Agent({ name: "support", instructions: "You are a helpful assistant.", tools, model: "gpt-4o" }),
  { agentId: "support-bot" },
);

const result = await run(agent, "What was Q3 revenue?");
console.log(result.finalOutput);
```

The harness wraps each function tool's model-facing `invoke` in place, so
every call the `run()` loop dispatches is gated — regardless of how you start
the run.

<Note>
  **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.
</Note>

## Python

The OpenAI Agents SDK has a Python edition, 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 "openai-agents>=0.1,<1.0"
```

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

from dotenv import load_dotenv          # pip install python-dotenv
from agents import Agent, Runner, function_tool

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 gate(name, fn, **kwargs):
    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, kwargs, lambda effective: fn(**effective))
    except ToolBlocked as e:
        return f"[BLOCKED BY POLICY] {e.reason}"


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


# The OpenAI Agents SDK derives each tool's JSON schema from the typed signature,
# so declare tools explicitly and route every body through the gate.
@function_tool
def issue_refund(customer_id: str, amount: int) -> str:
    return gate("issue_refund", _issue_refund, customer_id=customer_id, amount=amount)


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"}},
    ]


@function_tool
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 = [issue_refund, search_knowledge]


async def main():
    gov.start(tools=[{"name": t.name} for t in TOOLS])  # report the tool surface once
    agent = Agent(name="support", instructions="You are a helpful assistant.",
                  model="gpt-4o", tools=TOOLS)
    result = await Runner.run(agent, "What was Q3 revenue?")
    print(result.final_output)
    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/openai-agents-agent-py`](https://github.com/VISIQ-LABS/xy/tree/main/examples/openai-agents-agent-py).
The [LangChain](/quickstart/langchain) and [LlamaIndex](/quickstart/llamaindex)
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>