OpenAI Agents SDK Quickstart

​

Install

npm install @visiq/harness @openai/agents zod

​

Set environment variables

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

​

Wrap your agent

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

​

Python

pip install "visiq>=0.5.0" openai-agents

from agents import Agent, Runner, function_tool
from visiq import govern  # pip install visiq


@function_tool
def issue_refund(customer_id: str, amount: int) -> str:
    """Issue a refund to a customer."""
    return f"Refunded ${amount} to {customer_id}"


@function_tool
def search_knowledge(query: str) -> list:
    """Search the knowledge base."""
    # Your real RAG store returns the same shape: a list of
    # {"page_content", "metadata"} dicts the retrieval facet can filter.
    return [
        {"page_content": f"Q3 revenue was $4.2M. (matched: {query})",
         "metadata": {"classification": "internal"}},
    ]


agent = Agent(
    name="support",
    instructions="You are a helpful assistant.",
    model="gpt-4o",
    tools=[issue_refund, search_knowledge],
)

# ── One call: every tool on this agent is now governed ──
govern(agent, agent_id="support-bot", retrieval_tools={"search_knowledge"})

print(Runner.run_sync(agent, "What was Q3 revenue?").final_output)

• Every tool call is decided before the tool runs. A deny (or a human approval that is not granted) means your function is never called: the block message is returned as the tool’s result, so the model reads why and the run continues. A mask hands your function only the redacted arguments, nested fields included.
• Retrieval results are governed too. Tools named in retrieval_tools also have their result governed before it reaches the model: restricted documents are dropped and sensitive fields redacted, whether the tool returns a list of documents or a JSON string of one. A result the retrieval facet cannot split into documents (a dict envelope, a pydantic model) is withheld rather than passed through.
• Tools added later are covered. The runner assembles the tool list at the start of every turn, and govern() hooks that step, so a tool appended to agent.tools after govern() and the tools built from mcp_servers on each turn are governed before the model can call them.
• The whole agent graph is covered. Agents in handoffs (a plain Agent or one wrapped in handoff(...)) and agents exposed through agent.as_tool(...) are governed too, under the same agent id. To report a sub-agent as a separate agent, call govern(sub_agent, agent_id="...") on it first; an agent that is already governed keeps its own governance.
• Audit per run. The agent and its tool surface are registered with VisIQ on the first turn of the first run, and each run’s decisions are delivered when the agent produces its final output. Your own hooks= keep running.

​

Run this on AWS Bedrock

from agents import Agent
from agents.extensions.models.litellm_model import LitellmModel
from visiq import govern  # pip install visiq

agent = Agent(
    name="support",
    instructions="You are a helpful assistant.",
    model=LitellmModel(model="bedrock/amazon.nova-micro-v1:0"),
    tools=[issue_refund, search_knowledge],
)
govern(agent, agent_id="support-bot", retrieval_tools={"search_knowledge"})

​

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-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. This page also documents the Python SDK, which honours the same posture. The visiq wheel fails OPEN on a harness-internal failure with the same loud [VisIQ] FAIL-OPEN report, and honours VISIQ_FAIL_MODE=closed to block instead. A policy deny, a required mask that cannot be applied, and a HITL approval that cannot be confirmed still block in Python exactly as in TypeScript.
• 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 36 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

• Control AI → Agents: your agent appears automatically (monitor mode) with a live last-seen heartbeat.
• Control AI → Agent Events: a decision row for every governed tool call, with the matched rule and outcome.
• Control AI → 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