How to Monitor Pydantic AI with Vigilmon

Pydantic AI is a Python agent framework built by the team behind Pydantic — bringing type-safe, validated AI agent development to production Python applications. It supports OpenAI, Anthropic, Gemini, Groq, and Mistral through a unified API, and uses Pydantic models for structured input/output validation. When you deploy Pydantic AI agents as HTTP services, you need uptime monitoring to know when those services fail. Vigilmon gives you HTTP health checks, heartbeat monitoring for background agents, and instant alerts so you can keep type-safe AI agents reliably available.

What You'll Set Up

• HTTP uptime monitor for your Pydantic AI agent API
• Cron heartbeat for batch agent workers running on a schedule
• SSL certificate expiry monitoring for production endpoints
• Alert channels for on-call notification

Prerequisites

• Pydantic AI installed (pip install pydantic-ai) with an agent deployed as a service
• An HTTP endpoint serving your agent (FastAPI, Flask, or similar)
• A free Vigilmon account

Step 1: Add a Health Endpoint to Your Pydantic AI Service

Pydantic AI agents integrate cleanly with FastAPI because both are Pydantic-native. Add a /health route alongside your agent endpoint:

from fastapi import FastAPI
from pydantic import BaseModel
from pydantic_ai import Agent

app = FastAPI()

agent = Agent(
    "openai:gpt-4o",
    system_prompt="You are a helpful assistant.",
)

class AgentRequest(BaseModel):
    message: str

class AgentResponse(BaseModel):
    reply: str

@app.get("/health")
async def health():
    return {"status": "ok", "framework": "pydantic-ai"}

@app.post("/agent/run", response_model=AgentResponse)
async def run_agent(request: AgentRequest):
    result = await agent.run(request.message)
    return AgentResponse(reply=result.data)

The /health endpoint gives Vigilmon a fast, cheap probe that doesn't consume LLM tokens — it confirms the service process is up and the FastAPI app initialized without burning API quota on every check.

Step 2: Monitor Your Pydantic AI Agent API

With the health endpoint in place, add a Vigilmon monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your agent's health URL: https://api.yourdomain.com/health
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If you run multiple agents (different models or system prompts) behind separate services, add a Vigilmon monitor for each. Pydantic AI's type system makes it easy to version agent contracts — monitor each version's endpoint separately so you can track which version has problems.

Step 3: Validate Structured Outputs in Your Health Check

One of Pydantic AI's strengths is validated structured outputs via Pydantic models. You can extend your health check to verify the agent's output schema is still working:

from pydantic import BaseModel
from pydantic_ai import Agent

class HealthCheckOutput(BaseModel):
    status: str
    version: str

health_agent = Agent(
    "openai:gpt-4o",
    result_type=HealthCheckOutput,
    system_prompt="Return status=ok and version=1.0",
)

@app.get("/health/deep")
async def deep_health():
    try:
        result = await health_agent.run("health check")
        return {"status": result.data.status, "version": result.data.version}
    except Exception as e:
        return JSONResponse(status_code=503, content={"status": "error", "detail": str(e)})

Use /health for Vigilmon's lightweight 1-minute probes and /health/deep for less frequent deep checks (every 5 minutes) that validate the full agent pipeline.

Step 4: Heartbeat Monitoring for Scheduled Agent Workers

Pydantic AI agents running as batch processors, scheduled summarizers, or periodic classification jobs need heartbeat monitoring since they have no persistent HTTP listener. Set up a cron heartbeat in Vigilmon:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your schedule (e.g. 60 minutes for an hourly job).
3. Copy the heartbeat URL.

Ping the heartbeat after each successful agent run:

import httpx
from pydantic_ai import Agent
from pydantic import BaseModel

class ClassificationResult(BaseModel):
    category: str
    confidence: float

classifier = Agent(
    "anthropic:claude-3-5-sonnet-latest",
    result_type=ClassificationResult,
    system_prompt="Classify the input text into a category.",
)

async def run_batch_classification(texts: list[str]):
    for text in texts:
        result = await classifier.run(text)
        store_result(result.data)

    # Signal successful completion to Vigilmon
    async with httpx.AsyncClient() as client:
        await client.get("https://vigilmon.online/heartbeat/abc123", timeout=5)

If the agent raises a validation error or the LLM provider returns an unexpected response, the exception propagates before the heartbeat ping — and Vigilmon alerts after the missed interval.

Step 5: SSL Certificate Alerts

For production Pydantic AI APIs served over HTTPS, add SSL monitoring:

1. Open the HTTP monitor for your agent endpoint (created in Step 2).
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Certificate expiry breaks HTTPS connections silently from the server's perspective — Vigilmon catches it before your agent clients start seeing TLS handshake failures.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 — LLM provider cold starts and rate limit retries can cause transient probe timeouts.
3. For staging environments, use a separate alert channel with lower severity so production pages don't fire on staging issues.

Use the Vigilmon API to add maintenance windows around deployments:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 3}'

# Deploy updated agent
uvicorn app:app --reload

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP endpoint | /health | Service crash, startup failure | | Deep health check | /health/deep | Agent pipeline failure, schema break | | Cron heartbeat | Heartbeat URL | Batch worker crash, missed schedule | | SSL certificate | API domain | Certificate expiry |

Pydantic AI brings type safety and testability to production AI agents — Vigilmon brings the same rigor to their uptime. With health checks on every agent endpoint and heartbeats on every scheduled worker, you'll know the moment a type-safe agent stops being available.