A well-designed context package for a single-turn system is relatively simple: write a clear system prompt, include relevant information, get a response. The same discipline applied to a 40-step agent task is an entirely different engineering challenge.
In agentic systems, the context window is not static — it evolves with every turn. Tool outputs get injected. Conversation history accumulates. Retrieved information may become stale or contradictory. The model's understanding of the task state shifts with each new observation. Context engineering in this environment is not about writing a great prompt once; it's about designing a system that maintains context quality across the full duration of the agent's operation.
This guide covers the full discipline: how to initialize an agent's context, how to manage context evolution across turns, how to inject tool outputs correctly, and how to recover from the context failure modes that emerge in long-running agent sessions.
The anatomy of an agentic context
At any point in an agent session, the context window contains:
┌─────────────────────────────────┐
│ SYSTEM PROMPT │ ← Static: set once, never changes
│ Role, task, success criteria, │
│ behavioral constraints, format │
├─────────────────────────────────┤
│ TOOL DEFINITIONS │ ← Semi-static: changes only if task changes
│ Available tools and schemas │
├─────────────────────────────────┤
│ PERSISTENT CONTEXT │ ← Semi-static: project/session state
│ CLAUDE.md, task brief, │
│ established constraints │
├─────────────────────────────────┤
│ CONVERSATION HISTORY │ ← Dynamic: grows with each turn
│ Prior turns, tool calls, │
│ tool outputs, decisions │
├─────────────────────────────────┤
│ CURRENT TURN │ ← Dynamic: changes each call
│ Current user message, │
│ latest retrieved context │
└─────────────────────────────────┘
The static components (system prompt, tool definitions) are set at initialization. The semi-static components are updated when the task or project context changes. The dynamic components grow with each turn and require active management.
The ratio of static to dynamic content shifts as the session extends. At turn 1, the context is mostly static. At turn 30, the dynamic history component often dominates. This shift is the central challenge of agentic context design.
Stage 1: Context initialization
Getting the initial context right prevents a class of failures that are otherwise impossible to recover from mid-session.
The agentic system prompt
Agentic system prompts must do more than single-turn system prompts. They must cover:
Task definition and success criteria. Not just "help the user with their coding task" but a precise definition of what task completion looks like. "The task is complete when: (1) all tests pass, (2) the change is committed with a descriptive message, (3) you have reported the outcome to the user." Without explicit success criteria, agents loop indefinitely or stop too early.
Autonomous vs. ask behavior. When should the agent proceed without user confirmation? When should it stop and ask? Define the threshold explicitly:
Proceed autonomously when:
- The action is reversible (file reads, test runs, code generation)
- The action follows directly from prior user instruction
- The action's scope is limited to the specified files/directories
Stop and ask when:
- You need to delete or overwrite files not mentioned in the task
- You are uncertain whether your plan matches the user's intent
- You have encountered an error state that changes the task scope
Error and failure protocols. What should the agent do when a tool call fails? Retry immediately? Try a different approach? Stop and report? Define this explicitly — agents with no failure protocol either loop on retries until context fills or stop at the first error without explanation.
Output format. Specify how the agent communicates its state: status updates after key steps, summary at completion, format for reporting errors. This affects both the quality of user experience and the token cost of output generation.
Tool definition initialization
Initialize with only the tools needed for the task type. For a coding agent: file read/write, test runner, terminal, search. Not: calendar, email, document creation. Minimizing the tool surface at initialization reduces selection errors throughout the session.
Persistent context injection
If the task involves a specific codebase, project, or set of constraints, inject them at initialization in a labeled block:
[PROJECT CONTEXT]
Repository: payment-service (Python, FastAPI, PostgreSQL)
Conventions: snake_case, type hints required, no external dependencies without approval
Relevant files: src/payment/, tests/test_payment.py, docs/payment-api.md
Current issue: Transaction rollback not triggered on timeout (see issue #1284)
[END PROJECT CONTEXT]
This is the equivalent of a CLAUDE.md file — explicit context engineering for the project rather than hoping the model infers it from code style.
Stage 2: Tool output injection
Tool calls are the primary mechanism by which new information enters the agent's context mid-session. How you inject tool outputs determines whether the model can make use of them.
Structure tool outputs clearly
Unstructured tool outputs are the most common source of context confusion in agentic systems. The model receives a blob of JSON, a wall of log output, or a multi-page file — and must infer what's relevant.
Instead, wrap tool outputs in structure that makes their nature and relevance explicit:
[TOOL OUTPUT: read_file]
File: src/payment/processor.py (lines 45-89)
Retrieved at: turn 7 | Task: diagnose timeout issue
---
{file_content}
---
[END TOOL OUTPUT]
The label tells the model: what tool produced this, what file/resource it came from, when in the session it was retrieved, and why it was retrieved. This context helps the model weight the output appropriately and recognize when it may have become stale.
Truncate large tool outputs
Not every tool output needs to be injected in full. A 50,000-line log file, a full database dump, or a 10MB API response in the context window is context engineering malpractice. Extract the relevant section and inject that:
[TOOL OUTPUT: run_tests - TRUNCATED]
Showing first 3 failures of 47 total
---
FAILED test_payment_timeout: AssertionError at line 134
Expected: rollback triggered
Got: transaction committed (unexpected success)
FAILED test_concurrent_transactions: TimeoutError at line 89
...
[END TOOL OUTPUT - see full output at tests/output/run_2026-06-28.log]
Reference the full output location so the model can retrieve it if needed, but don't inject it preemptively. The model should use the summary to understand the state and make decisions; it can retrieve detail if that's needed.
Remove stale tool outputs
Tool outputs become stale when the task state has changed. If a file was read at turn 5, modified at turn 12, and re-read at turn 15, the turn-5 output is now stale and potentially contradictory. Stale tool outputs confuse the model — it sees two versions of the same file and must infer which is current.
Actively remove stale outputs from the context during history management:
- After a file is modified, mark the previous read output as stale
- After a test run supersedes a previous test run, summarize or drop the prior result
- After a search result is refined (new query, same topic), replace the old result
Stage 3: Context evolution management
As the session progresses, the context window evolves in ways that require active management.
The context evolution cycle
Each turn follows the same pattern:
- Assess current state. What does the model know? What tools has it called? What decisions have been made?
- Retrieve or inject. Bring in new information needed for the current step.
- Generate. The model reasons and produces a response or tool call.
- Inject output. Tool call results are added to the context.
- Prune and manage. Remove stale content, summarize accumulated history, maintain token budget.
- Repeat.
Step 5 — prune and manage — is the step most agentic systems skip. Without it, the context grows monotonically until it hits the context limit or becomes so cluttered that quality degrades.
Detecting context drift
Context drift is when the model's behavior starts diverging from its initial instructions as the session extends. Signs of context drift:
- The model re-introduces options that were ruled out in earlier turns
- The model asks clarifying questions about constraints that were already established
- The model's output format changes without being asked to change
- Tool calls start becoming redundant (calling the same tool with the same query)
All of these indicate that critical early context has been diluted by accumulated history. The system prompt and early task definition have been pushed into the middle of the context window where they receive less attention.
Mitigation: Repeat critical constraints. Add a compact re-statement of current task state and hard constraints before the latest user message in each turn, especially in long sessions:
[CURRENT TASK STATE - Turn 23]
Task: Fix payment timeout rollback (issue #1284)
Constraints established: no schema changes, no new dependencies
Progress: Root cause identified (line 67, processor.py), fix drafted, tests written
Next: Run full test suite to verify fix
[END TASK STATE]
This 5-6 line injection is cheap but dramatically reduces context drift in long sessions.
Managing contradictions
Tool outputs frequently contradict each other across session turns. An API returns one count at turn 5; a database query returns a different count at turn 15. Both are in the context. The model must reconcile them.
Don't leave contradictions unresolved in the context. When a new tool output contradicts an earlier one:
- Note the contradiction explicitly in the context:
[Note: the above contradicts the API response at turn 5 — the database count (42) is authoritative for this task] - Mark the superseded output as stale or remove it
- Ensure the model has a clear resolution
Agents without contradiction resolution drift between conflicting beliefs, producing inconsistent outputs across turns.
Stage 4: Multi-agent context design
In multi-agent systems, context engineering applies at two levels: within each sub-agent's session, and at the orchestrator level.
Orchestrator context design
The orchestrator coordinates sub-agents. Its context should contain:
[ORCHESTRATOR CONTEXT]
Active task: Refactor authentication module
Sub-agents available: coding-agent, testing-agent, documentation-agent
Task decomposition:
- coding-agent: refactor src/auth/* (assigned, in progress)
- testing-agent: waiting for coding-agent completion
- documentation-agent: update API docs (depends on coding completion)
Current status: Turn 12 of coding-agent execution
[END ORCHESTRATOR CONTEXT]
The orchestrator should not receive sub-agent conversation history verbatim. It should receive structured outputs: what was attempted, what succeeded, what failed, and what the current state is. This keeps the orchestrator context focused on coordination, not implementation detail.
Sub-agent context design
Sub-agents receive a focused task context. This should include:
- The specific task assigned by the orchestrator (not the full parent task)
- Only the tools needed for this sub-task
- Relevant project context for their specific domain
- Clear success criteria for their sub-task
- Explicit handoff format (how to report completion back to the orchestrator)
Sub-agent contexts should be designed to complete in as few turns as possible. Complex multi-step sub-tasks are often better broken into additional sub-agents than handled in a single long-running sub-agent session.
Context boundary discipline
The most important design decision in multi-agent systems is what crosses the context boundary between agents. As a rule:
- Pass structured outputs, not raw history. Orchestrators receive summaries and outcomes; sub-agents receive task briefs and constraints.
- Pass what's load-bearing, not everything. Not every fact from a sub-agent's session is relevant to the orchestrator or sibling sub-agents.
- Make handoffs explicit. The receiving agent should know it's receiving a handoff, not continuing a conversation. Label cross-agent context clearly.
Stage 5: Failure recovery
Long-running agent sessions fail in ways that short sessions don't. Context design must include explicit failure recovery patterns.
Context limit failures
When the session approaches the context limit, the agent needs a graceful fallback:
[SYSTEM - CONTEXT LIMIT APPROACHING]
Current context: 185,000 / 200,000 tokens
Required action: Complete or checkpoint the current step, then:
1. Summarize completed work and current state in < 1,000 words
2. List remaining steps explicitly
3. Output the summary as your final response for this session
The user will start a new session with your summary as the initial context.
Without this instruction, agents at context limit either hallucinate (generating plausible-sounding completions without valid context) or stop abruptly without a useful handoff.
Tool failure cascades
When a key tool fails, the agent needs to know whether to retry, use an alternative, or escalate:
Tool failure protocol (in system prompt):
- On transient errors (timeout, rate limit): retry once after 1 second
- On validation errors (bad parameters): do not retry; fix the parameter and retry
- On permission errors: stop and report to user immediately, do not attempt workarounds
- On 3+ failures on the same tool call: stop, summarize what was attempted, ask for guidance
Without explicit failure protocols, agents retry indefinitely (burning tokens and time) or stop at the first error without useful context for the user.
Contradictory state
When the agent's inferred task state conflicts with a tool output, it needs a resolution protocol rather than letting the contradiction sit in context:
On detecting contradictions:
1. Note the contradiction explicitly (state both versions)
2. Identify which source is more authoritative (database > API > cached state > inferred)
3. Update your task state based on the authoritative source
4. Continue with the resolved state
The agentic context design checklist
Before deploying a multi-turn agent system:
Initialization:
- System prompt includes success criteria, not just task description
- System prompt defines autonomous vs ask boundaries
- System prompt includes failure and error protocols
- Tool surface minimized to task-relevant tools
- Persistent context injected in labeled block
Tool output management:
- Tool outputs injected with labels (tool name, source, when/why retrieved)
- Large outputs truncated to relevant sections
- Stale outputs removed or marked as superseded
- Contradictions resolved with explicit resolution notes
Context evolution:
- History management strategy implemented (summarization, sliding window, or pruning)
- Context drift mitigation in place (task state re-statement in long sessions)
- Token budget monitored across session turns
- Cache boundaries set for static context prefix
Failure recovery:
- Context limit approach handled gracefully
- Tool failure cascade protocol defined
- Contradiction resolution protocol defined
Multi-agent (if applicable):
- Orchestrator receives structured outputs, not raw history
- Sub-agents receive task briefs with clear success criteria
- Cross-agent handoffs labeled and structured
Context engineering in agentic systems is not a one-time task. It requires monitoring running sessions, diagnosing where quality degrades, and iterating on the context design as you learn how your specific agent task evolves. The teams that do this well build agents that are reliable across long, complex sessions. The teams that skip it build agents that work in demos and fail in production.