netzilo (Python)

Netzilo AI Detection & Response(AIDR) for Python

Provides full governance for custom AI agents written in Python

How it works

The Netzilo client is compiled to a native shared library and loaded in-process via ctypes. Every LLM prompt, model response, and tool call your agent makes can be evaluated — allowed, blocked, or redacted — against policy pulled live from your Netzilo management server. No daemon, no sidecar — nothing to stand up.

Install

pip install netzilo

Wheels are published per platform (Linux, macOS, Windows) and are independent of your Python version.

Core API

import netzilo

netzilo.start(server="https://srv.netzilo.com",   # management server
              pat="nzl_...",                       # or setup_key="..."
              agent_name="my-agent")               # non-blocking

netzilo.is_running()                       # -> bool: True once policy has synced (ready to govern)
netzilo.mcp_gateway_port()                 # -> int: scanner gateway port in use (auto-picked)
allowed, reason = netzilo.is_allowed("Bash", {"command": "rm -rf /"})
netzilo.report_result("Bash", "<stdout>")  # post-tool observability
netzilo.flush()                            # force-deliver buffered events to management
netzilo.snapshot()                         # force AIDR behavior-graph snapshot + delivery (else hourly/at-stop)
netzilo.stop()                             # graceful stop (snapshots graph + flushes events; auto-registered atexit)

Parameters may be passed as keyword args (above) or a single config dict. config_path defaults to ~/.netzilo-sdk/config.json; ports auto-pick free ports (governance on by default). is_running() returns True only after the initial policy sync — poll it before kicking off work.

Evaluation runs inside the process — evaluate() calls the embedded engine directly, with no HTTP roundtrip and no local port to manage.

Advanced governance (enable_advanced_governance=True) — Linux only

Framework adapters (below) govern at the tool/LLM-hook layer and work on macOS, Linux, and Windows. Advanced governance adds deep inspection of the agent's own outbound traffic — covering every prompt, response, and tool call (including from subprocesses and libraries you have no hook for), with full content analysis and semantic classification. It is currently only supported when your agent process runs on Linux; on macOS/Windows, set enable_advanced_governance=False (the default) and rely on the framework adapters:

netzilo.start(server=..., pat=..., agent_name=..., enable_advanced_governance=True)

It is fully automatic and requires no root and no changes to the host — the SDK prepares the process so the agent's traffic is inspected and continues to work normally. Inspected prompts/responses are analyzed and classified, emitting semantic.event records to your dashboard alongside the usual tool/LLM events. Default off; the framework adapters govern without it.

Framework adapters

Adapters are submodules of the one netzilo package — no separate installs. The framework is imported lazily inside each adapter (where it's imported at all — see below), so pip install netzilo never pulls in a framework you don't use.

Process-wide hooks

Register once; every tool call and LLM call made through the framework is governed from then on — no per-tool wrapping needed.

# CrewAI — registers before/after tool and LLM hooks process-wide
from netzilo.crewai import govern
govern(config={...})

# LangGraph — wrap nodes before compile()
import netzilo.langgraph
netzilo.langgraph.govern(graph, config={...})

# AutoGen — intervention handler
from netzilo.autogen import handler
runtime = SingleThreadedAgentRuntime(intervention_handlers=[handler(config={...})])

See CrewAI: local vs CrewAI AMP below for CrewAI's two deployment modes.

Tool-decorator frameworks

Where a framework's "tool" is a plain function wrapped by a decorator or a from_function()-style constructor, govern_tool() wraps the function itself. Apply it closer to the function than the framework's own decorator so schema inference still sees the original signature (functools.wraps preserves it):

from netzilo.llamaindex import govern, govern_tool
from llama_index.core.tools import FunctionTool

govern()  # starts the embedded client once, at boot

@govern_tool
def get_order_status(order_id: str) -> str:
    ...

tool = FunctionTool.from_defaults(fn=get_order_status)

The same pattern covers netzilo.langchain, netzilo.openai_agents (OpenAI Agents SDK), netzilo.google_adk, netzilo.pydantic_ai, netzilo.semantic_kernel, netzilo.smolagents, and netzilo.haystack — swap the import and the framework's own tool constructor/decorator, everything else is the same. netzilo.tools provides the same govern_tool() for any framework without a dedicated module. netzilo.langchain additionally exposes govern_model() for full prompt/response redaction at the LangChain chat-model boundary — see that module's docstring.

Raw LLM clients

For agents calling a provider's SDK directly with no framework in between, govern_client() patches the one call that sends a prompt so it's gated and redacted in place, then hands back the same client:

from netzilo.openai_sdk import govern, govern_client
from openai import OpenAI

govern()
client = govern_client(OpenAI())

resp = client.chat.completions.create(
    model="gpt-4o", messages=[{"role": "user", "content": "..."}]
)

Also available: netzilo.anthropic_sdk, netzilo.bedrock (AWS Bedrock runtime), netzilo.gemini (Google GenAI), netzilo.mistral — same govern() / govern_client() shape for each provider's own client and method.

Hook / middleware integrations

# LiteLLM — a CustomLogger registered into litellm.callbacks
from netzilo.litellm import govern, handler
import litellm
govern()
litellm.callbacks = [handler()]

# MCP — governs tool calls made through a ClientSession
from netzilo.mcp_client import govern, govern_session
session = govern_session(ClientSession(read_stream, write_stream))

# Guardrails AI — Netzilo as a Validator, composes with a Guard's own pipeline
from guardrails import Guard
from netzilo.guardrails import govern, validator
guard = Guard().use(validator(on_fail="fix"))

CrewAI: local vs CrewAI AMP

Local / self-hosted — put govern() once at the top of your entrypoint, before kickoff(). That's it.

import netzilo.crewai
netzilo.crewai.govern(config={"server": "...", "pat": "...", "agent_name": "my-agent"})

MyCrew().crew().kickoff(inputs={...})   # governed

CrewAI AMP — AMP's managed runtime only executes Flow @start/@listen methods; it skips module-level code, lifecycle hooks, and tool bodies. So the same govern() call goes inside a Flow @start step, then your crew runs in @listen. Deploy with [tool.crewai] type = "flow" in pyproject.toml, and always create the automation fresh as a flow (the type is locked at creation — re-pushing cannot convert an existing crew automation).

from crewai.flow import Flow, listen, start
import time

class MyFlow(Flow):

    @start()
    def init_governance(self):
        import netzilo, netzilo.crewai
        netzilo.crewai.govern(config={"server": "...", "pat": "...", "agent_name": "my-agent"})
        while not netzilo.is_running():   # wait until policy has synced
            time.sleep(0.5)

    @listen(init_governance)
    def run(self):
        return MyCrew().crew().kickoff(inputs={...})   # governed

Optional convenience extras pull a framework alongside netzilo, e.g. pip install netzilo[crewai], netzilo[langgraph], netzilo[llamaindex], netzilo[bedrock] — see [project.optional-dependencies] in pyproject.toml for the full list (one per adapter above). None of these are required: every adapter imports its framework lazily, so the extra is a convenience, not a dependency of the adapter itself.

Configuration

start() / govern() accept a config dict. Common keys:

Notes

The native library is bundled inside the wheel; pip selects the correct one for your platform automatically. Adapters ship inside the same wheel as submodules — a single distribution, not per-framework packages.

Netzilo is a commercial product. See https://www.netzilo.com.