Alovia AIDocsOpen dashboard

Set up Watchdog

Watchdog protects your AI agents while they run. Your app checks each incoming message with Watchdog before your agent acts on it, and everything caught shows up in your dashboard. This page takes you from nothing to a guarded agent with a mission.

What Watchdog catches

Prompt injection
A message tells your agent to ignore its instructions, leak data, or act for someone else. Watchdog spots it before your agent reads it.
Off-mission work
You describe what each agent is for. Anything outside that mission is blocked, or recorded, your choice.
Runaway agents
An agent that starts behaving differently from its history is frozen, along with the agents it delegated to, until you release it.

Connect your first agent

1
Create a fleet and copy its key
In your dashboard open Watchdog, choose New, then New Watchdog fleet. Name it and choose Create fleet. The key starts with wd_live_ and is shown once. Copy it now and keep it in an environment variable, never in your code.
2
Install the package
Python 3.9 or newer. One package, no other setup.
pip install alovia-watchdog
3
Guard the function your agent takes messages through
Every message passes through Watchdog before your agent reads it. A blocked message raises WatchdogBlocked, so the function never runs on it. session_id is the id of the conversation, it lets Watchdog see across a user's turns, so always pass one.
from alovia_watchdog import Watchdog, guard_input

wd = Watchdog(api_key="<your fleet key>")

@guard_input(wd, agent="support-bot", session_id=lambda: current_chat_id())
def handle(message):
    ...
If a decorator does not fit, ask Watchdog directly. Decide with verdict.enforce, never verdict.blocked: enforce also stops when Watchdog could not decide, blocked only says the answer was block.
verdict = wd.check(message, agent="support-bot", session_id=chat_id)
if verdict.enforce:
    return "I can't help with that."
4
Send one message and watch it appear
Run your agent and send it any message. Within a few seconds it shows up under Agents in your dashboard with its first check. Or check the connection from a terminal first:
python -c "from alovia_watchdog import Watchdog; print(Watchdog(api_key='<your fleet key>').check('hello', agent='support-bot').verdict)"
5
Give the agent a mission
Open Missions and choose Set mission next to your agent. Describe what it is allowed to do in a sentence or two, then pick a mode. Monitor records anything off-mission without blocking it, use it for the first week. Enforcing blocks it. An agent with no mission keeps working for 15 minutes after its first check, then is put on hold until you set one.
If it does not work
The key is empty or shows as dots
The key is shown once when the fleet is created. In the dashboard open Connect agent and choose Rotate, then put the new key in your environment variable. The old key stops working.
The agent never appears in the dashboard
Run the terminal check from step 4. An authentication error means the key is wrong. A verdict means the key works and the decorator is not on the function your messages actually go through.
Every message is blocked and the error says failing closed
Your app could not reach Watchdog and stopped rather than let the message through. Check outbound network access from where your agent runs. To keep working while you look, start Watchdog with fail_mode="open".
Ordinary messages are blocked
The mission is narrower than the work. Widen it in Missions, or switch it to Monitor until you have seen a clean run.
Blocks show in Findings but the agent still acts
Your code checks verdict.blocked. Switch to verdict.enforce.

Frameworks

If your agent is built on a framework, guard its tool calls instead of one function. Pick yours for the exact lines.

pip install "alovia-watchdog[langchain]"
Add the middleware to your agent
from langchain.agents import create_agent
from alovia_watchdog import Watchdog
from alovia_watchdog.integrations.langchain import WatchdogToolMiddleware

wd = Watchdog(api_key="<your fleet key>")

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[WatchdogToolMiddleware(wd, agent="support-bot", session_id=lambda: chat_id)],
)
Every tool call passes through Watchdog before it runs. A blocked call comes back to the model as a tool error, so the run continues without that tool.

Gateways

If partner agents or MCP clients call your agent over the network, Watchdog can sit in front of it, the same way Shield sits in front of your website. Every request is checked before it reaches your server. Both gateways only forward to a host you have proved you own.

1
Prove you own the host
In your Watchdog fleet open Settings, then Verified agent hosts. Add the domain your agent runs on. Add the TXT record shown at your DNS provider, then choose Check. A CNAME option is there if your provider blocks TXT records.
2
Enter your server's address
In MCP server we protect, enter the address of your MCP server. For an agent partners call directly, enter it under Agent URL instead.
3
Turn the gateway on
Turn on MCP gateway, or Gateway mode for partner traffic. To watch before anything is blocked, turn on Pause enforcement for the first week.
4
Point clients at the gateway address
Copy Address for MCP clients, or Address for partner agents, and hand that out instead of your server's own address. Every tool call now passes through Watchdog on the way in.
If it does not work
The gateway settings are not there
They appear once a host is verified. Finish step 1 first.
Check does not pass
DNS can take up to an hour to spread. Confirm the record name and value match exactly, with no extra quotes, then Check again.
The gateway answers that the host is not verified
The address you entered is on a domain other than the one you verified. Verify that domain too, or enter an address on the verified one.
Approved actions stay held and then expire
Approvals are recorded by the API and consumed by the Watchdog runtime, so both must share one Redis. When the runtime has no REDIS_URL, or a different one, it never sees an approval; the Needs approval lane in Review says so above the cards. Give the runtime the same REDIS_URL as the API.
An agent is frozen after many held actions
An agent that parks more than 20 distinct actions for approval inside 15 minutes is refused further holds, and frozen when auto-quarantine is on, so it cannot flood the approval lane. Clear the lane, then release the agent from Agents.
A partner agent keeps re-sending a held message
It does not have to. A held message comes back as a task in state auth-required. The agent can call tasks/get with that task's id: it gets the same answer while the item waits, the delivered answer once you approve, and a rejected task if you reject it or the window closes. Re-sending the same message after approval also still works.
An MCP tool call answers held at once instead of waiting
Waiting is off unless the fleet sets heldWaitSeconds through the API (up to 600, never longer than the approval window). With it set, a client that accepts a streamed reply is held on the stream until you decide or the wait ends, then gets the tool's answer, a rejection, or the usual held reply. Many MCP clients give up on a request after about a minute unless they asked for progress updates, so keep the wait under that for them.
Approve asks for a two-factor code
The fleet requires step-up approval (approvalStepUp, set through the API, and only by an owner with two-factor turned on). Enter the current code from your authenticator app. Five wrong codes pause step-up approvals for 15 minutes. Rejecting never needs the code.

Boundary scan

Boundary scan looks at your agent's public address from the outside, the way an attacker would: MCP endpoints left open, tools that answer without a login, and agent cards that give away more than they should. Choose Boundary scan on the Agents view, confirm the address, then scan. It needs a public address on a host you have verified, and results land in Findings.

Standards coverage

Watchdog publishes what it defends against in the two vocabularies a security review uses: the OWASP Top 10 for Agentic Applications (2026) and MITRE ATLAS. Both are read from the detectors and controls that run rather than from a written list. In your fleet open Settings, then Standards coverage: each OWASP risk shows the detectors and the controls behind it, marking the ones you turn on yourself, and each ATLAS technique shows its detectors; both show what fired on your account in the last 30 days, and every finding in the Findings view carries its technique id with the OWASP risk on hover. Download layer gives you an ATT&CK Navigator layer: open the ATLAS Navigator, choose Open existing layer, upload the file, and the covered techniques light up over the matrix, each naming the detector behind it. Covered means a detector or control exists and runs for that item; it is not a certification and it says nothing about attacks that detector misses. Findings exported to your SIEM carry the same technique and risk ids, so you can pivot on them there.

Key safety

Keep the key out of your code
Read it from an environment variable. Anyone with the key can send checks as your fleet.
Rotate it if it leaks
Open Connect agent and choose Rotate. The old key stops working the moment the new one is issued, so update your environment variable in the same change.
One key per fleet
Agents in the same fleet share a key and a dashboard. Give separate products separate fleets.
Stuck on something this page does not answer? Tell us, we read every note.