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)
Approvals
Some actions should wait for a person, such as a refund or an account change. Put those tools on the task's lease. Mint the lease on your deploy path with the deploy key and give it to the agent's client; every check that names a tool carries it.
from alovia_watchdog import Watchdog, WatchdogBlocked
deploy = Watchdog(api_key=DEPLOY_KEY)
lease = deploy.mint_lease("support-bot", "ticket-4812", ttl_seconds=1800,
allowed_tools=["read_ticket", "refund"],
approval_required=["refund"],
amount_field="amount", approval_above=100)["lease"]
wd = Watchdog(api_key=RUNTIME_KEY, lease=lease)
v = wd.check("refund the order", agent="support-bot",
tool_name="refund", tool_args={"ticket_id": "4812", "amount": 250})
if v.held:
v = wd.wait_for_approval(v, timeout=600)
if v.enforce:
raise WatchdogBlocked(v)
A refund of 100 or less runs without asking. A larger one, or one whose amount Watchdog cannot read, shows up in Review under Needs approval. wait_for_approval checks whether someone decided, every two seconds at first and less often the longer it waits; once approved it sends the same call again, and that one call goes through. A rejection, a closed approval window, or no decision before the timeout comes back as a block. A held call never runs on its own, even with fail_mode="open". The framework integrations stop on a held call like on any block; call wait_for_approval yourself where you want to wait.
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
From 0.7.0 the model gets the inspected projection: hidden comments, invisible characters and encoded instructions are withheld, and a later call that uses a value from them is refused. Pass source_kind, source and task_id so findings name where the data came from, and metadata for a document's Title, Author, Subject and Keywords. Images are not read; pass the text you extracted.
Metadata
Release files for alovia-watchdog 0.7.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 |
|---|---|---|---|---|
| alovia_watchdog-0.7.0.tar.gz | 36.5 kB | Without provenance | Details for alovia_watchdog-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alovia_watchdog-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for alovia_watchdog-0.7.0-py3-none-any.whl |
Total release size: 66.5 kB
Release files / alovia_watchdog-0.7.0.tar.gz
| Download URL | alovia_watchdog-0.7.0.tar.gz |
|---|---|
| Size | 36.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bce5478f47d38d96f31c07d620b0e171c37117fa5af1c2dd901450da6cab291a
|
|
BLAKE2b-256 checksum How to use checksums |
b579d0cc29e17c51873c5f87952b47c1c366a012ee6a7f6607397f36863e3952
|
| 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.7.0-py3-none-any.whl
| Download URL | alovia_watchdog-0.7.0-py3-none-any.whl |
|---|---|
| Size | 30.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
45e4aec3bc8bc6ffd114fbd8a6367082c2b857134aa3b8026b796550de85c3d5
|
|
BLAKE2b-256 checksum How to use checksums |
95738a23b6fcbdbbfa375ea030b42607819e69c487893d6da810a36973acd34e
|
| 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.7.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.