Recommended:
Governor, the self-refreshing client. It fetches your agent’s
rule bundle, re-fetches it every 5 seconds before the next decision, and keeps the
last good bundle through a control-plane outage, so stopping an agent (Agent Jail)
blocks its next action without any code on your side. The host-fed helpers
(GateAction(bundleJSON, ...)) are the local-decision layer only: they decide
against whatever bundle you pass in. HITL approvals and audit streaming are not
part of this binding.Build
Build the C-ABI core (no pyo3) once, then build/run the Go package from the repo:Govern with the self-refreshing client
Create oneGovernor per agent and share it (it is safe for concurrent use).
Every GateAction / GateRetrieval call decides against the current bundle.
GateRetrieval(resourceMetadata) and Decide(event) work the same way, and
Bundle() returns the bundle currently held, for code that passes it on.
What it does:
- Refresh. When the bundle is older than the refresh interval, the next
decision fetches
GET /rules/bundle?agent_id=...first. Concurrent calls share one fetch. An unchanged bundle costs a304. - Outage. If a fetch fails or times out, the last bundle it loaded stays in force, however old. A stopped agent stays stopped until the control plane serves it a normal bundle again.
- No bundle yet. Before the first successful fetch (or with no API key
configured, in which case it makes no network call), a decision follows the
fail mode:
openpermits and writes a[VisIQ] FAIL-OPEN (no-bundle)line to stderr;closeddenies.
Acquire a bundle yourself
If you fetch the bundle yourself and call the host-fed helpers below, re-fetch it at least every few seconds. A kill switch reaches the agent only through a fresh bundle. Fetch it over the rules API:VISIQ_ENDPOINT defaults to https://api.visiqlabs.com; set it only for onprem.
Hold the returned JSON as a string (bundleJSON) and pass it to the gate helpers.
Govern a tool call
GateAction(bundleJSON, toolName, args, agentID) decides one tool/action call.
Inspect decision["allowed"]; on a mask verdict apply
decision["action"]["argRedactionRules"] to the args before running the tool.
guide_example_test.go,
ExampleGateAction) against a bundle copied verbatim from the oracle-stamped
conformance corpus: the deny fixture blocks (allowed=false), the permit fixture
passes (allowed=true).
Govern a retrieval
GateRetrieval(bundleJSON, resourceMetadata, agentID) decides one retrieval.
Inspect decision["retrieval"]["action"] — drop on deny/escalate, redact via
decision["retrieval"]["redactionRules"] — before content reaches the model.
Fail mode
A HARNESS-internal failure — the native core can’t load, orvisiq_evaluate
returns NULL — is routed by VISIQ_FAIL_MODE (owner G001 rescope): open
(default) returns a permit-equivalent decision plus a loud stderr report so a
VisIQ packaging bug never disrupts the agent; closed returns a deny-equivalent.
A real rule deny always blocks regardless of fail mode. The same setting
decides what a Governor does before it has loaded a bundle (see above).
Override the core library
The binding loadslibvisiq_core from the build tree. Point it elsewhere with
VISIQ_CORE_LIB (an absolute path), matching the Java and Ruby bindings.
Next steps
Java Reference
The Java binding —
gateAction over the same core.Ruby Reference
The published Ruby gem —
gate_action over the same core.