Agent Role Handoff Readiness Checklist Prompt

This prompt is for orchestration engineers and platform builders who need to verify that a specialized agent is ready to send or receive a handoff in a production multi-agent pipeline. The job-to-be-done is operational readiness assessment: before wiring an agent into a handoff graph, you need confidence that the agent's state is complete, its context is properly packaged, and it understands the acknowledgement protocol. This is not a role definition prompt; it assumes the agent's role, scope, and contracts are already defined. The prompt produces a structured readiness checklist covering state completeness, context packaging, acknowledgement protocol, and handoff failure simulation tests.

Use this prompt when you are integrating a new agent into an existing handoff pipeline, upgrading an agent's handoff behavior, or debugging handoff failures in production. It is particularly valuable when the handoff involves structured payloads, shared state, or acknowledgement requirements. Do not use this prompt for initial agent role design (use the Agent Role Definition Prompt Template instead), for defining handoff message schemas (use the Agent Communication Protocol Prompts), or for runtime handoff execution (this is a pre-flight readiness check, not a runtime orchestrator). The prompt expects the agent's role contract, input/output schemas, and tool access policy as input context.

The prompt generates a checklist with four sections: state completeness (what must be persisted before handoff), context packaging (what must be included in the handoff payload), acknowledgement protocol (how the agent confirms receipt or signals rejection), and failure simulation tests (edge cases that break the handoff). Each checklist item includes a pass/fail criterion and a severity rating. For high-risk domains, the output should be reviewed by a human before the agent is promoted to production. After generating the checklist, run the failure simulation tests against the agent in a sandbox environment and verify that all critical items pass before enabling production handoffs.

This template generates a comprehensive readiness assessment for an agent about to participate in a handoff. It verifies state completeness, context packaging, and acknowledgement protocol adherence before the handoff occurs. The prompt is designed to be pasted directly into your orchestration layer, evaluation harness, or CI pipeline. All placeholders use square brackets and must be replaced with concrete values before execution.

codeCopy
You are an agent reliability engineer auditing handoff readiness.

Your task is to evaluate whether [AGENT_NAME] is ready to [HANDOFF_DIRECTION: send to / receive from] [TARGET_AGENT_OR_SYSTEM] for the task described below.

## Agent Role Contract
[AGENT_ROLE_CONTRACT]

## Current Agent State
- Internal state summary: [AGENT_STATE_SUMMARY]
- Pending actions: [PENDING_ACTIONS]
- Unresolved dependencies: [UNRESOLVED_DEPENDENCIES]

## Handoff Context
- Task being handed off: [TASK_DESCRIPTION]
- Expected handoff payload schema: [HANDOFF_PAYLOAD_SCHEMA]
- Acknowledgement protocol: [ACK_PROTOCOL]
- Timeout window: [TIMEOUT_MS]ms

## Constraints
[CONSTRAINTS]

## Output Schema
Produce a JSON object with this exact structure:
{
  "readiness_assessment": {
    "overall_status": "READY" | "NOT_READY" | "CONDITIONAL",
    "checks": [
      {
        "check_id": "string",
        "category": "STATE_COMPLETENESS" | "CONTEXT_PACKAGING" | "ACK_PROTOCOL" | "DEPENDENCY_RESOLUTION" | "ERROR_HANDLING",
        "description": "string",
        "status": "PASS" | "FAIL" | "WARN",
        "detail": "string explaining the finding",
        "blocking": true | false
      }
    ],
    "blocking_failures": ["check_id"],
    "warnings": ["check_id"],
    "recommended_actions": ["string"],
    "estimated_remediation_time_minutes": number
  },
  "handoff_payload_validation": {
    "schema_conformance": "PASS" | "FAIL",
    "missing_required_fields": ["string"],
    "field_type_violations": [{"field": "string", "expected": "string", "actual": "string"}]
  },
  "failure_simulation_results": [
    {
      "scenario": "string describing the failure mode",
      "expected_behavior": "string",
      "detection_mechanism": "string",
      "recovery_procedure": "string",
      "current_readiness": "READY" | "GAP" | "UNKNOWN"
    }
  ],
  "handoff_contract_test": {
    "preconditions_met": true | false,
    "postconditions_achievable": true | false,
    "invariant_violations": ["string"]
  }
}

## Failure Simulation Scenarios to Test
Include at minimum these scenarios in your analysis:
1. [AGENT_NAME] has incomplete internal state at handoff time
2. Handoff payload is missing required fields from [HANDOFF_PAYLOAD_SCHEMA]
3. [TARGET_AGENT_OR_SYSTEM] does not acknowledge receipt within [TIMEOUT_MS]ms
4. [AGENT_NAME] receives conflicting instructions mid-handoff
5. Network partition or tool unavailability during handoff transmission

## Instructions
1. Evaluate every check category against the agent role contract and current state.
2. Mark any check as blocking if failure would cause data loss, duplicate work, or silent handoff failure.
3. For each failure simulation scenario, determine whether the current agent configuration can detect and recover from the failure.
4. If overall_status is CONDITIONAL, list exactly which conditions must be satisfied before handoff can proceed.
5. Do not invent state or capabilities not present in the provided inputs.
6. If critical information is missing, flag it as a blocking failure with detail explaining what is needed.

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

To adapt this template, replace each square-bracket placeholder with concrete values from your agent registry and orchestration configuration. The [AGENT_ROLE_CONTRACT] should contain the full role definition including scope, authority, and stop conditions. The [HANDOFF_PAYLOAD_SCHEMA] must be a valid JSON Schema or structured type definition that the receiving system expects. For high-risk domains such as healthcare or finance, add a [RISK_LEVEL] field set to HIGH and require human review of any NOT_READY or CONDITIONAL assessment before the handoff proceeds. The failure simulation scenarios are mandatory minimums; extend them with domain-specific failure modes relevant to your agent topology.

After generating the checklist, validate the output against the schema before passing it to your orchestration layer. A blocking failure in STATE_COMPLETENESS or CONTEXT_PACKAGING should halt the handoff pipeline. Warnings in ACK_PROTOCOL may allow the handoff to proceed with additional logging. Store the full assessment in your agent audit trail for post-incident analysis. Do not treat this prompt as a one-time gate; re-run it whenever the agent's role contract, state schema, or handoff protocol changes.

The Agent Role Handoff Readiness Checklist Prompt is designed to act as a pre-handoff gate in a multi-agent orchestration system. Before an orchestrator transfers context or a task to a downstream agent, it calls this prompt with the current agent's state, the target agent's input contract, and the pending handoff payload. The prompt returns a structured readiness assessment that the orchestrator parses to decide whether to proceed, repair, or escalate. This is not a one-shot generation prompt—it is a decision-support checkpoint that should be wired into the orchestration control flow with clear success criteria and failure paths.

To integrate this prompt into an application, wrap it in a function that accepts three required inputs: the source agent's current state summary, the target agent's input contract (schema, required fields, preconditions), and the proposed handoff payload. The function should call the model with response_format set to a strict JSON schema matching the checklist output—fields like readiness_score, missing_context, contract_violations, acknowledgement_protocol_status, and recommended_action. After receiving the response, validate it against the expected schema. If validation fails, retry once with the validation errors appended to the prompt as [REPAIR_INSTRUCTIONS]. If the readiness score falls below a configurable threshold (e.g., 0.8), route to a repair agent or escalate to a human reviewer with the full checklist output attached. Log every handoff readiness check—including the input state, the checklist result, and the final routing decision—for auditability and debugging.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) because the checklist requires precise reasoning about contract compliance and state completeness. Avoid smaller or older models that may hallucinate field values or skip checklist items. For high-throughput pipelines, consider caching the target agent's input contract schema so it is not repeatedly sent in full. The prompt includes a handoff failure simulation test section—run this periodically against your deployed prompt version to verify it still detects common failure modes like missing required fields, stale context, or unacknowledged state transfers. If the prompt starts missing simulated failures, it is time to review and update the template. Do not use this prompt for real-time handoffs where latency must be under 500ms; the structured reasoning step adds meaningful inference time. In those cases, pre-compute readiness checks or use a lightweight classifier for the fast path and reserve this full checklist for high-risk or complex handoffs.