Agent State Diff Generation Prompt Template

Use this prompt when you need a structured, machine-readable comparison of two agent state snapshots taken at different points in a workflow. The primary job-to-be-done is detecting what changed between state captures so that downstream systems—such as replanning modules, audit loggers, or human reviewers—can act on precise deltas instead of re-parsing full state objects. This is essential for long-running agent sessions where state evolves incrementally and silent corruption, missing fields, or unexpected mutations must be surfaced before they compound into execution errors.

The ideal user is an AI engineer or platform developer building an agent runtime that captures state at checkpoints, after tool calls, or before context-window eviction. You should have access to two structured state objects (JSON, typed dicts, or schema-validated records) and need a diff that includes added, removed, and modified fields, each with a confidence score and a human-readable change description. This prompt is not a general-purpose text diff. Do not use it for comparing natural language summaries, unstructured logs, or freeform agent notes—those inputs require extraction and normalization before diffing. It is also not a replacement for a state reconciliation or conflict-resolution prompt; it only reports what changed, not which version is correct.

Before wiring this into production, define the state schema both snapshots must conform to. If the input state objects can arrive with missing keys, nested nulls, or type drift, add a pre-validation step that normalizes them to a canonical shape. The prompt works best when the two snapshots share the same schema version. If you are comparing states across schema migrations, you will need an adaptation layer before invoking the diff. For high-risk agent workflows—such as financial transactions, clinical documentation, or infrastructure mutation—always log the raw diff output alongside the source snapshots and require human review for any change that exceeds a configurable severity threshold.

This prompt template is designed to be copied directly into your application code, test suite, or prompt management system. It accepts two agent state snapshots—a prior state and a current state—and produces a structured change log identifying what was added, removed, or modified. Each change entry includes a confidence score and the specific field paths affected. The template uses square-bracket placeholders that you replace with your actual state schemas, constraints, and examples before deployment.

textCopy
You are an agent state auditor. Your task is to compare two agent state snapshots and produce a structured diff of all changes.

## INPUT

### Prior State (before the last action or checkpoint)
```json
[PRIOR_STATE_JSON]

Current State (after the last action or checkpoint)

jsonCopy
[CURRENT_STATE_JSON]

State Schema

jsonCopy
[STATE_SCHEMA_JSON]

CONSTRAINTS

[CONSTRAINTS]

OUTPUT SCHEMA

Return a JSON object with the following structure:

jsonCopy
{
  "diff_id": "string, unique identifier for this diff",
  "prior_checkpoint_id": "string, identifier from the prior state snapshot",
  "current_checkpoint_id": "string, identifier from the current state snapshot",
  "timestamp_comparison": {
    "prior_timestamp": "string or null",
    "current_timestamp": "string or null",
    "temporal_ordering_valid": "boolean, false if timestamps are out of order"
  },
  "changes": [
    {
      "change_type": "added | removed | modified | unchanged",
      "field_path": "string, dot-notation path to the changed field",
      "prior_value": "any or null",
      "current_value": "any or null",
      "confidence": "number between 0.0 and 1.0",
      "evidence": "string, brief explanation of what was compared and why this change was detected",
      "severity": "critical | high | medium | low | informational"
    }
  ],
  "summary": {
    "total_fields_compared": "integer",
    "added_count": "integer",
    "removed_count": "integer",
    "modified_count": "integer",
    "unchanged_count": "integer",
    "low_confidence_changes": "integer, count of changes with confidence below [CONFIDENCE_THRESHOLD]"
  },
  "integrity_checks": {
    "schema_conformance": "boolean, whether current state conforms to the provided schema",
    "schema_violations": ["string, description of each schema violation found"],
    "cross_field_consistency": "boolean, whether related fields are internally consistent",
    "consistency_violations": ["string, description of each inconsistency found"],
    "silent_corruption_suspected": "boolean, true if state changed without corresponding action records",
    "corruption_evidence": ["string, specific indicators of possible silent corruption"]
  },
  "warnings": ["string, any warnings about the diff quality, missing data, or ambiguous changes"]
}

INSTRUCTIONS

1. Parse both state snapshots according to the provided schema.
2. Perform a field-by-field comparison at all levels of nesting.
3. For each field, determine whether it was added, removed, modified, or remained unchanged.
4. Assign a confidence score to each change based on how unambiguous the comparison is. Low confidence is appropriate when values are semantically similar but syntactically different, or when type coercion could mask a real change.
5. Run integrity checks: validate schema conformance, check cross-field consistency, and look for signs of silent state corruption (state changes that don't correspond to any logged action).
6. Flag any changes with confidence below [CONFIDENCE_THRESHOLD] in the summary.
7. If [RISK_LEVEL] is "high", include explicit human-review markers on all critical-severity changes.

EXAMPLES

[EXAMPLES]

RISK LEVEL

Current risk level: [RISK_LEVEL]

To adapt this template for your system, replace the square-bracket placeholders with concrete values. [PRIOR_STATE_JSON] and [CURRENT_STATE_JSON] should be populated with serialized state objects from your agent's checkpoint system. [STATE_SCHEMA_JSON] must be your actual state schema definition, which the model uses to understand field types, required fields, and nesting structure. [CONSTRAINTS] should include domain-specific rules such as "ignore fields prefixed with internal_" or "treat null and missing as equivalent." [CONFIDENCE_THRESHOLD] is a float like 0.7 that determines when a change is flagged as low-confidence. [RISK_LEVEL] accepts "low," "medium," or "high" and controls whether human-review markers are injected. [EXAMPLES] should contain one or two few-shot examples showing correct diff output for your specific state schema—this is the most important adaptation step for production accuracy.

Before deploying, validate that your state schema is complete and that both state snapshots are valid JSON conforming to that schema. The integrity checks in the output will catch schema violations, but feeding malformed JSON into the prompt will produce unreliable diffs. In high-risk workflows, always route diffs with silent_corruption_suspected: true or severity: critical changes to a human reviewer before the agent acts on the updated state. For automated pipelines, implement a post-processing validator that confirms the output JSON matches the output schema and that total_fields_compared equals the sum of all change counts.

The Agent State Diff Generation prompt is designed to be called programmatically whenever an agent's internal state snapshot changes—typically after a tool execution, a planning step, or a human intervention. The harness should treat the prompt as a deterministic function: two state snapshots go in, a structured diff comes out. Because the diff is used to update downstream systems (task trackers, audit logs, handoff summaries), the harness must validate the output before accepting it. A malformed diff that silently drops a removed field or mislabels a modified entry can corrupt the agent's understanding of its own progress, leading to duplicated work or skipped subtasks.

Wire the prompt into a state-change hook or middleware that fires after every state mutation. The harness should: (1) serialize the previous state and current state into the [PREVIOUS_STATE] and [CURRENT_STATE] placeholders using a canonical JSON representation; (2) include the [STATE_SCHEMA] so the model knows which fields are expected and their types; (3) set [CONFIDENCE_THRESHOLD] to a value appropriate for your risk tolerance (0.7–0.85 is typical for production, with anything below flagged for human review). After receiving the model response, run a structural validator that checks: the output is valid JSON, the changes array contains only added, removed, and modified entries, each entry has a field_path, previous_value, current_value, and confidence score, and no field appears in multiple change categories. If validation fails, retry once with the validation error appended to the [CONSTRAINTS] block. If the retry also fails, log the raw response and escalate to a human reviewer rather than silently accepting a partial diff.

For production deployments, choose a model with strong JSON-mode support and low structural hallucination rates—GPT-4o, Claude 3.5 Sonnet, or Gemini 2.0 Flash with response_schema enabled are good starting points. Avoid models under 7B parameters for this task unless you've validated their schema adherence on your specific state shapes. Log every diff generation call with: input state hashes, output diff hash, validation pass/fail, retry count, and latency. This trace data is essential for debugging silent state corruption—when an agent acts on stale information, the first place to check is whether the diff that should have caught the change was generated correctly. For high-risk workflows (healthcare, finance, legal), require that any diff with a confidence score below the threshold or any diff that modifies a safety-critical field (e.g., patient_condition, transaction_status, contract_clause) be routed to a human approval queue before the agent's state is updated.

Finally, implement a periodic reconciliation check that compares the agent's accumulated state against an independently computed ground-truth snapshot (e.g., from a database query or a separate agent). If the diff-based state tracker diverges from ground truth by more than a configurable tolerance, trigger a full state rebuild rather than applying incremental diffs. This guards against the cumulative error mode where a series of small, plausible diffs gradually drift the agent's state away from reality without any single diff failing validation.