Multi-Turn State Contract Definition Prompt

This prompt is for agent platform teams who need to define an explicit, typed state contract before building a multi-turn tool-use agent. The job-to-be-done is converting an informal understanding of what the agent should remember across turns into a machine-readable schema that governs state initialization, field updates, merge semantics, and validation rules. The ideal user is an infrastructure developer or AI engineer who is integrating a stateful agent into a production system and needs the contract to be enforced programmatically, not just described in a design doc. Required context includes a list of all tools the agent can call, the data each tool produces or requires, and the expected lifecycle of a session (e.g., short-lived task vs. long-running conversation).

Do not use this prompt when the agent is stateless, when all context is passed inline by the application layer, or when you are prototyping a single-turn workflow. It is also the wrong tool if you are looking for a generic system prompt that describes agent behavior—this prompt produces a state schema, not behavioral instructions. The output is a technical artifact meant to be consumed by validation harnesses, context management middleware, and state reconciliation logic. If your team does not have the infrastructure to enforce the contract at runtime, the schema will become documentation that drifts from reality. In high-risk domains such as healthcare, finance, or safety-critical operations, the generated contract must be reviewed by a human who understands the domain's data integrity requirements before it is wired into production.

Before using this prompt, gather the tool definitions, expected session duration, and any existing state management patterns your platform already enforces. The prompt works best when you provide concrete tool schemas and example turns rather than abstract descriptions. After generating the contract, the next step is to implement the validation harness described in the Implementation Harness section, which will catch schema violations, drift, and incomplete state before they corrupt agent reasoning.

This prompt template produces a typed state contract for an agent that calls tools across multiple turns. It forces explicit decisions about which fields are required, which are optional, how each field is updated per turn, and what happens when tool results conflict. Use this template before building the agent's execution loop—it becomes the source of truth that your state manager, validators, and evals all reference. The output is a machine-readable schema plus human-readable rules, not a generic description of state.

textCopy
You are defining a typed state contract for a multi-turn agent that uses external tools. The agent maintains state across tool calls, and each turn may read or update that state. Your job is to produce a complete, unambiguous contract that a state manager can enforce.

## INPUTS
- Agent purpose: [AGENT_PURPOSE]
- Available tools and their schemas: [TOOL_SCHEMAS]
- Maximum turns per session: [MAX_TURNS]
- Risk level: [RISK_LEVEL]  // one of: low, medium, high, critical
- Regulatory context (if any): [REGULATORY_CONTEXT]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "contract_version": "string",
  "state_schema": {
    "required_fields": [
      {
        "name": "string",
        "type": "string",
        "description": "string",
        "source": "string",  // which tool or input populates this field initially
        "update_rule": "replace | append | merge | conditional",
        "merge_strategy": "string | null",  // required if update_rule is merge
        "validation": "string",  // regex, range, enum, or custom rule
        "nullable": false
      }
    ],
    "optional_fields": [ /* same structure as required_fields */ ]
  },
  "turn_rules": [
    {
      "turn_number": 1,
      "allowed_tools": ["string"],
      "required_state_before": ["string"],
      "state_updates": [
        {
          "field": "string",
          "action": "set | append | merge | delete",
          "condition": "string | null"
        }
      ],
      "conflict_resolution": "string"
    }
  ],
  "conflict_rules": {
    "same_turn_conflict": "string",
    "cross_turn_staleness": "string",
    "tool_result_divergence": "string"
  },
  "drift_detection": {
    "checks": ["string"],
    "remediation": "string"
  },
  "human_approval_gates": [
    {
      "trigger": "string",
      "fields_under_review": ["string"],
      "approval_action": "string"
    }
  ]
}

## CONSTRAINTS
- Every field in state_schema must have an explicit update_rule. Do not use "implicit" or "context-dependent" as a rule.
- Turn rules must cover every turn from 1 to [MAX_TURNS]. If later turns are open-ended, define the pattern that repeats.
- Conflict rules must handle: two tools writing the same field in one turn, a tool returning data that contradicts prior state, and state that has not been refreshed for more than [STALENESS_THRESHOLD] turns.
- If [RISK_LEVEL] is high or critical, every state mutation must have a corresponding human_approval_gate entry.
- Drift detection checks must be executable by a validator, not subjective. Use field-level comparisons, schema checks, and timestamp-based staleness.
- Do not invent tools. Use only the tools provided in [TOOL_SCHEMAS].
- If [REGULATORY_CONTEXT] is provided, add an "audit_fields" array to state_schema containing every field that must appear in audit logs.

## EXAMPLES
[EXAMPLES]

## OUTPUT
Return only the JSON object. No markdown fences, no commentary.

Adaptation notes: Replace every square-bracket placeholder before use. [TOOL_SCHEMAS] should contain the actual JSON schemas of your tools, not just names—the model needs argument types and return shapes to define update rules correctly. [EXAMPLES] is critical: provide at least two worked examples showing a complete contract for a simpler agent so the model learns the expected level of detail. If you omit examples, the output will be vague about merge strategies and conflict resolution. For high-risk domains, add a post-generation step that runs the contract through a schema validator and a human reviewer before it touches production state.

The Multi-Turn State Contract Definition Prompt is designed to be called before any tool execution begins in a new agent session or when a new tool is registered dynamically. It should run as a synchronous pre-flight step inside the agent's orchestration layer, not as a one-off design exercise. The prompt expects a description of the agent's purpose, the available tools and their schemas, and the expected multi-turn interaction pattern. Its output is a typed state contract—a JSON Schema object plus merge rules—that the agent runtime can use to initialize, validate, and update state across turns. Wire this prompt into your agent framework's session initialization hook or tool registration handler so that every session starts with an explicit, machine-readable contract rather than an implicit, drift-prone state model.

After the prompt returns the contract, the harness must perform three validation steps before accepting it. First, validate the output against a JSON Schema that requires stateSchema (a valid JSON Schema object), requiredFields, optionalFields, updateRules (a map from field name to replace, merge, append, or conditional), and driftDetection (a list of invariants to check each turn). Reject and retry if the schema is malformed or missing required keys. Second, cross-check that every field referenced in updateRules and driftDetection exists in stateSchema.properties. Third, run a deterministic merge simulation: apply a synthetic sequence of tool results against the update rules and verify no field ends up in an undefined state. Log the contract version, the model that generated it, and the validation result. For high-stakes agent deployments (finance, healthcare, infrastructure control), require a human reviewer to approve the contract before it goes live, and store the approved contract as an immutable artifact in your agent's configuration store.

At runtime, the agent executor should load the approved contract and use it to initialize an empty state object with requiredFields set to null or explicit defaults. After each tool call, the harness must apply the tool's output to the state object using the updateRules map—do not rely on the model to remember state correctly across turns. Before each subsequent tool call, run the driftDetection invariants against the current state; if any invariant fails, pause the agent, log the violation, and either request a state repair from the model or escalate to a human operator. Avoid wiring this prompt as a one-shot generator with no runtime enforcement. The contract is only as valuable as the harness that enforces it. For model choice, prefer a model with strong schema-following behavior (GPT-4o, Claude 3.5 Sonnet, or equivalent) and set temperature=0 to maximize contract stability. If your platform supports multiple models, generate the contract with the strongest available model and enforce it with a lighter model at runtime.