The Complete Production SOP: How to Deploy and Run Helicone AI Proxy Semantic Caching & Rate Limiting in Autonomous AI Agents

---
name: "helicone-llm-proxy-caching"
description: "Accelerate LLM applications and cut costs with Helicone proxy semantic caching."
metadata:
  author: "Helicone"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "setup helicone proxy"
  - "enable semantic caching helicone"
  - "rate limit users helicone"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Helicone AI Proxy Semantic Caching & Rate Limiting Rules
1. Target baseURL must strictly point to 'https://oai.helicone.ai/v1'.
2. Mandatory headers: 'Helicone-Auth': 'Bearer ${HELICONE_API_KEY}'.
3. Cache headers: 'Helicone-Cache-Enabled': 'true', optional 'Helicone-Cache-Bucket-Max-Age'.
4. Rate limit headers: 'Helicone-RateLimit-Policy': '10;w=60;u=cents' or request count.

import OpenAI from 'openai';

export const getHeliconeClient = (userId?: string) => {
  const heliconeKey = process.env.HELICONE_API_KEY;
  if (!heliconeKey) {
    throw new Error('HELICONE_API_KEY environment variable is missing');
  }

  return new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://oai.helicone.ai/v1',
    defaultHeaders: {
      'Helicone-Auth': `Bearer ${heliconeKey}`,
      'Helicone-Cache-Enabled': 'true',
      'Helicone-Cache-Bucket-Max-Age': '86400',
      ...(userId ? { 'Helicone-User-Id': userId } : {}),
    },
  });
};

Setup helicone proxy for our OpenAI chat completion service. Enable semantic caching with a 24-hour TTL and implement user rate limiting of 50 requests per minute.

import { describe, it, expect } from 'vitest';
import { getHeliconeClient } from '../src/lib/llmClient';

describe('Helicone Client Configuration', () => {
  it('should instantiate OpenAI client with Helicone proxy headers', () => {
    process.env.HELICONE_API_KEY = 'test-key';
    const client = getHeliconeClient('usr_test_123');
    expect(client.baseURL).toBe('https://oai.helicone.ai/v1');
    expect(client.defaultHeaders['Helicone-Auth']).toBe('Bearer test-key');
    expect(client.defaultHeaders['Helicone-Cache-Enabled']).toBe('true');
    expect(client.defaultHeaders['Helicone-User-Id']).toBe('usr_test_123');
  });
});