Compress agent traffic with Headroom using Kong Operator

1. Create a proxy token. The data plane sends it to Headroom on every call:

   export HEADROOM_TOKEN=$(openssl rand -hex 16)
   kubectl create secret generic headroom-token -n kong \
     --from-literal=token="$HEADROOM_TOKEN"

   Copied!

2. Deploy Headroom and its Service:

   echo '
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: headroom
     namespace: kong
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: headroom
     template:
       metadata:
         labels:
           app: headroom
       spec:
         containers:
           - name: headroom
             image: ghcr.io/headroomlabs-ai/headroom:latest
             args: ["--host", "0.0.0.0", "--port", "8787"]
             env:
               - name: HEADROOM_COMPRESS_ALLOW_REMOTE
                 value: "1"
               - name: HEADROOM_PROXY_TOKEN
                 valueFrom:
                   secretKeyRef:
                     name: headroom-token
                     key: token
             ports:
               - containerPort: 8787
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: headroom
     namespace: kong
   spec:
     selector:
       app: headroom
     ports:
       - port: 8787
         targetPort: 8787
   ' | kubectl apply -f -

   Copied!

   By default, Headroom only answers /v1/compress for loopback callers and returns 404 to everyone else. HEADROOM_COMPRESS_ALLOW_REMOTE=1 lets the data plane pod call it, and HEADROOM_PROXY_TOKEN rejects any caller without the token with 401.

3. Wait for Headroom to be ready:

   kubectl rollout status deployment/headroom -n kong --timeout=5m

   Copied!

Headroom compresses tool output, JSON, code, and logs. It doesn’t compress plain user prose by default, and it leaves blocks under about 500 tokens alone. A short chat message will show no change, so the test request carries a large tool result: 400 structured log entries returned by a fetch_logs tool call.

1. Build the request:

   jq -n '[range(400) | {id: ., level: (if . % 7 == 0 then "ERROR" else "INFO" end),
     service: "checkout", latency_ms: ((. * 37) % 900),
     msg: (if . % 7 == 0 then "upstream timeout" else "request completed" end)}]' > logs.json
   
   jq -n --rawfile logs logs.json '{
     model: "gpt-4o-mini",
     messages: [
       {role: "user", content: "Which service produced errors in these logs?"},
       {role: "assistant", content: null, tool_calls: [{id: "call_1", type: "function",
         function: {name: "fetch_logs", arguments: "{\"window\":\"1h\"}"}}]},
       {role: "tool", tool_call_id: "call_1", content: $logs}
     ]}' > request.json

   Copied!

2. Send the request before you create the AI Prompt Compressor Policy and note the prompt tokens OpenAI reports:

   curl -s http://$AIGW_HOST:8000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d @request.json | jq '.usage.prompt_tokens'

   Copied!

   In this example, this request should use about 16,900 prompt tokens.

1. Store the AI Policy configuration in a Secret. Kong Operator reads the whole AI Policy config from the Secret key, as YAML or JSON, so the proxy token never appears in the AIGatewayPolicy. The konghq.com/secret=true label lets Kong Operator read the Secret:

   cat > headroom-config.yaml <<EOF
   provider: headroom
   compressor_url: http://headroom.kong.svc.cluster.local:8787/v1/compress
   timeout: 45000
   keepalive_timeout: 60000
   stop_on_error: true
   log_text_data: false
   headroom:
     proxy_token: ${HEADROOM_TOKEN}
     ssl_verify: false
     session_id_headers:
       - x-claude-code-session-id
       - x-claude-code-agent-id
       - thread-id
       - session-id
   EOF
   
   kubectl create secret generic headroom-policy-config -n kong \
     --from-file=config.yaml=headroom-config.yaml
   kubectl label secret headroom-policy-config -n kong konghq.com/secret=true

   Copied!

2. Create the AI Policy and apply it to every AI Model:

   echo '
   apiVersion: aiconfiguration.konghq.com/v1alpha1
   kind: AIGatewayPolicy
   metadata:
     name: headroom-compressor
     namespace: kong
   spec:
     aiGatewayRef:
       type: namespacedRef
       namespacedRef:
         name: my-ai-gateway-cp
     apiSpec:
       name: headroom-compressor
       displayName: Headroom compressor
       type: ai-prompt-compressor
       enabled: Enabled
       global: Enabled
       config:
         type: secretRef
         secretRef:
           name: headroom-policy-config
           key: config.yaml
   ' | kubectl apply -f -

   Copied!

3. Wait for the AI Policy to be reconciled:

   kubectl wait aigatewaypolicy/headroom-compressor -n kong \
     --for=condition=Programmed=True \
     --timeout=5m

   Copied!

1. Send the same request again, this time with a session header. Use a fresh session ID, because Headroom compresses a repeated tool result more aggressively within the same session:

   curl -s http://$AIGW_HOST:8000/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "x-claude-code-session-id: $(uuidgen)" \
     -d @request.json | jq '.usage.prompt_tokens'

   Copied!

   The prompt token count drops from about 16,900 in the baseline to about 4,500.

2. To confirm the savings from Headroom’s side, forward Headroom’s port and read its statistics:

   kubectl port-forward -n kong deployment/headroom 8787:8787 > /dev/null 2>&1 &
   curl -s http://localhost:8787/stats -H "Authorization: Bearer $HEADROOM_TOKEN" \
     | jq '{compress_calls: .requests.by_provider.compress, tokens_saved: .tokens.saved}'

   Copied!