Agent Role State Management Contract Prompt

This prompt is for infrastructure engineers and platform developers who need to formalize how a single agent manages its internal state across a multi-turn or multi-step lifecycle. The job-to-be-done is producing a machine-readable and human-auditable state contract that specifies what the agent persists, what it discards, how it serializes state, and how it recovers from corruption or unexpected termination. Use this when you are building a multi-agent system where state consistency, recovery, and debuggability are production requirements—not when you are prototyping a single-turn agent or a simple chat assistant that can safely lose all context between calls.

The ideal user is someone who already has a defined agent role and capability boundary but needs to make the agent's internal memory explicit before wiring it into an orchestrator, shared memory store, or handoff protocol. Required context includes the agent's role definition, its input/output contracts, and the execution environment's persistence guarantees (or lack thereof). Do not use this prompt if the agent is stateless by design, if state is managed entirely by an external orchestrator with no agent-side memory, or if you are looking for a generic 'memory prompt' for a consumer chatbot. This prompt assumes a production system where state corruption, partial writes, and recovery are real failure modes.

The output is a state lifecycle contract with a defined serialization format, a list of persisted vs. ephemeral fields, recovery procedures, and explicit test cases for corruption and recovery scenarios. Before integrating this contract into your agent harness, validate it against your orchestrator's state-passing mechanism and ensure the serialization format is compatible with your shared memory store. The next step after generating this contract is to implement the state save/load hooks in your agent runtime and run the provided corruption test cases to verify recovery behavior.

This prompt template produces a structured state management contract for a single agent role. It forces explicit decisions about serialization format, persistence boundaries, corruption detection, and recovery procedures before the agent is deployed. Use it when you are defining a new agent or hardening an existing one against state loss. Do not use this prompt for agents that are fully stateless by design or for simple request-response assistants that carry no internal memory between turns.

textCopy
You are an infrastructure engineer designing the state lifecycle for an AI agent. Your task is to produce a complete state management contract for the agent described below. The contract must be precise enough that an orchestration engine can enforce it and a recovery system can rebuild state from it.

## AGENT IDENTITY
[AGENT_ROLE_NAME]
[AGENT_ROLE_DESCRIPTION]

## REQUIRED SECTIONS
Generate a state management contract with exactly these sections:

### 1. State Schema
Define every field the agent persists. For each field, specify:
- Field name and type
- Whether it is required or optional
- Default value if absent
- Whether it survives session boundaries or is ephemeral
- Serialization format (JSON, binary, base64, etc.)

### 2. Persistence Policy
Specify:
- Which state fields are written to durable storage and when (every turn, on commit, on handoff)
- Which fields are held in memory only and discarded on session end
- Maximum size constraints per field and total state
- Retention duration for persisted state

### 3. State Lifecycle Events
For each of these events, describe exactly what happens to the agent's state:
- Agent initialization (cold start)
- Agent receiving a new task
- Agent completing a task
- Agent handing off to another agent
- Agent receiving a handoff from another agent
- Agent encountering an error mid-task
- Agent being interrupted or timed out
- Agent session termination

### 4. Corruption Detection
Specify:
- Checksum or hash mechanism for integrity verification
- Schema version field and migration rules
- Validation checks run on state load
- What the agent must do when corruption is detected (reject, rebuild, escalate)

### 5. Recovery Procedures
For each failure scenario, provide step-by-step recovery instructions:
- State file missing or unreadable
- State fails integrity check
- State schema version mismatch
- Partial state after crash
- Conflicting state from concurrent writes

### 6. Handoff State Package
Define the exact payload this agent passes to another agent during handoff:
- Required fields and their sources
- Format specification
- Size limits
- What must be excluded (internal-only state)

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT FORMAT
Return valid JSON matching this schema:
{
  "agent_role": "string",
  "state_schema": [
    {
      "field_name": "string",
      "type": "string",
      "required": true/false,
      "default": "string or null",
      "persistence": "durable|ephemeral|session",
      "serialization": "string"
    }
  ],
  "persistence_policy": {
    "durable_fields": ["string"],
    "write_triggers": ["string"],
    "max_total_size_bytes": number,
    "retention_hours": number
  },
  "lifecycle_events": {
    "on_init": "string",
    "on_receive_task": "string",
    "on_complete_task": "string",
    "on_handoff_out": "string",
    "on_handoff_in": "string",
    "on_error": "string",
    "on_interrupt": "string",
    "on_terminate": "string"
  },
  "corruption_detection": {
    "integrity_mechanism": "string",
    "schema_version_field": "string",
    "validation_rules": ["string"],
    "on_corruption": "reject|rebuild|escalate"
  },
  "recovery_procedures": {
    "missing_state": "string",
    "integrity_failure": "string",
    "version_mismatch": "string",
    "partial_state": "string",
    "conflicting_writes": "string"
  },
  "handoff_payload": {
    "fields": ["string"],
    "format": "string",
    "max_size_bytes": number,
    "excluded_fields": ["string"]
  }
}

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adapt this template by filling the square-bracket placeholders with your agent's specifics. The [CONSTRAINTS] field should include any regulatory, latency, or storage constraints that affect state design. The [EXAMPLES] field should contain one or two concrete state schemas from similar agents in your system to guide consistency. Set [RISK_LEVEL] to high if the agent handles financial, clinical, or personally identifiable data—this should trigger additional validation and human review of the generated contract before deployment. After generating the contract, validate the JSON output against the schema, test recovery procedures with injected failures, and confirm that handoff payloads are compatible with receiving agents.

The state management contract prompt is not a one-shot generation exercise. It is a design artifact that should be versioned alongside the agent's role definition and tool access policy. The prompt produces a structured contract—serialization format, persistence rules, recovery procedures, and corruption test cases—that the agent runtime must enforce. Treat the output as a machine-readable specification, not a prose document. The contract should be stored in a registry that the agent's state manager reads at startup, so any change to the contract triggers a state migration review before deployment.

Wire the prompt into a contract generation pipeline that runs whenever an agent role is created or modified. The pipeline should: (1) invoke the prompt with the agent's role definition, capability boundary, and tool access policy as [CONTEXT]; (2) parse the output against a strict JSON schema that validates serialization format, persistence rules, and recovery procedures; (3) run the generated corruption test cases against a sandboxed state store to verify that the recovery procedures actually work; (4) flag any contract that lacks a rollback strategy or fails to specify what happens when the state store is unreachable. If the contract references external storage (S3, Redis, Postgres), the harness must verify that the agent runtime has the necessary credentials and network access before accepting the contract. Log every contract generation with the prompt version, model, and validation results for auditability.

The highest-risk failure mode is silent state corruption that the recovery procedure cannot repair. To guard against this, implement a state integrity check on every read: compute a hash or checksum over the serialized state, compare it to a stored value, and refuse to load corrupted state. If corruption is detected, the agent must enter a degraded mode—log the incident, escalate to a human operator, and refuse to act on stale or partial state until recovery is confirmed. Do not let the agent silently continue with corrupted state. The contract's recovery procedures should be tested in CI against injected corruption scenarios (truncated files, schema mismatches, missing fields) before the contract is approved for production. Finally, monitor state size growth over time; a contract that permits unbounded accumulation will eventually cause latency spikes or storage failures, so add size thresholds and compaction rules to the contract validation step.