Connect your first Python job.

This quickstart is for a developer with access to an owner-operated Watchdog deployment and its source checkout. It verifies one small Python job. No model API key, sidecar or change to your scheduler is needed for the synthetic example.

1. Get the deployment details.

Create an account using Google or email/password when sign-in is enabled on your deployment. Email signup requires verification. Existing pilot operators can still use administrator access. Ask the deployment owner for the SDK source; there is no verified package-registry installation in this release. Create a separate telemetry key for your agent code. Never put a password, session cookie, or administrator token in the agent.

1. Open the dashboard and register an unscheduled job with slug daily-report.
2. For this small example, set maximum runtime to 60 seconds and progress timeout to 120 seconds. Keep cancellation and agent retry off, the control URL blank, and required outcomes empty.
3. In Connect, create a telemetry API key. Use a dedicated key for your environment; keys are scoped to workspace telemetry, not individual jobs.

2. Install from the supplied source checkout.

Use Python 3.10 or later. From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install ./sdk

Set WATCHDOG_URL to your deployment’s HTTPS origin and WATCHDOG_API_KEY to the telemetry key using your environment or secret manager. Keep both out of source control and avoid putting keys directly into shell history. The import is watchdog_agent; do not install the unrelated filesystem package named watchdog.

from watchdog_agent import Watchdog

with Watchdog() as watchdog:
    if not watchdog.enabled:
        raise RuntimeError("Set WATCHDOG_API_KEY first")
    with watchdog.run("daily-report", cancellable=False):
        print("Synthetic job completed")
    if not watchdog.flush(timeout=10):
        raise RuntimeError("Telemetry did not drain")
    if watchdog.stats["dropped"] or watchdog.stats["errors"]:
        raise RuntimeError("Inspect telemetry delivery")

The run context emits a start and a normal completion, or reports failure while preserving an exception. The outer client drains its bounded queue. A killed process cannot guarantee that pending events arrive. Normal exit is lifecycle success, not proof of a useful business result.

3. Verify the received run.

Open Runs in the dashboard and inspect the new execution. Confirm that both run.started and run.completed arrived and that the job is the one you registered. A printed message or successful SDK construction is not proof of delivery.

Replace the print statement with your agent invocation after this check. For longer jobs, use realistic runtime and progress limits: the default progress timeout is 300 seconds. A lifecycle-only job that legitimately runs longer needs a larger progress timeout or explicit meaningful progress signals.

# Emit these only after the corresponding work succeeds.
run.progress("Research complete", completed=3)
run.tool("record.read", arguments={"record_id": "synthetic-1"})
run.outcome("report_saved", success=True)
# Only if you know the cost of this request:
run.usage(model="configured-model", cost_usd=0.02)

Use these snippets inside an active with watchdog.run(...) as run: context. They are independent optional signals, not a claim that the example saved a report. Tool arguments are fingerprinted locally. Progress messages and explicit metadata are transmitted: do not include prompts, secrets or customer payloads. Costs are values you report; token counts alone do not calculate spend in this version.

4. Verify your alert path with a test job.

In Settings, enable a destination you control. Generic webhooks use a generated signing secret; the receiver must verify the exact payload signature. Slack, Resend email and PagerDuty require their own destination details or credentials. No destination is enabled by default.

Use a separate, clearly named synthetic job with a short runtime limit. Report a start without a completion, stop local schedulers when testing hosted Cron, and leave the dashboard closed. Confirm an independent scheduler heartbeat and the matching received alert. Keep automatic cancellation and agent retry disabled.

The Failure Lab tests detectors locally with all alert destinations disabled. The supplied repository’s docs/DEMONSTRATION.md separately explains signed webhook delivery testing; docs/CLOUDFLARE_DEPLOYMENT.md covers native hosted checks. Do not confuse an incident in the dashboard with a delivered alert.

Optional OpenAI Agents support.

python -m pip install './sdk[openai]'

The tested extra pins openai-agents==0.8.4 and openai==2.19.0. It supplies WatchdogHooks to an existing Runner call. Hosted provider tools and errors converted into result strings may require explicit instrumentation. Hooks do not infer business progress or outcomes. See the supplied sdk/ADAPTER_VERIFICATION.md before upgrading dependencies.

Next, declare an expected schedule or instrument repeated tool work.