---
name: agent-rate-limit-strategy
description: "Control LLM spend and Apex governor exposure for high-traffic Agentforce agents via per-user token budgets and graceful fallback. NOT for API rate-limiting of REST endpoints."
category: agentforce
salesforce-version: "Spring '25+"
well-architected-pillars:
  - Scalability
  - Operational Excellence
triggers:
  - "agent token budget blown"
  - "one user drives the whole agent quota"
  - "graceful fallback when agent is over limit"
  - "rate-limit agentforce per user"
tags:
  - agentforce
  - rate-limiting
  - cost
  - platform-events
inputs:
  - "Traffic forecast"
  - "per-tenant/per-user quotas"
  - "fallback UX"
outputs:
  - "Rate-limit policy CMDT"
  - "fallback messaging"
  - "observability dashboard"
dependencies: []
version: 1.0.0
author: Pranav Nagrecha
updated: 2026-04-17
---

# Agent Rate Limit Strategy

Agentforce exposes internal LLM quotas indirectly — you hit them as platform 503s with no forward signal. This skill builds a client-side budget gate in front of the agent: per-user token ledger, CMDT-driven thresholds, and a graceful fallback when the budget is exhausted.

## When to Use

Agents exposed to unauthenticated Experience Cloud users, high-traffic Service deflection, or any use case where one user can drive thousands of turns.

Typical trigger phrases that should route to this skill: `agent token budget blown`, `one user drives the whole agent quota`, `graceful fallback when agent is over limit`, `rate-limit agentforce per user`.

## Recommended Workflow

1. Define budget: tokens/user/hour, tokens/tenant/day. Persist in `Agent_Rate_Limit__mdt` per-persona.
2. In the channel entry point (LWC wrapper or Connect API), call a `BudgetService.checkAndConsume(userId, estTokens)` before dispatching to the agent.
3. Log consumption via Platform Event `Agent_Token_Consumed__e` — the subscriber rolls into a `User_Token_Ledger__c` aggregate.
4. When the budget is exhausted, render the fallback UX (human handoff / retry-after message) instead of calling the agent.
5. Dashboard: p50/p95 consumption per persona, budget exhaustion count, tokens/turn — page SRE when exhaustion >1%.

## Key Considerations

- Estimate tokens conservatively from input length (`chars/4`) before the call; reconcile after.
- Ledger is eventually consistent — use the Platform Event pattern, not synchronous DML.
- Fallback UX must be pre-approved; a generic 'try again later' erodes trust.

## Worked Examples (see `references/examples.md`)

- *Budget service sketch* — 100 Service reps use agent summarization; one rep loops a bad input 500x.
- *Graceful fallback* — Budget exhausted mid-conversation.

## Common Gotchas (see `references/gotchas.md`)

- **Estimating tokens from chars misses long RAG context** — Estimate says 500 tokens; reality is 5000 after grounding.
- **Platform Event volume limits** — High-traffic agent saturates your 24h PE quota.
- **Ledger bucket skew** — Timezone boundary resets at midnight UTC, users see it mid-afternoon locally.

## Top LLM Anti-Patterns (full list in `references/llm-anti-patterns.md`)

- Trusting Agentforce to rate-limit for you — it only fails loudly on hard limits.
- Hard-coded tokens/minute without per-persona CMDT — cannot respond to traffic shifts.
- Synchronous ledger DML per turn — blows DML limits.

## Official Sources Used

- Agentforce Developer Guide — https://developer.salesforce.com/docs/einstein/genai/guide/agentforce.html
- Einstein Trust Layer — https://help.salesforce.com/s/articleView?id=sf.generative_ai_trust_layer.htm
- Invocable Actions (Apex) — https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_invocable_action.htm
- Agentforce Testing Center — https://help.salesforce.com/s/articleView?id=sf.agentforce_testing_center.htm