Skip to main content

alovia-watchdog

Runtime protection for AI agents. Guard your agent's inputs with your Alovia fleet key.

Install

pip install alovia-watchdog

Use

from alovia_watchdog import Watchdog, guard_input

wd = Watchdog(api_key="wd_live_...")

# Pass session_id: it groups a conversation's turns so the scope-expansion and
# cascade-anomaly detectors can see across them. Without it they have nothing to
# correlate and stay silent, so always send a stable per-conversation id.
@guard_input(wd, agent="support-bot", session_id=lambda: chat_id)
def handle(message):
    ...

guard_input raises WatchdogBlocked when verdict.enforce says to stop, so the wrapped function never runs on a malicious or unresolved input. On a network error it honors fail_mode ("closed" blocks, "open" allows).

Fail mode

Leave fail_mode unset and the fail mode you set for the fleet in the dashboard decides an unresolved verdict on the server. Locally the client still stops on an unresolved verdict or a network error, the same as "closed". Pass fail_mode="open" or "closed" only to override the fleet's setting for this client. Before 0.5.0 the client always sent "closed", so the fleet's setting never applied to an SDK call.

Always pass agent. A call with no agent name has no mission to check against, so on a fleet that fails closed Watchdog refuses it with an anonymous_actor finding. This is a server rule: it applies to every SDK version, not only 0.5.0.

You can also check directly:

verdict = wd.check("some user input", agent="support-bot", session_id=chat_id)
if verdict.enforce:
    ...

Use verdict.enforce, not verdict.blocked, to decide whether to stop. enforce answers "should I stop": it always stops on block, and it also honors fail_mode for challenge and unknown. blocked only answers "did the server say block", so code that checks blocked still lets challenge and unknown through even when fail_mode is "closed".

LangChain

Optional extra:

pip install alovia-watchdog[langchain]

WatchdogToolMiddleware gates every tool call through Watchdog before it runs, blocking off-mission or injected calls with a ToolMessage instead of letting the tool execute:

from langchain.agents import create_agent
from alovia_watchdog import Watchdog
from alovia_watchdog.integrations.langchain import WatchdogToolMiddleware

wd = Watchdog(api_key="wd_live_...")

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[WatchdogToolMiddleware(wd, agent="support-bot", session_id=lambda: chat_id)],
)

For async agent graphs, the middleware also exposes awrap_tool_call, LangChain calls it automatically wherever the graph runs async.

Checking tool results

Pass inspect_results=True and the middleware also checks what each tool returned before the model reads it. A result carrying an injected instruction is cleaned when it can be and withheld when it cannot:

WatchdogToolMiddleware(wd, agent="support-bot", session_id=lambda: chat_id, inspect_results=True)

Google ADK and Microsoft Agent Framework

The same result check is after_tool_callback (or async_after_tool_callback) in alovia_watchdog.integrations.google_adk, wired next to before_tool_callback, and inspect_results=True on WatchdogFunctionMiddleware in alovia_watchdog.integrations.agent_framework:

LlmAgent(..., before_tool_callback=before_tool_callback(wd, agent="support-bot"),
         after_tool_callback=after_tool_callback(wd, agent="support-bot"))
WatchdogFunctionMiddleware(wd, agent="support-bot", session_id=lambda: chat_id, inspect_results=True)

Any other framework

guard_tool_call and guard_tool_result wire Watchdog into any framework's own before-tool and after-tool points:

from alovia_watchdog.integrations.hook import guard_tool_call, guard_tool_result

guard_tool_call(wd, name, args, agent="support-bot", session_id=chat_id)           # raises WatchdogBlocked to stop
text = guard_tool_result(wd, name, result, agent="support-bot", session_id=chat_id)  # hand `text` to the model

Metadata

Release files for alovia-watchdog 0.5.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 alovia-watchdog 0.5.0
File Size Uploaded Provenance Actions
alovia_watchdog-0.5.0.tar.gz 29.8 kB Without provenance Details for alovia_watchdog-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alovia-watchdog 0.5.0
File Interpreter ABI Platform Actions
alovia_watchdog-0.5.0-py3-none-any.whl Python 3 none any Details for alovia_watchdog-0.5.0-py3-none-any.whl

Total release size: 53.9 kB

Release files / alovia_watchdog-0.5.0.tar.gz

Download URL alovia_watchdog-0.5.0.tar.gz
Size 29.8 kB
Tags Source
SHA-256 checksum
How to use checksums
2d837472892d09b3030603af6dd833db664ce0f713e5d37d6e39eaa7f771858b
BLAKE2b-256 checksum
How to use checksums
d3d1025ef6db859aa18fcb8d28616651c6422aed8b3bd53343fb1ff788753cf5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / alovia_watchdog-0.5.0-py3-none-any.whl

Download URL alovia_watchdog-0.5.0-py3-none-any.whl
Size 24.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e40b36231bd4d221eae70ef6af7eba2cf0edf5d1e6c252a915455ce8f8c9e98
BLAKE2b-256 checksum
How to use checksums
526a289821bbdea78b55e18a11e543cd8fd1778576bc410301e5064090b847c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for alovia-watchdog 0.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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