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)

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)

Source distribution for alovia-watchdog 0.7.0
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)

Table of built distributions (wheels) for alovia-watchdog 0.7.0
File Interpreter ABI Platform Actions
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.

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