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

Metadata

Release files for alovia-watchdog 0.6.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.6.0
File Size Uploaded Provenance Actions
alovia_watchdog-0.6.0.tar.gz 34.1 kB Without provenance Details for alovia_watchdog-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 62.0 kB

Release files / alovia_watchdog-0.6.0.tar.gz

Download URL alovia_watchdog-0.6.0.tar.gz
Size 34.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cdb6e38dbb7a5e3f46df174278593b949d9e7d0c4b4b9eaa7cdfd129bcf59af8
BLAKE2b-256 checksum
How to use checksums
49a39133bc29c3c5c251958fd9430953342b9dc643a50f632987f71319e6b9a0
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.6.0-py3-none-any.whl

Download URL alovia_watchdog-0.6.0-py3-none-any.whl
Size 27.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eca5ec7a0b32b435efa2070a0a52ef79bbb6950fb6f5f5813e1e493509a067ba
BLAKE2b-256 checksum
How to use checksums
3e551c14cd61000104cf357bdbb380d9bc501c35ce61e33c074121fad82399ee
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.6.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