Session State Snapshot Prompt for Handoff

This prompt is designed for platform engineers and orchestration system builders who need a machine-readable, lossless serialization of an agent's complete internal state immediately before a handoff to another agent. The core job-to-be-done is not summarization or human-readable logging; it is creating a strict contract that allows a receiving agent to deserialize the payload and resume execution exactly where the previous agent left off. You should reach for this prompt when your multi-agent pipeline has a hard dependency on state continuity—for example, when Agent B must continue a multi-step tool-use sequence initiated by Agent A, or when an agent is being preempted and its successor must honor all pending actions, partial results, and unresolved dependencies without re-deriving them from scratch.

The ideal user is an infrastructure engineer wiring together an agent orchestration framework where state transfer is a programmatic operation, not a conversational one. The required context includes the active goal stack, in-progress tool calls with their request IDs and partial responses, unresolved dependencies that block downstream steps, and any session-scoped variables or constraints the agent was operating under. The output is a structured JSON payload with explicit schema versioning, integrity checksums, and a resume_instructions block that tells the receiving agent how to pick up execution. Do not use this prompt when the receiving agent only needs a high-level summary of what happened, when the state is too large to fit in a single context window without aggressive pruning (use the Agent Working Memory Summarization Prompt first), or when the handoff is to a human reviewer who needs a narrative, not a machine contract.

Before implementing this prompt in production, validate that your receiving agent can actually deserialize and act on every field in the snapshot. A common failure mode is producing a perfectly valid snapshot that the downstream agent ignores because its system prompt was not designed to parse resume_instructions. Pair this prompt with a deserialization test harness that feeds the snapshot into the receiving agent and asserts that it takes the correct next action. For high-risk pipelines—such as those involving financial transactions, clinical data, or irreversible side effects—add a human approval gate that reviews the snapshot for completeness before the handoff executes. If your handoff frequency is high, also instrument a completeness eval that flags snapshots missing required fields like pending_tool_calls or active_goals before they reach the receiving agent.

This prompt template captures the complete working state of an agent before a handoff. It forces the model to produce a machine-readable snapshot containing active goals, partial results, pending actions, and unresolved dependencies. The output is designed to be validated programmatically before the receiving agent ingests it, preventing silent context loss.

textCopy
You are an agent state serializer. Your task is to produce a complete, structured snapshot of the current session state for handoff to another agent.

## INPUT
Agent Identity: [AGENT_ID]
Current Task: [TASK_DESCRIPTION]
Conversation History: [CONVERSATION_HISTORY]
Tool Call Log: [TOOL_CALL_LOG]
Active Goals: [ACTIVE_GOALS]
Partial Results: [PARTIAL_RESULTS]
Pending Actions: [PENDING_ACTIONS]
Unresolved Dependencies: [UNRESOLVED_DEPENDENCIES]
Session Metadata: [SESSION_METADATA]

## OUTPUT SCHEMA
Return a single JSON object with the following structure. Every field is required unless marked optional.

{
  "snapshot_version": "1.0",
  "agent_id": "string",
  "timestamp": "ISO-8601 UTC string",
  "session_id": "string",
  "handoff_priority": "low | medium | high | critical",
  "state_summary": "One-paragraph natural language summary of current state for human review.",
  "active_goals": [
    {
      "goal_id": "string",
      "description": "string",
      "status": "not_started | in_progress | blocked | completed",
      "priority": 1-5,
      "blocked_by": ["goal_id"]
    }
  ],
  "partial_results": [
    {
      "result_id": "string",
      "description": "string",
      "data": {},
      "confidence": 0.0-1.0,
      "source": "tool_call_id | agent_id | user_input",
      "needs_verification": true | false
    }
  ],
  "pending_actions": [
    {
      "action_id": "string",
      "type": "tool_call | agent_query | human_approval | wait",
      "description": "string",
      "target": "tool_name | agent_id | human_role",
      "deadline": "ISO-8601 UTC string or null",
      "depends_on": ["action_id"]
    }
  ],
  "unresolved_dependencies": [
    {
      "dependency_id": "string",
      "description": "string",
      "required_from": "agent_id | tool_name | human_role",
      "blocking_goals": ["goal_id"],
      "timeout": "ISO-8601 UTC string or null"
    }
  ],
  "context_window_usage": {
    "tokens_used": 0,
    "tokens_remaining": 0,
    "critical_context_snippets": ["string"]
  },
  "errors_and_warnings": [
    {
      "severity": "error | warning | info",
      "message": "string",
      "related_action_id": "string or null"
    }
  ],
  "handoff_notes": "Free-text notes for the receiving agent about edge cases, assumptions, or risks."
}

## CONSTRAINTS
- Every array field must be present, even if empty.
- All IDs must be consistent with the input data.
- Do not invent goals, results, or actions not present in the input.
- If a field is unknown, use null for scalars and [] for arrays.
- The state_summary must be understandable without reading the full conversation.
- Include enough detail in partial_results.data for the receiving agent to continue work without replaying tool calls.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Before sending this prompt, replace every square-bracket placeholder with live data from the agent runtime. The [FEW_SHOT_EXAMPLES] placeholder should contain 1-2 example snapshots showing correct serialization of goals, partial results, and dependencies. For high-risk domains, set [RISK_LEVEL] to high and add a constraint requiring the receiving agent to confirm deserialization integrity before acting on the snapshot. After receiving the output, validate the JSON schema, check that all referenced IDs are consistent, and verify that no active goal is missing from the snapshot before passing it to the next agent.

The Session State Snapshot prompt is a critical infrastructure component in any multi-agent system where handoff integrity determines downstream correctness. It should be called by the orchestration layer immediately before an agent yields control, not by the agent itself. The orchestrator collects the agent's internal working state—active goals, partial results, pending tool calls, unresolved dependencies—and passes it through this prompt to produce a canonical, serializable snapshot. This snapshot becomes the single source of truth for the next agent in the chain. Treat the snapshot as an immutable artifact: once generated, it should be stored with a version identifier and checksum before being passed to the receiving agent.

Wire the prompt into a dedicated snapshot_agent_state function within your orchestration service. This function should accept the raw agent context (conversation turns, tool outputs, internal scratchpad) and return a validated JSON object conforming to your state schema. Implement a validation layer immediately after the model response: check that all required fields (active_goals, partial_results, pending_actions, session_metadata) are present, that timestamps are ISO 8601, that goal IDs are unique, and that no dangling references point to non-existent entities. If validation fails, retry the prompt once with the validation errors appended to the [CONSTRAINTS] block. If the second attempt also fails, log the failure, preserve the raw agent context, and escalate to a human operator rather than passing corrupted state downstream. For high-reliability systems, add a round-trip deserialization test: serialize the snapshot, deserialize it, and compare field-by-field against the original to catch truncation or encoding errors.

Model choice matters here. Use a model with strong structured output capabilities and a large enough context window to hold the full agent state without truncation. Enable structured output mode (e.g., OpenAI's response_format with a JSON Schema, or equivalent constrained generation) to reduce malformed output risk. For production deployments, instrument the snapshot generation with observability hooks: log the input token count, output token count, validation pass/fail status, retry count, and snapshot size. Set alerts on snapshot size spikes (which may indicate unbounded state growth) and on validation failure rates exceeding 2%. Avoid calling this prompt inside tight agent loops where latency is critical—batch snapshot generation at natural handoff boundaries instead. The snapshot artifact should be stored in your shared state store with a TTL that matches your session retention policy, and it should be queryable by session_id for debugging and audit purposes.