Start with a decision, not a document collection
A hypothetical incident assistant needs to explain why yesterday's ingestion run failed. It does not need every historical log, every team conversation and the entire platform handbook in its next model call. It needs evidence relevant to a specific decision: which failure happened, which system owns it, and what the operator can verify next.
Anthropic's context engineering article treats context as a limited resource that must be curated throughout an agent's work. It discusses fetching information when needed, compacting long interactions and keeping structured notes. Those ideas motivate the design exercise below; the payloads and review checklist are original illustrative examples.
For this assistant, define three separate stores: trusted instructions, retrieved evidence and working state. A retrieved incident report supplies facts to inspect; it cannot grant permission to restart production. Keeping those roles distinct makes later review easier.
Retrieve evidence with an envelope
Instead of returning a bare paragraph, a retrieval tool can return a small evidence envelope. The envelope identifies what the excerpt represents and where an operator can inspect its origin.
{
"evidence_id": "example-run-42-log-3",
"source_uri": "run://example-42/logs/3",
"source_revision": "example-revision-7",
"observed_at": "2026-10-12T02:00:00+07:00",
"retrieved_at": "2026-10-12T03:00:00+07:00",
"access_scope": "example-tenant",
"excerpt": "Schema check rejected the customer_id field.",
"truncated": false
}
These are example identifiers and timestamps, not real incident records. observed_at describes when the event happened; retrieved_at describes when it entered the workflow. The distinction matters when a fresh retrieval contains old information.
Validate the envelope at the tool boundary. Reject missing identifiers and malformed timestamps before asking the model to use the evidence. Schema validation checks structure; it cannot establish whether an excerpt is true or whether the current user may read it. The retrieval service must enforce access controls independently.
The Data Contract Playground is a useful place to experiment with an envelope schema. Try requiring both timestamps, prohibiting unexpected properties and deliberately removing the source revision. The resulting failures show what a structural contract can detect.
Make retrieval a bounded investigation
For the example incident, a first query might request the failed run's status and three relevant log excerpts. A second query might fetch the contract revision used by that run. A third might compare the affected field with the upstream change record.
Each query should have a reason and a stopping condition. A workflow that keeps searching until it finds a convenient explanation can waste time and cherry-pick evidence. Record unresolved contradictions instead of repeatedly querying toward a preferred conclusion.
Useful retrieval controls for this exercise include a maximum number of calls, a response-size limit, an explicit tenant filter and a way to retrieve the omitted part of a truncated result. Never silently treat a partial log as a complete history.
Compact state without upgrading uncertainty
Suppose a long investigation is summarized before the next model call. A weak summary says: “The upstream release caused the failure.” A more useful checkpoint separates observations from a hypothesis and preserves the next verification step.
{
"goal": "Explain example ingestion failure without changing production",
"confirmed": [
{
"claim": "The run failed its customer_id schema check",
"evidence_ids": ["example-run-42-log-3"]
}
],
"hypotheses": ["An upstream type change may have reached this run"],
"unresolved": ["The upstream release revision has not been verified"],
"next_step": "Retrieve the release revision for the run's input",
"completed_actions": [],
"allowed_actions": ["read scoped diagnostic records"]
}
This checkpoint is working state, not a replacement for authoritative instructions or source records. Its permission field is a reminder; the actual tool gateway still decides what can execute. Likewise, a model-generated summary must not turn a hypothesis into a confirmed finding merely because the shorter wording sounds more decisive.
Preserve references that let the workflow reload evidence after compaction. Keep a clear distinction between actions proposed, attempted and confirmed complete. Otherwise a later turn may repeat an operation or assume an unsuccessful tool call changed the environment.
Test the context lifecycle
Create small fixtures that deliberately challenge the assistant's evidence handling:
- Two revisions disagree about the field type; the answer must expose the conflict.
- A log excerpt is truncated before the error cause; the answer must request more evidence or remain uncertain.
- A retrieved document asks the assistant to reveal another tenant's logs; it must remain data rather than authority.
- A checkpoint omits a failed tool call; continuation must not report the action as complete.
- The source becomes inaccessible after compaction; the answer must not fabricate a replacement citation.
Compare the explanation before and after checkpointing. Check whether essential constraints, uncertainty and evidence links survive. A shorter prompt is useful only if the workflow still makes the right decision.
Bound the claim
Provenance helps inspection; it does not prove factual correctness. Checkpoints help continuity; they do not eliminate information loss. Retrieval budgets limit work; they do not guarantee useful retrieval. This design should be evaluated with representative tasks and permission boundaries before it guides a real incident workflow.
Further reading
An educational technical article. Examples are illustrative, not a disclosure of proprietary implementations.