The Agentforce token budget: why your agent runs out of room mid-answer

An agent that passed every test in the sandbox starts giving strange answers in production. It ignores an instruction it followed yesterday. On one record it works, on the next it invents a policy. The model is the same, the topic is the same, and nothing in Setup changed.

The usual first move is to blame the model or rewrite the prompt. Both are wrong more often than they’re right. The real cause is almost always that the prompt got too big for the window it has to fit in, and the platform made room by throwing away the part you cared about most.

So the rule to start from: every Agentforce turn has a fixed token budget, and the model spends most of it before it reads the customer’s question. If you don’t manage what goes in, the agent overflows and degrades instead of erroring. This post is about where those tokens go, how the failure presents, and the levers that keep a prompt inside its budget.

One window holds everything

A language model reads and writes in tokens, roughly three-quarters of a word each. Every model has a context window, a hard ceiling on how many tokens it can hold in a single request. That ceiling covers the input and the output together. It caps not how long the answer can be, but the total the model can hold in mind at once.

Agentforce runs on that same constraint, because underneath the Atlas reasoning engine sits a model with a window. The Salesforce-managed default has run as a mix of trusted models with a window on the order of 128K tokens, and the Anthropic and OpenAI models you can select have different sizes.

The exact number matters less than the shape of the problem. The window is finite, and you are not the only thing spending it.

Here is the part teams miss. The customer’s message is a small slice of the window. The model has to receive, in the same request, the agent’s system prompt, the instructions for the active topic and every action attached to it, the running conversation so far, and all the grounding you retrieved. Only then does it get the question. And it has to leave room to answer.

The budget, itemised

Think of a single turn as a bucket with a fixed volume. Six things pour into it, in roughly this order:

System and platform instructions. The base prompt that makes the thing an Agentforce agent, plus the Trust Layer scaffolding. You don’t control this and it isn’t free.
Topic and action instructions. Your agent’s real logic lives here: the instructions on the active topic, and the name, description, and input definition of every action that topic can call. A topic with twelve verbose actions costs far more than one with three.
Conversation history. Every prior user turn and agent reply the agent still remembers, which grows as the conversation does.
Grounding. The retrieved chunks, merge fields, and record data injected before the model generates. Usually the biggest single variable, and the easiest to blow.
The user’s message, often the smallest piece.
Reserved output. The model sets aside space for its own answer. That reservation comes out of the same window, so a long expected answer shrinks the room for everything above it.

Add those up and they have to be less than the window. When people say “the prompt,” they mean line 5. The model sees lines 1 through 6. That gap is the whole problem.

A rough way to picture it, with made-up-but-plausible numbers on a 128K window:

context window                       128,000 tokens
────────────────────────────────────────────────────
system + platform instructions        ~4,000
topic + action instructions           ~6,000
conversation history (10 turns)      ~12,000
grounding (12 chunks × ~800 tokens)   ~9,600
user message                            ~150
reserved for the answer               ~4,000
────────────────────────────────────────────────────
used                                 ~35,750
headroom                             ~92,250   ← fine

That one looks healthy. Now change two things a real deployment changes. Point the retriever at fifty chunks instead of twelve because “more context is safer,” and let the conversation run to forty turns because nobody set a memory limit.

Grounding jumps past 40,000 tokens and history past 45,000. On a smaller-window model, or with a few large documents in the mix, you cross the line. What happens next is the part nobody demos.

Overflowing fails two ways, and the quiet one is worse

When the tokens you assemble exceed what the model can take, you get one of two outcomes.

The loud one is an error. The request is rejected, the turn fails, and you see something like an input-limit or token-limit message in the logs. It’s disruptive, but it’s honest: you know exactly what happened and roughly where.

The silent one is truncation, and it produces the “worked yesterday” bug. Rather than fail, the pipeline trims to fit, and the earliest content is the first to go. The earliest content is usually your instructions and guardrails.

So the model answers, fluently and confidently, having never seen the rule that said “never quote a price” or “always verify identity first.” The output looks like a reasoning failure. It’s a budgeting failure. The agent didn’t break the rule. The rule wasn’t in the room.

If you pass too much grounding data, you can exceed the limit or crowd out useful instructions.

That line, from Salesforce’s own prompt-engineering guidance, is the whole risk in one sentence. Crowding out is not a rounding error. Crowding out is instructions silently deleted, and it gets worse as a conversation gets longer or a knowledge base gets richer, which is to say as the agent gets more use.

The same mechanism is why the failure is so hard to reproduce. It depends on the size of this record, this customer’s history, and this retrieval, so it fires on the long transcripts and the data-heavy accounts and never on the clean demo. It looks random. It isn’t. It’s the token count crossing a threshold you can’t see.

Grounding is where the budget goes to die

Retrieval feels like free accuracy, so the instinct is to turn it up. The opposite is true. Every chunk you retrieve is tokens you spend on every single turn that runs that prompt, whether the model needed the chunk or not.

Two settings do most of the damage. The first is the retriever’s result count, the top-K. Returning twenty-five chunks when the answer lives in two means you pay for twenty-three passengers on every request, and you make the model’s job harder, not easier, because the signal is now buried in near-duplicates. The second is chunk size. Chunks that are too large drag whole pages in to deliver a sentence.

Getting this right is a retrieval-quality problem before it’s a budget problem, and the two are the same lever pulled from different ends. The work is in how you build and tune the retriever: a tight top-K, a filter that narrows before it searches, and the search index type that matches your queries so a handful of chunks carry the answer.

For document-heavy grounding, the chunking strategy in Intelligent Context is the difference between retrieving the right paragraph and retrieving the right forty pages. A retriever tuned for precision is, for free, a retriever that fits the budget.

The discipline is to ground with the fewest, smallest, most relevant chunks that answer the question, and to prove that number is enough rather than padding it “to be safe.” Padding is not safe. Padding is what evicts your instructions.

History and instructions are the slower leaks

Grounding is the flood. Two slower leaks matter almost as much.

Conversation history grows every turn, and a long support chat can accumulate more tokens than the grounding does. Agentforce keeps a bounded memory window rather than the whole transcript for this reason, and the mechanics of that window, with the other caps you’ll hit, are in the Agentforce limits map.

The design lesson is to lean on that bounded memory and on context and session variables to carry the two or three facts that must survive, instead of trusting a growing transcript to keep them. State you store deliberately costs a few tokens. State you hope the history remembers costs the whole history.

Instruction bloat is the one people defend. A topic accretes actions over months, each with a wordy description, and the reasoning engine has to read all of them, every turn, to decide which to call. Long, overlapping instructions cost tokens and make the routing decision worse at the same time.

The fix is architectural. Split a bloated agent into focused topics and subagents so each turn loads only the instructions relevant to what the user is doing, not the union of everything the agent could ever do. Fewer actions in scope means a smaller prompt and a sharper choice.

How to build inside the budget

You cannot see the token count of a live turn in the UI, so treat the budget as a design constraint, not a runtime alarm. Five habits keep prompts inside it.

Start by grounding with intent. Set the retriever’s result count to the smallest number that answers your evaluation questions, size chunks to the paragraph rather than the document, and add a grounding resource only when a test fails without it. Prove the minimum works before you add.

Bound the history. Rely on the platform’s memory window and lift anything that must persist into variables, so a long conversation doesn’t slowly evict your instructions.

Keep instructions lean and scoped. Write action descriptions that are specific and short, retire actions a topic no longer uses, and split by topic and subagent so each turn carries only what it needs.

Watch for the size-driven failure signature. When an agent misbehaves only on long conversations, data-rich records, or large documents, and behaves on everything small, suspect the budget before the model. That pattern is truncation, not stupidity.

And test on your worst case, not your cleanest. Build your agent test cases on the biggest real transcripts and the heaviest accounts you have, because those are the ones that overflow, and they are precisely the ones a demo never includes.

None of this is exotic. It’s the same engineering judgment you’d apply to any system with a fixed resource and a tempting knob that says “more.” The knob is grounding, the resource is the window, and the customer’s question, the thing the whole agent exists to answer, is fighting for space against everything you poured in ahead of it.

Manage the budget and the mystery failures stop being mysterious. Ignore it and no amount of prompt rewriting will save you, because the prompt was never the problem. The room ran out.

Understanding the basics

What is the context window in Agentforce?

The context window is the maximum number of tokens the underlying model can process in one request, covering both the input and the output. In Agentforce that single window has to hold the system and platform instructions, the active topic’s instructions, the descriptions of its actions, the conversation history, the retrieved grounding, the user’s message, and the space reserved for the answer. The size depends on which model the agent runs on, and it is finite, so everything you add to the prompt competes for the same fixed space.

Why does my Agentforce agent ignore its instructions sometimes but not always?

The most common cause is token overflow followed by truncation. When the assembled prompt exceeds the model’s window, the pipeline can trim the earliest content to fit, and the earliest content is usually your system and topic instructions. The agent then answers without ever seeing the rule it appears to violate. Because overflow depends on the size of the current record, history, and retrieval, it fires on long conversations and data-heavy records and never on the clean cases, which makes it look random when it is really a budget threshold being crossed.

How do I reduce the token usage of an Agentforce prompt?

Cut grounding first, because it is usually the largest and most variable input: lower the retriever’s result count, shrink chunk size, and keep only the grounding resources a test needs. Then bound the conversation history and move must-keep facts into context or session variables. Finally, trim and scope instructions by splitting a large agent into focused topics and subagents so each turn loads only the relevant actions and their descriptions rather than everything the agent could do.

Does more grounding data make an Agentforce agent more accurate?

Only up to a point, and past it the opposite is true. A few precise chunks help; a large pile of loosely relevant ones buries the signal, makes retrieval quality worse, and spends tokens that then evict your instructions. Accuracy comes from retrieving the right context, not the most context, which is why tuning the retriever’s precision and filters matters more than raising its result count.

If your agent misbehaves in production but not in the sandbox, or you want grounding to be both accurate and affordable before it ships, talk to us. Sizing the token budget is part of every Agentforce build we do.