Common Support Scenarios

Quick reference for the scenarios you’ll face most often. Each scenario has the symptom, cause, and fix.

---

Client says “my agent is being blocked”

Symptom: Agent gets HTTP 403 / PolicyBlockError on requests that should be allowed.

Diagnose:

1. Check the error response. It includes blocked_by (which step) and reason:

   {"error": {"step": "detect_pii", "reason": "PII detected in request"}}

2. Check the audit trail for the agent:

   curl -H "Authorization: Bearer tp_admin_..." \
     http://localhost:9620/v1/audit?agent=<agent-name>&limit=10

3. Check if mode=observe works (logs but doesn’t block):

   agent = Agent(url, key, flags={"mode": "observe"})

Common causes:

Blocked by	Likely cause	Fix
detect_pii	Agent prompt contains names, emails, phone numbers	Use pii=mask flag, or tune PII patterns in pipeline config
detect_injection	Prompt looks like injection (common with system prompts)	Add prompt hash to allowlist, or lower injection sensitivity
check_exfiltration	Agent tries to send data to external URL	Add URL to allowed domains in pipeline config
check_budget	Agent exceeded budget cap	Increase budget flag: budget=standard or budget=unlimited
check_tools	Agent called a tool not in its allowed list	Update agent’s tool allowlist via admin API

Escalation: If the block is a false positive, see Pipeline Tuning.

---

Client wants to add a new LLM provider

Steps:

1. Get the provider API key from the client
2. Store it in the TapPass vault:

   tappass vault set ANTHROPIC_API_KEY=sk-ant-...

3. The provider is immediately available. Agents use it by specifying the model:

   response = agent.chat("Hello", model="claude-3-5-sonnet-20241022")

No restart needed. Provider keys are hot-reloaded from the vault.

Supported providers: OpenAI, Anthropic, Azure OpenAI, Google Gemini, AWS Bedrock, Ollama, vLLM, LM Studio.

---

Client wants to see audit logs

Option 1: Dashboard (recommended for CISOs)

Direct them to app.tappass.ai (or their self-hosted dashboard URL). Login via SSO.

Option 2: API

# Last 50 events for a specific agent
curl -H "Authorization: Bearer tp_admin_..." \
  "http://localhost:9620/v1/audit?agent=my-agent&limit=50"

# Events in a time range
curl -H "Authorization: Bearer tp_admin_..." \
  "http://localhost:9620/v1/audit?after=2026-03-01T00:00:00Z&before=2026-03-14T00:00:00Z"

# Only blocked events
curl -H "Authorization: Bearer tp_admin_..." \
  "http://localhost:9620/v1/audit?blocked=true"

Option 3: SIEM export

Configure webhook in the dashboard or via env var:

TAPPASS_SIEM_WEBHOOK_URL=https://your-siem.example.com/webhook

---

Client wants to register a new agent

Via CLI (if they have server access):

tappass agents add finance-bot --preset=regulated --flags="pii=mask,email=block"

Via Admin API (recommended):

curl -X POST http://localhost:9620/v1/agents \
  -H "Authorization: Bearer tp_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "finance-bot",
    "preset": "regulated",
    "flags": {"pii": "mask", "email": "block"}
  }'

Response includes the agent’s API key. Send it to the developer securely (not over email).

---

Client reports slow responses

Diagnose:

1. Check health endpoint:

   curl http://localhost:9620/health/detailed \
     -H "Authorization: Bearer tp_admin_..."

2. Look for slow pipeline steps in audit trail (each step has a duration_ms field)
3. Common bottlenecks:
   • LLM judge step: uses an LLM call for classification. Disable or switch to a faster model
   • PII detection: Presidio model loading on first call (cold start). Subsequent calls are fast
   • OPA: Check if OPA sidecar is healthy: curl http://localhost:8181/health

Fixes:

Bottleneck	Fix
LLM judge slow	Use TAPPASS_LLM_JUDGE_MODEL=gpt-4o-mini (faster, cheaper)
PII cold start	Pre-warm on server start (already done in production)
OPA timeout	Check OPA sidecar health and restart if needed
High latency on all requests	Check if Redis is connected (TAPPASS_KV_URL). Without it, each worker loads state independently

---

Server health check fails

Symptom: /health/ready returns 503.

Check each dependency:

# PostgreSQL
docker compose exec postgres pg_isready
# Redis
docker compose exec redis redis-cli ping
# OPA
curl http://localhost:8181/health
# SPIRE
docker compose exec spire-agent /opt/spire/bin/spire-agent healthcheck

Common causes:

Dependency	Symptom	Fix
PostgreSQL down	”database connection failed”	docker compose restart postgres
Redis unreachable	Degraded mode (works but slow)	docker compose restart redis
OPA unreachable	All requests denied (fail-closed)	docker compose restart opa
SPIRE agent down	mTLS auth fails	docker compose restart spire-agent

---

Client wants to change pipeline configuration

Option 1: Switch preset

curl -X PATCH http://localhost:9620/v1/agents/finance-bot \
  -H "Authorization: Bearer tp_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"preset": "regulated"}'

Option 2: Custom overrides

curl -X PATCH http://localhost:9620/v1/agents/finance-bot/pipeline \
  -H "Authorization: Bearer tp_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "standard",
    "overrides": {
      "categories": {
        "pii_protection": {"enabled": true, "sensitivity": "high"},
        "cost_control": {"budget_usd": 10.0}
      }
    }
  }'

See Industry Configurations for per-vertical presets and Pipeline Tuning for advanced config.

---

Dashboard login not working

Symptom: User can’t log in to app.tappass.ai.

Check:

1. Is SSO configured? TAPPASS_SSO_PROVIDER must be set
2. Is their email domain in the allowed list? Check TAPPASS_SSO_ALLOWED_DOMAINS
3. Is the OAuth redirect URI correct? Must match exactly in Google/Azure/Okta config
4. Check SSO logs: docker compose logs tappass | grep SSO

Quick fix for testing: Generate a temporary auth token via CLI:

tappass auth token --email user@company.com --ttl 1h

---

Need to rotate an agent’s API key

curl -X POST http://localhost:9620/v1/agents/finance-bot/rotate-key \
  -H "Authorization: Bearer tp_admin_..."

The old key is immediately invalidated. Send the new key to the developer securely.

---

Emergency: suspected data breach via agent

1. Immediately block the agent:

   curl -X PATCH http://localhost:9620/v1/agents/compromised-bot \
     -H "Authorization: Bearer tp_admin_..." \
     -d '{"enabled": false}'

2. Pull full audit trail:

   curl "http://localhost:9620/v1/audit?agent=compromised-bot&limit=1000" \
     -H "Authorization: Bearer tp_admin_..." > audit-export.json

3. Check for data exfiltration: Look for classification: RESTRICTED or CONFIDENTIAL events
4. Follow the Incident Response Playbook