Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 2.8.5 instead.
Reason given by maintainers: Defaults to a retired API host. Upgrade to agentgovern 2.4.0 or later.

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"
fail_silently True If True, SDK errors never raise into your agent

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. After upgrading, reinstall with --force:

pip install --upgrade agentgovern     # or the extra you installed with, e.g. "agentgovern[langchain]"
agentgovern hook install --force
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: if you installed with --capture-mode=minimal, --matcher or --python-command, pass them again — --force without --capture-mode=minimal turns a minimal install into a full one. Your environment variables are not touched. Restart any running Claude Code session afterwards.

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

License

MIT — Copyright (c) 2026 Zirahn

Metadata

Release files for agentgovern 2.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentgovern 2.3.0
File Size Uploaded Provenance Actions
agentgovern-2.3.0.tar.gz 150.5 kB With provenance Details for agentgovern-2.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentgovern 2.3.0
File Interpreter ABI Platform Actions
agentgovern-2.3.0-py3-none-any.whl Python 3 none any Details for agentgovern-2.3.0-py3-none-any.whl

Total release size: 232.9 kB

Release files / agentgovern-2.3.0.tar.gz

Download URL agentgovern-2.3.0.tar.gz
Size 150.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5c5372f57c76987ad9a76aabb88cf15021c63343698c009480bca797fd5497b8
BLAKE2b-256 checksum
How to use checksums
a6593200f7ca9f0ac47b1e62e3ed72049945a67deb4b2866e94590e85863651f
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 Sep 30, 2026.

Transparency log

Release files / agentgovern-2.3.0-py3-none-any.whl

Download URL agentgovern-2.3.0-py3-none-any.whl
Size 82.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d7082fb37925c318349dc20d89dc26166f1701aa855097a75c94760fd969733
BLAKE2b-256 checksum
How to use checksums
1d0dc8f6e5c992b086716d8ae8a5490472b4fcee71ef164fdcc1339c9cffcb78
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 Sep 30, 2026.

Transparency log

Security for agentgovern 2.3.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.

Select from 2 files

Attestation for agentgovern-2.3.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 Sep 30, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release

2.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page