convex-agents-rate-limiting_skill

Overview

This skill enforces message frequency and token-usage limits to prevent abuse, control LLM costs, and ensure fair resource allocation. It provides configurable fixed-window and token-bucket policies for per-user and global limits, plus hooks to estimate and record actual token usage. Use it to combine burst capacity, steady-rate caps, and quota accounting in multi-user systems.

How this skill works

Define named limiters with strategies (fixed window for simple counts, token bucket for burst-friendly rates) and attach them to actions. Check limits before performing work by supplying a key (user ID or global key) and optional token counts; reserve or debit actual usage after generation. Client helpers expose status so UIs can show retry times and avoid unnecessary requests.

When to use it

• Prevent rapid-fire message spam from a single user or session
• Enforce total token quotas per user to control billing exposure
• Provide burst capacity while keeping long-term throughput steady
• Protect against hitting global provider API quotas
• Allocate resources fairly across many users in shared systems

Best practices

• Use fixed-window rules for simple per-period message caps and token buckets for burst-tolerant quotas
• Estimate token usage before generation to reject heavy requests early, then record actual usage afterward
• Combine per-user and global limits to avoid a single user consuming shared budget
• Return retryAfter timestamps for clients so UIs can show when to retry
• Reserve capacity (not just check) when starting a generation to avoid races

Example use cases

• Limit each user to 1 message every 5 seconds with a small burst capacity
• Enforce a per-minute token quota per user while maintaining a large global token pool
• Reject requests that would exceed a billing quota and inform the client when they can try again
• Expose rate-limit status to the chat input so the UI disables sending when limits are hit
• Track actual model usage from an agent’s usage handler to debit tokens after generation