Troubleshooting - agent offline, quick checklist

A quick checklist for agent offline and stale-state issues, with a link to the full diagnostics guide.

1 min read · verified against [email protected]

When an agent is in stale state (stopped reporting) or never-connected, follow this guide to diagnose and resolve the issue.

Quick checklist

Before diving into detailed diagnostics, verify these basics:

✅ The application with the agent is running
✅ The agent library is installed (uv add fastapi-guard guard-agent)
✅ guard_lifespan is passed to your FastAPI() constructor
✅ The agent has a valid API key and project ID in SecurityConfig
✅ Outbound HTTPS (port 443) to api.guard-core.com is not blocked

Common fixes

Check agent configuration

config = SecurityConfig(
    enable_agent=True,
    agent_api_key="<your-api-key>",
    agent_project_id="<your-project-id>",
)

app = FastAPI(lifespan=guard_lifespan)
app.add_middleware(SecurityMiddleware, config=config)

Enable agent debug logging

import logging
logging.getLogger("guard.agent").setLevel(logging.DEBUG)

Next steps

For full step-by-step diagnostics, see the detailed agent offline guide
For an overview of all agent health states, see the dashboard documentation, available with an account