How do I allocate a context-window budget?

Scope

Use this guide to design prompt assembly for an agent that combines instructions, identity and authority, workflow state, retrieved evidence, tool contracts, conversation history, and generated output. It is an allocation method for a new or redesigned frame. If the problem is reducing an existing oversized prompt, use the context-shortening guide.

Why it happens

Most context windows are assembled by append order. System instructions arrive first, conversation grows, retrieval adds the top K chunks, tools append verbose results, and output gets whatever space remains. Under pressure, a library truncates old messages or the API rejects the request. Neither behavior knows which information is binding.

An agent needs asymmetric protection. Losing conversational courtesy is cheap. Losing the target tenant, a policy exception, an unresolved approval, or the source of a critical claim can be severe. A budget makes those priorities explicit before the system reaches its limit.

Diagnosis

Instrument the compiled frame, not only the user prompt. For a representative task set, record tokens by context class, material omitted, compression performed, retrieval candidates rejected, reserved output, and actual output. Identify where each failure came from:

• required evidence never retrieved;
• retrieved evidence displaced instructions or state;
• a tool schema or result consumed unexpected space;
• history was retained after its decisions were already normalized;
• output or structured fields were truncated;
• two sources conflicted but only one survived allocation.

The diagnostic question is not “Which message is longest?” It is “Which retained or evicted object changed the task decision or its verifiability?”

Solution

Compile context in classes. Protect a fixed-order core: current policy and instructions, actor and authority, task objective, committed state, invariants, open decisions, and required evidence. Allocate bounded pools to candidate retrieval, examples, and recent interaction. Reserve output and at least one tool-error/result envelope before filling optional pools.

Each object needs a priority, maximum size, expiry, provenance reference, and eviction behavior. When the core itself exceeds the frame, fail compilation with a typed error; silent truncation is unsafe. When optional evidence is evicted, record what was lost so the agent can request it later.

Test several allocations with the same model and tasks. Report outcome, serious failures, evidence support, latency, total calls, and outcome cost.

Artifact

Start with a template rather than universal percentages:

Frame class	Minimum reserve	Maximum	Eviction/compression rule	Failure signal
Instructions and policy			Versioned; never silently truncate	policy_overflow
Identity and authority			Typed fields; revalidate at action	authority_missing
Current task state			Snapshot plus event references	state_incomplete
Required evidence			Keep claim/source/limit units	evidence_missing
Candidate retrieval			Rank, diversify, and fetch on demand	candidate_evicted
Tool schemas/results			Narrow schemas; normalize outputs	tool_frame_overflow
Interaction history			Extract decisions, then age out prose	history_compacted
Output and recovery reserve			Protected before optional fill	output_at_risk

Version the completed frame policy and save the compiled-frame manifest for every evaluated run.

Common mistakes

• Setting top_k without a token or diversity budget.
• Counting only document text and omitting message, schema, and serialization overhead.
• Letting optional retrieval displace authority or current state.
• Silently truncating the core when it exceeds the model limit.
• Optimizing one call while compaction and recovery create more total work.