Multi-Agent Handoff Record Prompt Template

This prompt is designed for orchestration engineers and platform builders who need to produce a standardized, machine-readable handoff record when one agent transfers work to another. The primary job-to-be-done is generating a structured payload that captures the current task state, completed steps, pending actions, unresolved ambiguities, and relevant context—ensuring the receiving agent can resume work without re-discovering what already happened. Use this when your multi-agent system has explicit handoff points between specialized agents, and you need traceable, auditable context transfers rather than ad-hoc message passing.

Do not use this prompt for simple chat message forwarding, single-agent task decomposition, or scenarios where agents share a persistent memory store and don't need explicit handoff artifacts. It is also inappropriate for real-time streaming handoffs where latency constraints prevent structured record generation. The prompt assumes you have access to the sending agent's execution trace, tool call history, and current state representation. Required inputs include: the sending agent's role identifier, the receiving agent's role identifier, the original user request, completed steps with outcomes, pending actions with dependencies, unresolved questions or ambiguities, relevant context snippets, and any constraints or policies the receiving agent must respect. Without these inputs, the handoff record will be incomplete and the receiving agent will operate with degraded context.

Before deploying this prompt into production, implement schema validation on the generated handoff payload to catch missing required fields, malformed timestamps, or truncated context arrays. Silent data loss during handoff is the most common failure mode in multi-agent systems—a missing pending_actions field or an empty unresolved_ambiguities array can cause the receiving agent to skip critical work. Pair this prompt with a validation step that checks field presence, type correctness, and context completeness before the handoff is accepted. For high-risk workflows involving financial decisions, healthcare data, or compliance-sensitive operations, route handoff records through a human review queue before the receiving agent acts on them. The next step after reading this section is to review the prompt template, adapt the output schema to your agent communication protocol, and wire it into your orchestration layer with validation and logging.

This prompt template is the core of the handoff record playbook. It instructs a model to act as an orchestration logger, consuming the raw state of a completed agent task and producing a structured, machine-readable payload. The payload is designed to be the single source of truth for what the next agent receives, eliminating ambiguity and silent context loss. Every field is intentional: it captures not just what was done, but what was left undone, what is uncertain, and what constraints the receiving agent must respect. Use this template directly in your orchestration layer, passing the output to the next agent's context window or storing it in an audit log.

textCopy
You are an Agent Handoff Recorder. Your only job is to produce a valid JSON object that captures the complete state of a task transfer from one agent to another. Do not perform the task. Do not continue the work. Only document the transfer.

Generate a JSON object conforming to the schema below, using the provided inputs.

[OUTPUT_SCHEMA]
{
  "handoff_id": "string, unique identifier for this transfer event",
  "timestamp": "string, ISO 8601 UTC timestamp of the handoff",
  "from_agent": {
    "agent_id": "string",
    "agent_role": "string, e.g., 'ResearchAgent', 'CodeAnalysisAgent'"
  },
  "to_agent": {
    "agent_id": "string",
    "agent_role": "string"
  },
  "task_summary": {
    "original_objective": "string, the high-level goal from the user or upstream agent",
    "completed_steps": [
      {
        "step_id": "string",
        "description": "string, what was done",
        "outcome": "string, the result or artifact produced",
        "evidence_refs": ["string, pointer to log entry, tool output, or file"]
      }
    ],
    "pending_actions": [
      {
        "action_id": "string",
        "description": "string, what still needs to be done",
        "reason_incomplete": "string, e.g., 'blocked by missing data', 'delegated to next agent', 'out of scope'",
        "suggested_owner": "string, agent_id or 'human'"
      }
    ],
    "unresolved_ambiguities": [
      {
        "ambiguity_id": "string",
        "question": "string, the open question or unclear requirement",
        "impact": "string, how this ambiguity affects downstream work",
        "possible_interpretations": ["string"]
      }
    ]
  },
  "context_payload": {
    "key_findings": ["string, critical facts or conclusions for the next agent"],
    "relevant_data": ["string, data snippets, file paths, or variable values"],
    "constraints_for_next_agent": ["string, rules, budgets, or boundaries the next agent must follow"],
    "escalation_triggers": ["string, conditions under which the next agent should stop and escalate"]
  },
  "confidence_assessment": {
    "overall_confidence": "string, 'high' | 'medium' | 'low'",
    "low_confidence_areas": ["string, specific parts of the work that are uncertain"]
  }
}

[INPUT]
- from_agent_state: [RAW_AGENT_STATE]
- task_definition: [TASK_DEFINITION]
- handoff_policy: [HANDOFF_POLICY]

[CONSTRAINTS]
1. Populate every field. Use empty arrays [] if there are no items, never omit a field.
2. Do not invent information. If a detail is not present in the [RAW_AGENT_STATE], mark it as "unknown" or add it to "unresolved_ambiguities".
3. The "context_payload" must be self-contained. The next agent should not need to read the full agent state to understand what to do.
4. If the handoff_policy specifies a required field that is missing, add a warning to "unresolved_ambiguities".
5. Output ONLY the JSON object. No markdown fences, no explanatory text.

To adapt this template, start by mapping your agent framework's internal state representation to the [RAW_AGENT_STATE] placeholder. This is often a large, semi-structured log. The prompt's primary value is in compressing that log into the context_payload without dropping critical constraints or pending actions. The [HANDOFF_POLICY] input is a critical control point: use it to inject domain-specific rules, such as 'never transfer PII in the context_payload' or 'always include the original user query verbatim.' Before deploying, run this prompt against a golden dataset of known agent states and validate the output JSON against the schema. Common failures include omitting empty arrays, hallucinating completed steps that weren't in the log, and leaking sensitive data from the raw state into the summary. If the workflow is high-risk, route the generated handoff record to a human review queue before the next agent consumes it.

This prompt is not a standalone chat interaction; it is a structured function call inside an agent orchestration framework. The orchestrator invokes this prompt immediately before transferring control from one agent to another. The input is a machine-readable state object containing the current task, completed steps, pending actions, unresolved ambiguities, and the target agent's role contract. The output is a validated JSON payload that becomes the handoff context for the next agent. Treat this prompt as a deterministic serialization step: its job is to produce a lossless, schema-compliant record, not to summarize or interpret the state creatively.

Wire the prompt into your orchestration layer as a pre-handoff hook. Before calling the next agent, the orchestrator assembles the [CURRENT_TASK], [COMPLETED_STEPS], [PENDING_ACTIONS], [UNRESOLVED_AMBIGUITIES], and [TARGET_AGENT_ROLE] fields from the current agent's execution trace. These fields should be populated programmatically from the agent's tool call history, reasoning logs, and state store—not manually by a human. Pass the assembled object to the model with a strict JSON output schema and a low temperature setting (0.0–0.2). On response, validate the payload against the expected schema immediately. Check for missing required fields, truncated arrays, and type mismatches. If validation fails, retry once with the validation error message appended to the prompt as a correction hint. If the retry also fails, log the failure, attach the raw state object as a fallback handoff payload, and raise an alert for manual review. Never silently pass a malformed handoff record to the next agent.

For production deployments, implement three additional safeguards. First, log every handoff payload to an append-only audit store with a timestamp, workflow ID, and hash chain reference. This creates the traceability artifact that downstream audit prompts will consume. Second, implement a size budget check: if the serialized handoff payload exceeds your context window allocation for the next agent, truncate the [COMPLETED_STEPS] array by dropping the oldest entries and appending a truncated: true flag with the count of omitted steps. Third, add a human-in-the-loop circuit breaker for high-risk domains. If the [RISK_LEVEL] field is set to high or critical, route the handoff payload to a review queue before the next agent executes. The reviewer confirms that the context transfer is complete and that no safety-critical information was dropped. Model choice matters here: use a model with strong JSON mode and schema adherence (such as GPT-4o or Claude 3.5 Sonnet with structured outputs enabled) rather than a smaller, faster model that may silently drop fields or rephrase values.