Agent Handoff with Suggested Actions Prompt

This prompt is a decision-support tool for agent workflows that reach an action boundary. It is designed for situations where an AI agent has analyzed a situation, identified a set of possible next steps, but is explicitly prohibited from executing them due to policy, risk, or system design. The primary job-to-be-done is to transform raw agent analysis into a structured, actionable choice for a human operator. The ideal user is a developer or AI engineer building a semi-autonomous agent system, such as a customer support copilot, a code-review bot, or a compliance monitoring agent, where the final decision must rest with a human reviewer. The prompt requires rich context: the agent's full analysis, the proposed actions, the constraints that prevent autonomous execution, and the specific decision the human needs to make.

Use this prompt when your agent has completed its analytical work and must hand off control. For example, a code-review agent might identify a security vulnerability and propose three remediation paths, but a senior engineer must choose the correct one based on broader system context. A compliance agent might flag several transactions and suggest blocking, reviewing, or escalating each, but a human analyst must make the final call. The prompt structures this handoff by forcing the agent to rank its suggestions, provide a clear rationale for each, and package the necessary evidence. This is not a generic summary prompt; it is a structured interface between agent capability and human authority. It should not be used for simple status updates, logging, or when the agent is authorized to act autonomously. If the agent can execute the action itself, use a direct tool-calling or execution prompt instead.

Before implementing this prompt, ensure you have defined a clear action boundary in your agent's system prompt. The agent must know it is a recommender, not an executor. The harness should validate that the output contains a ranked list, explicit rationales, and all context a human needs to decide without re-analyzing raw data. Common failure modes include the agent providing unranked lists, omitting the rationale, or failing to include the specific decision the human must make. In high-risk domains like finance or healthcare, the harness must also log the handoff for audit trails and require explicit human acknowledgment before any downstream system acts on the decision. If the human's choice will be fed back into the agent system, design a separate prompt to ingest that decision and continue the workflow.

This prompt template is designed to be pasted directly into your agent's handoff instruction block. It forces the agent to produce a structured handoff payload containing a ranked list of suggested actions, the rationale behind each, and the evidence a human reviewer needs to choose among them. The agent must not execute any of the suggested actions—it only proposes them. Replace every square-bracket placeholder with values from your runtime context before the agent processes the handoff.

textCopy
You are an agent that has completed analysis but lacks authority to execute the next steps. Your task is to produce a structured handoff for a human reviewer. Do not take any action beyond producing this handoff.

## Context
- Task: [TASK_DESCRIPTION]
- Agent Actions Taken: [ACTIONS_ALREADY_PERFORMED]
- Constraints: [CONSTRAINTS]
- Risk Level: [RISK_LEVEL]

## Output Schema
Return a JSON object with the following structure:
{
  "handoff_summary": "A 2-3 sentence summary of what the agent did and why a human decision is needed.",
  "suggested_actions": [
    {
      "rank": 1,
      "action": "Clear, imperative description of the proposed action.",
      "rationale": "Why this action is proposed, including trade-offs considered.",
      "evidence": ["Source or observation that supports this action."],
      "risk_if_taken": "What could go wrong if this action is executed.",
      "risk_if_not_taken": "What could go wrong if this action is skipped."
    }
  ],
  "decision_deadline": "ISO 8601 timestamp or 'none' if no deadline.",
  "questions_for_human": ["Specific questions the human must answer to make a decision."]
}

## Rules
1. Rank suggested actions by urgency and impact, with rank 1 being the strongest recommendation.
2. Every suggested action must include at least one piece of supporting evidence.
3. If you are uncertain about any field, mark it with a confidence note: "[LOW CONFIDENCE] reason."
4. Do not fabricate evidence. If evidence is missing, state "No direct evidence available."
5. If the risk level is [HIGH] or [CRITICAL], include an explicit warning in the handoff_summary.
6. Limit suggested actions to a maximum of [MAX_ACTIONS] items.

After pasting this template, wire the output into your human review queue. Validate that the JSON conforms to the schema before presenting it to a reviewer. For high-risk workflows, log every handoff payload with a timestamp and reviewer identity for audit trails. If the agent produces malformed JSON, retry once with a repair prompt; if it fails again, escalate the raw agent output to a human operator with a note that the handoff structure is broken.

The Agent Handoff with Suggested Actions prompt is designed to sit at the boundary between an autonomous agent and a human reviewer. In a typical implementation, the agent reaches a decision point where it has identified candidate next steps but lacks the authority to execute them. The harness calls this prompt with the agent's current state, context, and analysis, and the model returns a structured handoff payload containing ranked suggested actions, rationale for each, and the information a human needs to choose among them. This payload is then surfaced in a review queue, dashboard, or notification system where a human operator can review and select an action.

The implementation harness must enforce a strict output schema. Define a JSON schema that includes: a handoff_summary string, a suggested_actions array where each item has an action_id, rank (integer), title, description, rationale, risks (array of strings), expected_outcome, and required_inputs (array of field names the human must provide if this action is selected), and a context_for_reviewer object containing agent_identity, task_id, confidence_scores per action, and evidence_references linking claims to source data. Validate the model's output against this schema before presenting it to the human. If validation fails, retry once with the schema error included in the prompt. If the retry also fails, log the failure and escalate the raw agent state to a human operator with a note that structured handoff generation failed.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities. For high-stakes workflows, prefer models that support constrained decoding or JSON mode to reduce schema drift. Implement a review audit trail that captures: the agent state at handoff time, the full prompt sent, the raw model response, the validated structured output, the human's selected action, and the timestamp of selection. This audit trail is critical for governance, debugging handoff quality, and improving the prompt over time. Do not allow the agent to proceed with any suggested action until the human explicitly selects one through the review interface. The harness should treat the handoff as a blocking gate, not a notification that can be ignored.

Common failure modes to guard against: the model may suggest actions that are too vague to be actionable, rank actions without clear differentiation, omit critical risks, or hallucinate evidence references. Implement eval checks that run on a sample of handoff outputs before deployment. Each eval should verify that every suggested action includes a concrete next step a human can take, that the rationale is grounded in the provided context, that risks are specific to the action rather than generic disclaimers, and that evidence references point to actual source spans when source material is provided. Track false-positive escalations where the agent could have safely proceeded and false negatives where the agent failed to escalate a genuinely ambiguous or risky situation. Use these metrics to tune confidence thresholds and improve the prompt's escalation criteria.