Managing Context in Long-Running AI Agents

Every turn of an agent adds to the conversation: tool calls, large tool results, the model's replies. Long tasks can grow past the context window, and even before that, a bloated context makes the model slower, more expensive and less focused.

1. Keep tool results small

• Return summaries or the first N rows, with a way to fetch more ("page 2").
• Strip HTML, boilerplate and fields the model doesn't need.
• For files, return a path and line count; let the model read specific ranges.

2. Clear old tool results

Results from early steps are often irrelevant later. Context editing removes old tool results from what the model sees. With the Claude API this is a beta feature:

const response = await client.beta.messages.create({
  model: 'claude-opus-5-5',
  max_tokens: 16000,
  betas: ['context-management-2025-06-27'],
  context_management: { edits: [{ type: 'clear_tool_uses_20250919' }] },
  tools,
  messages,
});

3. Summarise with compaction

Compaction replaces older history with a summary when the context gets large. Server-side compaction (also beta) does this for you; you must append the full response.content each turn so the compaction block is kept.

const response = await client.beta.messages.create({
  betas: ['compact-2026-01-12'],
  model: 'claude-opus-5-5',
  max_tokens: 16000,
  messages,
  context_management: { edits: [{ type: 'compact_20260112' }] },
});
messages.push({ role: 'assistant', content: response.content }); // not just the text

4. External memory

Give the agent a way to write notes outside the conversation, such as a progress.md file, a to-do list tool or a database table. After a reset or in a new session, it reads the notes and carries on.

5. Split the work

For big tasks, have a coordinating agent hand self-contained subtasks (with their own clean context) to sub-agents and receive only their short conclusions back.