Governor
for any other Java agent.
Install
--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 oneGovernor 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 ingateTool. 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.
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 theGovernor 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. TheGovernor 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: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 withVISIQ_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.