My AI agent runs out of context window. How do I find the cause?

Rius shows context window pressure on the agent’s page, in the Context section, and the cause in the spans of the trace that hit it. Start with the agent’s Peak usage, open the trace that carries the largest call, and read the context growth strip and the span inputs to see what filled the prompt. You can then add a custom alert on Context usage so you hear about it the next time.

How it works

Rius computes context usage for each model call: the call’s input tokens, prompt cache included, divided by the model’s context window. A call whose model has no known context window is left out, never counted as 0. Three places show it:

• Agent page, Context section. On the Agents page, Peak usage is how much of the window the largest call used. Next to it, Rius splits the prompt into buckets: system prompt, tool definitions, tool calls and results, the tool-use preamble, user and assistant history, the current turn, and unattributed. The biggest bucket is your first suspect.
• Trace view. In Exploring traces, a trace with several model calls has a context growth strip above the tree. It plots input tokens for each call in order, which is where a runaway prompt or an unbounded history shows first.
• Span detail. When the model’s window is known, the trace and the span show how much of it was used, including reasoning tokens and the provider preamble.

What points at the cause: a steady climb across calls usually means history that is never trimmed. A sudden jump at one call usually means a large tool result or document was pasted into the prompt. A large tool definitions bucket means too many or too verbose tools. For background on reading agent runs in general, see Monitor AI agents in production.

Set it up

1. Open Agents, pick the agent, and set the time window to cover when the problem happened. Read Peak usage in Context. Close to 100% means calls are near truncation. Check which bucket is largest. If you see “nothing attributed”, no call in the window carried the data for the breakdown, but Peak usage still shows.
2. Open Recent traces or Errored traces on the same page and click a trace. A run that failed because the window filled up is a failed trace, and its error shows in the span detail. To look across traces instead, open Traces and use the Spans tab, filtered to LLM spans, then sort by the Tokens header.
3. In the trace, read the context growth strip. Click the tallest bar to select that call. With more than 80 model calls the strip groups neighboring calls, and clicking a grouped bar selects the run’s first failed call, or its peak when none failed.
4. In the span, open the Input / Output tab and choose Since previous llm call. Unchanged messages fold into one line, and every other message is marked added, removed or changed. In an agent loop this shows exactly what each step added to the prompt. This needs content capture on. If your SDK strips content, the tab says so, and you still get token counts and context usage.
5. Use Compare runs on the trace to set it against another run of the same agent, and see which steps were added or dropped and where tokens moved. To check whether a release caused it, tag runs with versions and compare them under Versions and Drift on the agent page:

RIUS_MAIN_AGENT_VERSION=prompt-v12      # the agent definition: prompt, tools, policy
RIUS_SERVICE_VERSION=2026.09.29-a41f3c  # the build or deploy

6. Create a custom alert on the Context usage metric. You compare it against a value between 0 and 1. This rule fires when the fullest 5% of calls in the window use more than 80% of their model’s context:

FILTERS   Service = checkout-agent
RULES     p95(Context usage) > 0.8
WINDOW    15 minutes

What you get

• The agent’s peak context usage and a bucket breakdown of what fills the prompt.
• A per-call view of input tokens inside a trace, with a click to the exact call where the prompt grew.
• A message-level diff between consecutive model calls, so you see which turn or tool result added the tokens.
• A version comparison to tell whether a new prompt, tool set or model made context pressure worse.
• An alert on Context usage that fires when its threshold is met over your chosen window. Firings on Context usage show the coverage ratio, so you can tell a real reading from a partly covered one.

If Peak usage is high, the fix is a larger window or less history in each prompt.

When something else fits

• If Peak usage is low but the agent still fails, the cause is not the window. Check Exceptions on the agent page, which groups errored spans by failure type.
• If your model has no known context window, Rius has no context usage for it. Use input token counts per call instead, in the trace and on the Spans tab.

Related