@visiq/harness

Governance for AI agents — one function, injected into your agentic framework.

@visiq/harness wraps the tools and executors of your agent framework so every tool call and retrieval is evaluated against your VisIQ governance rules in process, before it runs. Decisions are made by the same compiled governance core (@visiq/core-wasm) that powers the VisIQ platform — so what you enforce locally is exactly what the control plane authored.

• Fail-closed by design — if a decision can't be made (core unavailable, network error, malformed policy), the call is denied, never allowed.
• One call to adopt — visiq(target) wraps a framework executor or an individual tool. No rewrite of your agent.
• Human-in-the-loop — an approval_required decision blocks the tool and waits for a human to approve/deny (bounded by a timeout that itself fails closed).
• Retrieval redaction — masks sensitive fields in retrieved content according to policy.

Install

npm install @visiq/harness

@visiq/core-wasm (the compiled decision core) is a required dependency and is installed automatically. Node.js ≥ 20 only (the core is loaded as native Node WASM — not a browser build).

Quickstart

import { visiq } from "@visiq/harness";
import { AgentExecutor } from "langchain/agents";

// Wrap your framework's executor — every governed tool call now flows
// through VisIQ before it executes.
const executor = visiq(new AgentExecutor({ agent, tools }));

await executor.invoke({ input: "..." });

Wrap an individual tool with an explicit, rule-friendly agent identity:

const search = visiq(new SearchTool(), { agentId: "research-agent" });

Configuration

Options may be passed to visiq(target, options) or supplied via environment variables (option takes precedence, then the env var):

| Option | Env var | Purpose | |---|---|---| | apiKey | VISIQ_API_KEY | Backend API key. | | endpoint | VISIQ_ENDPOINT | Backend endpoint URL. | | agentId | VISIQ_AGENT_ID | Stable agent identity. If unset it is derived (package name → hostname) and auto-provisioned in monitor mode. | | hitlTimeoutMs | VISIQ_HITL_TIMEOUT_MS | Max wait (ms) for a human to resolve an approval_required decision before failing closed. Default 120000. |

Multi-agent delegation

For multi-agent (ORCHESTRATE) flows, mint the env a child process needs so its authority is a scoped delegation of the parent's:

const childEnv = await visiq.delegate("summarizer-agent");
spawn("node", ["summarizer.js"], { env: { ...process.env, ...childEnv } });

Behavior contract

• Deny is terminal — a denied tool call throws before the tool runs; the underlying tool is never invoked.
• Approval blocks — an approval_required decision suspends the call until a human resolves it, or the HITL timeout elapses (then it fails closed).
• Errors fail closed — any evaluation error results in denial, never a silent allow.

License

MIT © VisIQ Labs. See LICENSE.