AgentGovern Python SDK
Compliance-as-code for agentic AI workflows.
Beta — API may change before 1.0. Report issues.
AgentGovern intercepts AI agent actions, evaluates them against configurable compliance policies (EU AI Act, NIST AI RMF, ISO 42001), and generates audit-ready evidence — in near real-time (compliance verdicts within seconds; the SDK never blocks your agent). This SDK instruments your LangChain, CrewAI, or OpenAI Agents code with minimal changes.
Install
pip install "agentgovern[langchain]"
Quickstart — LangChain
import agentgovern
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
# 1. Initialize once at startup
agentgovern.init(
api_key="ag_prod_...", # from https://agentgovern.zirahn.com/settings/api-keys
base_url="https://agentgovern.zirahn.com",
environment="development", # "production" | "staging" | "development"
)
# 2. Register your agent
agentgovern.register_agent(
external_id="credit-scoring-v2",
name="Credit Scoring Agent v2",
framework="langchain",
)
# 3. Get the callback handler — binds to credit-scoring-v2 automatically
handler = agentgovern.instrument_langchain()
# 4. Build the agent and pass the handler via config — no other changes needed
agent = create_agent(model=ChatOpenAI(model="gpt-4o"), tools=tools)
result = agent.invoke(
{"messages": [{"role": "user", "content": "Evaluate loan application for customer #12345"}]},
config={"callbacks": [handler]},
)
instrument_langchain() binds to the most recently registered agent. Every tool call,
LLM invocation, and agent step is captured, evaluated against your compliance policies,
and visible in the dashboard.
Enforcement modes (current limitations)
AgentGovern supports four enforcement modes per policy:
| Mode | Behavior (v0.1) |
|---|---|
| warn | Logs violation, agent continues |
| log | Silently logs violation, agent continues |
| disabled | Policy not evaluated |
| enforce | Logs violation, agent should halt — see below |
Known limitation: enforce mode with LangChain (v0.1)
LangChain's callback machinery catches exceptions raised from callback handlers
and logs them as warnings rather than propagating them to halt the agent chain.
This means that when Gate 1 returns action_taken='block' for an enforce-mode
rule, our SDK correctly raises PolicyViolation, but LangChain swallows the
exception and the agent continues executing.
Today: enforce-mode rules log the violation to input_evaluations with full
regulatory citation. The audit trail is complete, but the agent chain does not halt.
v0.2 (Q3 2026): We are releasing a ChatModel wrapper that invokes Gate 1
before the LLM call (not as a callback), enabling real hard-block behavior.
Workaround: For customers who need hard-block today, call
agentgovern.evaluate_input() directly before invoking your agent, and check
result.action_taken == 'block' yourself:
result = agentgovern.evaluate_input(agent_external_id="my-agent", prompt=user_prompt)
if result.action_taken == "block":
raise HTTPException(status_code=403, detail="Prompt blocked by compliance policy")
agent.invoke({"input": user_prompt})
Multiple agents in one process
If you run more than one agent in the same process, pass the agent ID explicitly to avoid ambiguity:
agentgovern.register_agent("fraud-detector", name="Fraud Detector")
agentgovern.register_agent("kyc-agent", name="KYC Agent")
handler_fraud = agentgovern.instrument_langchain("fraud-detector")
handler_kyc = agentgovern.instrument_langchain("kyc-agent")
fraud_agent = create_agent(model=..., tools=...)
kyc_agent = create_agent(model=..., tools=...)
fraud_agent.invoke(inputs, config={"callbacks": [handler_fraud]})
kyc_agent.invoke(inputs, config={"callbacks": [handler_kyc]})
Manual instrumentation (all frameworks)
from agentgovern.types import ActionType, ActionStatus
agentgovern.track_action(
agent_external_id="my-agent-id",
action_type=ActionType.TOOL_CALL,
action_name="fetch_credit_bureau_data",
status=ActionStatus.COMPLETED,
duration_ms=312,
input_payload={"bureau": "experian", "customer_id": "..."},
output_payload={"fico_score": 720},
)
Supported frameworks
| Framework | Auto-instrumentation | Status |
|---|---|---|
| LangChain | instrument_langchain() — wraps tool and LLM callbacks |
Stable |
| CrewAI | Manual via track_action() |
Beta |
| OpenAI Agents API | Manual via track_action() |
Beta |
Auto-instrumentation for CrewAI and OpenAI Agents is on the roadmap.
Compliance frameworks
| Framework | Status |
|---|---|
| EU AI Act (High-Risk Systems) | Available |
| NIST AI RMF | Coming soon |
| ISO 42001 | Coming soon |
Enable policy packs from the AgentGovern dashboard.
Configuration
| Parameter | Default | Description |
|---|---|---|
api_key |
required | SDK ingest key from the dashboard |
base_url |
https://agentgovern.zirahn.com |
API endpoint |
environment |
"production" |
"production" | "staging" | "development" |
policy_engine_url |
https://engine.zirahn.com |
Policy engine endpoint for Gate 1 (evaluate_input) and Gate 2 checks. Override with this argument or the AGENTGOVERN_POLICY_ENGINE_URL env var |
fail_silently |
True |
If True, SDK errors never raise into your agent |
Policy engine address (2.4.0). The default engine address is now the stable name
https://engine.zirahn.com. Versions 2.3.0 and earlier call https://agentgovern.onrender.com
directly. That address keeps working, so nothing breaks if you stay on an older version, but only
the stable name can follow the engine if it moves. Upgrade with pip install --upgrade agentgovern.
If you set policy_engine_url or AGENTGOVERN_POLICY_ENGINE_URL yourself, it still takes precedence.
Claude Code Hook
The SDK ships a built-in CLI for installing the AgentGovern hook into Claude Code. The hook
intercepts PreToolUse events for every tool call and enforces your tenant policies in real
time — before the tool executes. A tool AgentGovern doesn't yet have a specific classification
for is still captured and evaluated, tagged action_type=unmapped_tool rather than silently
skipped.
Install
agentgovern hook install
This deploys the hook script to ~/.agentgovern/hook.py, merges the correct entry into
~/.claude/settings.json (with an atomic backup), and prints instructions for any missing
env vars.
Upgrading an existing install
Upgrading the package does not update a hook that is already installed. hook install
copies the hook script to ~/.agentgovern/hook.py and writes its entries into
~/.claude/settings.json, and a plain agentgovern hook install against an existing install
reports it as already installed and changes nothing. Upgrade, read what is installed now, then
reinstall with --force:
python3 -m pip install --upgrade agentgovern # or the extra you installed with, e.g. "agentgovern[langchain]"
agentgovern hook status # note each line's cmd= value and the "Install mode" line
agentgovern hook install --force # plus the flags below, if status calls for them
agentgovern hook status # reports no [DRIFT] lines once the hook is current
--force writes the current defaults. It does not remember options from the earlier install,
so repeat what hook status showed:
cmd=is anything other than plainpython3(for examplecmd=/opt/local/bin/python3.12): add--python-command <that exact value>. Without it,--forceresets the hook topython3.Install mode: minimal: add--capture-mode=minimal. Without it,--forceturns a minimal install into a full one.- You once passed
--matcher: pass it again.
Your environment variables are not touched. Restart any running Claude Code session afterwards.
If a command isn't found:
-
pip: command not found: usepython3 -m pip, as above. -
agentgovern: command not found(the command was installed somewhere that isn't on yourPATH), or pip refuses withexternally-managed-environment: install the CLI into its own virtual environment and call it by its full path:python3 -m venv ~/.agentgovern-venv ~/.agentgovern-venv/bin/python -m pip install --upgrade agentgovern ~/.agentgovern-venv/bin/agentgovern hook status ~/.agentgovern-venv/bin/agentgovern hook install --force # plus the flags status called for
The venv holds only the CLI. The hook itself runs with the interpreter recorded in
~/.claude/settings.json(thecmd=value inhook status;python3unless you chose otherwise). That interpreter needs no packages, because the hook script uses only the standard library, and installing from a venv does not change it unless you pass--python-command.
If your hook was installed by 2.2.1 or earlier, this step matters for coverage, not just
freshness. Those versions wrote a PreToolUse matcher naming a fixed list of tools (ten, in 2.2.1), so a call
through any other tool (PowerShell, for example) never reached the hook. Starting with 2.3.0
the matcher is *, every tool — but only once hook install --force has rewritten the entry.
Required env vars
export AGENTGOVERN_API_KEY="ag_prod_..." # Settings → API Keys
export AGENTGOVERN_ACTOR_USER_ID="user_2xxxx..." # Settings → Profile → User ID
Subcommands
| Command | Description |
|---|---|
agentgovern hook install |
Install the hook (flags: --dry-run, --force, --matcher, --python-command) |
agentgovern hook uninstall |
Remove the hook entry from settings.json (script file preserved) |
agentgovern hook status |
Show installation state, script path, and env var status |
agentgovern hook test |
Fire a synthetic event to verify end-to-end connectivity |
Bypass
To skip governance for a session without removing the hook:
AGENTGOVERN_HOOK_MODE=off claude
See packages/claude-hook/README.md for the full option reference.
Design guarantees
track_action()returns in < 5 ms — all I/O is async in a background thread- Buffer cap: 10,000 actions; oldest dropped when full
- Retry: 3 attempts with exponential backoff (1 s → 30 s max)
- If AgentGovern is unreachable, your agent continues unaffected
Links
- Dashboard: https://agentgovern.zirahn.com
- Documentation: https://github.com/ahmedkhan-zirahn/agentgovern
- Issues: https://github.com/ahmedkhan-zirahn/agentgovern/issues
License
MIT — Copyright (c) 2026 Zirahn
Metadata
Release files for agentgovern 2.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentgovern-2.5.0.tar.gz | 163.3 kB | With provenance | Details for agentgovern-2.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentgovern-2.5.0-py3-none-any.whl | Python 3 | none | any | Details for agentgovern-2.5.0-py3-none-any.whl |
Total release size: 250.1 kB
Release files / agentgovern-2.5.0.tar.gz
| Download URL | agentgovern-2.5.0.tar.gz |
|---|---|
| Size | 163.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8cf2d87ef9980fe036063ad1adf113f751793ba236a79dfa94202e16ba3751f7
|
|
BLAKE2b-256 checksum How to use checksums |
c987b583aaf8ef08fff727514c182735caa79a76c5476e53c17efc2ee47e133d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / agentgovern-2.5.0-py3-none-any.whl
| Download URL | agentgovern-2.5.0-py3-none-any.whl |
|---|---|
| Size | 86.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b2fc9005597093cea434dd5c0e469650440ed35c02d4aa489c532591abc00ad
|
|
BLAKE2b-256 checksum How to use checksums |
ba38969ec10cf320a0c55a8386daf9d5944cf7059b05ed8c1cda235793a497fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logSecurity for agentgovern 2.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentgovern-2.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.