Skip to main content
The Java SDK governs your agent’s tool calls and retrieved content in your own process. It runs the same compiled VisIQ core as the Python and TypeScript SDKs, through Java’s Foreign Function & Memory API, so there is no JNI shim and no separate install. Using Microsoft Semantic Kernel? Read the Semantic Kernel quickstart: one call governs every function on the kernel. This page covers the Governor for any other Java agent.

Install

Requires JDK 22 or later. Run your app with --enable-native-access=ALL-UNNAMED. The jar carries the compiled core for macOS, Linux and Windows, so there is nothing else to install.
Pre-1.0 (0.x). Breaking changes may ship in any minor release until v1.0. Pin an exact version. See SDK versioning.

Set your key

VISIQ_ENDPOINT defaults to https://api.visiqlabs.com. Set it only for an on-premises deployment.

Create a Governor

Create one Governor per agent and keep it for the life of the process.
start() loads your rules and adds the agent to Control AI → Agents. Pass your tools to start(tools), each as a {name, description, parameters} JSON object, and the dashboard lists them too. A new agent starts in monitor mode: every decision is recorded and nothing is blocked until you switch the agent to enforce on that page. The Governor checks for rule changes at most every 5 seconds, so a new rule, or Agent Jail, reaches the agent’s next call within 5 seconds.

Govern a tool call

Wrap the call to your tool in gateTool. Your code runs only if policy allows it, and it receives the arguments it is allowed to use.
args is a Jackson JsonNode of the tool’s arguments, for example new ObjectMapper().createObjectNode().put("amount", 500). blocked.toolMessage() tells the model the call was refused and why, in the same words every VisIQ SDK uses, so the model can explain it to the user instead of retrying.

Approvals

When a rule requires approval, gateTool waits while a person decides. The request appears under Control AI → Escalations, and in Slack or Email if you connected one under Integration → Connectors.
  • Approved: your code runs with the full arguments.
  • Rejected, or no answer in time: ToolBlockedException, and your code does not run. If the rule says to mask instead, your code runs with the sensitive arguments redacted.
  • The agent is put in Agent Jail while it waits: refused.
The wait lasts up to 120 seconds. Change it with VISIQ_HITL_TIMEOUT_MS or .hitlTimeout(Duration.ofMinutes(5)). gateTool blocks the thread that calls it while it waits, so call it from a worker thread if that thread must stay free. An approval needs your API key: without one there is nobody to ask, and the call is refused.

Govern retrieved content

Pass what a search or a tool returned through the Governor before the model sees it.
gateDocuments drops a document your rules deny, redacts one they redact, and keeps the rest. Each document is a JSON object with its text under content, text or page_content, plus its fields, such as classification, either under metadata or beside the text. Rules can match the fields and the text. gateText returns the text, the text with matches redacted, or [RECALL] Retrieved context was blocked by policy.

Decisions in your dashboard

Every decision appears under Control AI → Agent Events. The Governor sends them in the background, a batch at a time; call governor.flush() to send what is waiting, or governor.close() when your agent shuts down. Anything still waiting is also sent when the process exits normally.

Options

Fail mode

If VisIQ itself fails (the core cannot load, or no rules could be fetched yet), open, the default, lets the call through and prints a [VisIQ] FAIL-OPEN line to stderr, so a VisIQ problem never stops your agent. closed refuses the call instead. A rule that denies a call, and Agent Jail, always block, whatever the fail mode.

If you fetch the bundle yourself

If you would rather fetch the rules yourself and make no other network calls, decide against the bundle you hold:
Fetch the bundle from GET /rules/bundle?agent_id=... on the rules API, and re-fetch it at least every few seconds: a rule change or Agent Jail reaches the agent only through a fresh bundle. On a mask, apply decision.get("action").get("argRedactionRules") to the arguments before the call. These functions do not ask for approval or report decisions; the Governor does both.

Upgrading from 0.1.1

Visiq.gateAction, Visiq.gateRetrieval and Visiq.decide work as before. The Governor, gateTool, approvals, gateDocuments, gateText and decision reporting are new in 0.2.0. To move to them, create a Governor, wrap each tool call in gateTool, and stop fetching the bundle yourself.

Override the core library

The jar extracts its bundled core to a temporary file. Point it at a specific library with VISIQ_CORE_LIB, an absolute path.

Next steps

Semantic Kernel quickstart

Govern every function on a Semantic Kernel in one call.

Python Reference

The same Governor, in Python.