AI Pilot Troubleshooting

This guide covers common issues when configuring AI Pilot for per-bouncer LLM controls.

Quick triage

# Control Plane API
curl -sf http://localhost:8082/api/v1/health

# Bouncer health
curl -sf http://localhost:8080/health

# Plugin admin (live config source on bouncer)
curl -sf http://localhost:9998/pilot/config

Common issues

Smart Control Core Agent quick checks

Operational reference for SCCA credential hygiene, masking, Test connection, diagnostics, and trilingual prose lives in Smart Control Core Settings.

# 1) API health
curl -sf http://localhost:8000/health

# 2) Login and get token (replace creds)
TOKEN=$(curl -s http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<password>"}' | jq -r '.access_token')

# 3) Verify Smart CC settings
curl -s http://localhost:8000/v1/smart-cc/settings \
  -H "Authorization: Bearer $TOKEN" | jq .

# 4) Run one Smart CC turn
curl -s http://localhost:8000/v1/smart-cc/turn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"create draft for payroll MFA","context":{},"confirm_action":false}' | jq .

# 5) Run one code-assist turn with builder context
curl -s http://localhost:8000/v1/smart-cc/turn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"add principal and action checks using PIP risk score","context":{"active_page":"policy_lifecycle","editor_mode":"code","resource_id":"1","bouncer_id":"1","current_policy":{"name":"Draft","rego_excerpt":"package controlcore\n\ndefault allow = false"}},"confirm_action":false}' | jq .

Check for:

• intent and response_cards present.
• requires_confirmation=true for mutating draft flows.
• No provider/auth errors in evidence[] for normal draft generation.
• Code assist turns return intent=assist_policy_code with snippet/rationale evidence.

API-level validation

# Effective AI management for a bouncer
curl -H "Authorization: Bearer <token>" \
  http://localhost:8082/pep-config/pilot/bouncer/<pep_id>/ai-management

# Observability payload for charts
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8082/pep-config/pilot/bouncer/<pep_id>/observability?window=24h"

# Recent payload stream
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8082/pep-config/pilot/bouncer/<pep_id>/recent-payloads?limit=8"

Check that:

• use_global matches your UI state
• local_override exists when expected
• effective_config includes all prompt security fields

Runtime compile checks

AI Pilot compiles per-bouncer controls into bouncer runtime config.

Expected keys in effective pilot payload:

• ai_management
• compiled_targets.Bouncer intercept.content_safety
• compiled_targets.xds.cost_optimization

curl -sf http://localhost:9998/pilot/config | jq .

Prompt control tuning strategy

1. Start with strict controls in sandbox.
2. Use annotate mode for uncertain detections.
3. Promote high-confidence patterns to block.
4. Add explicit allowlist/trusted-domain exceptions.
5. Re-check audit events and false-positive rates weekly.

Routing

Troubleshooting: 404 from the bouncer on /v1/chat/completions usually means LLM routes are disabled for that PEP. Re-enable under Settings → AI Pilot → LLM Connections / Routing.

Guardrails & data protection

Token limits

Failover & resilience

MCP tools

Event streaming

By deployment mode

Gateway Mode

• Confirm clients and apps use the shared bouncer DNS/VIP as the LLM base URL — any direct provider DNS bypasses governance.
• Upstream errors (502) usually mean the shared TARGET_HOST or provider endpoint is unreachable from the bouncer network.
• Token limits across gateway replicas need shared Redis.

App-Embedded

• Confirm the application egress targets the local bouncer listen address, not the provider.
• Only the co-located app is in scope; other apps need their own embedded bouncer or a move to Gateway Mode.
• Loopback/TARGET_HOST mismatches are the most common cause of empty Activity with a healthy heartbeat.

Related: Deployment modes (AI Pilot) · Quick start

Related

• AI Pilot
• Prompt Security Controls
• Export & observability
• Admin user guide
• Global Troubleshooting