Playbook: Agent Connectivity

Agent Connectivity

When to use: Customer reports “agent offline”, “no data flowing”, or Quick Triage found agent disconnected.

Diagnosis Steps

1. Check Connection History

MCP: get_connection_history
  workspace_id: "<workspace_id>"

Look for patterns — intermittent disconnects, auth failures, version mismatches.

2. Remote Agent Health Check

MCP: remote_debug
  workspace_id: "<workspace_id>"
  command: "agent_health"

3. Check Agent Logs

MCP: remote_debug
  workspace_id: "<workspace_id>"
  command: "agent_logs"
  params: { "lines": 100 }

Common error patterns:

• 401 Unauthorized — API key expired or revoked
• WebSocket connection failed — network/firewall issue
• Capability negotiation failed — version mismatch

4. Verify Agent Version

MCP: remote_debug
  workspace_id: "<workspace_id>"
  command: "agent_version"

Check against the minimum supported version. Old agents may lack required capabilities.

Common Fixes

Issue	Fix
Expired API key	Customer regenerates in Settings > API Keys
Firewall blocking WebSocket	Customer needs to allow outbound WSS to *.pulsestream.ai:443
Old agent version	Customer upgrades Helm chart: helm upgrade pulsestream-agent ...
Pod in CrashLoopBackOff	Check K8s events — likely missing Secret or ConfigMap

Escalation

If the agent is connected but data isn’t flowing, check the telemetry pipeline — this may be an analysis engine issue, not connectivity.