Agent Handoff Dependency Contract Prompt Template

Use this prompt when you are building a multi-agent system where an upstream agent must pass structured context to a downstream agent, and a silent mismatch in that context would corrupt the downstream agent's reasoning or actions. The primary job-to-be-done is preventing runtime failures at agent boundaries by defining a machine-readable contract before any code wires the two agents together. The ideal user is a multi-agent system architect or an engineering lead who already has a dependency graph for their agents and needs to formalize the data contract for each edge in that graph. You should have a clear understanding of the upstream agent's output capabilities and the downstream agent's minimum required inputs before using this template.

This prompt is not a lightweight handoff note or a conversational summary. Do not use it for simple, best-effort context passing where the downstream agent can gracefully handle missing or malformed fields. It is also not a replacement for a full API schema definition when agents communicate over REST or gRPC; instead, it defines the semantic contract that your orchestration layer enforces. The prompt is most valuable when the cost of a bad handoff is high—for example, when a planning agent passes a task list to an execution agent, and a missing priority field causes the execution agent to process tasks in the wrong order, or when a research agent passes extracted entities to a reporting agent, and a null confidence field causes the report to present speculation as fact. In these cases, the contract acts as a runtime guard that prevents the orchestration layer from forwarding incomplete or invalid context.

Before using this prompt, map out the dependency chain between your agents. Identify every field the downstream agent requires, the expected types and value ranges, and the failure modes that occur when those fields are missing or invalid. If you cannot enumerate these requirements, start with a lighter-weight handoff summary prompt and observe failures in production before formalizing the contract. Once you have the contract, integrate it into your agent orchestration layer so that every handoff is validated against the contract before the downstream agent receives context. The next section provides the prompt template you will adapt for each agent pair in your system.

This prompt template forces an explicit contract between two agents in a dependency chain. Before wiring agents together, run this prompt with the upstream agent's output schema and the downstream agent's input requirements. The model will produce a structured handoff specification that defines required fields, expected state, failure modes, and timeout behavior. This prevents the most common multi-agent failure mode: silent context corruption at handoff boundaries where an upstream agent omits a field, changes a key name, or produces ambiguous state that the downstream agent misinterprets.

textCopy
You are defining a strict input/output dependency contract between two agents in a multi-agent system.

UPSTREAM AGENT
- Name: [UPSTREAM_AGENT_NAME]
- Role: [UPSTREAM_AGENT_ROLE]
- Output schema: [UPSTREAM_OUTPUT_SCHEMA]
- Example output: [UPSTREAM_OUTPUT_EXAMPLE]

DOWNSTREAM AGENT
- Name: [DOWNSTREAM_AGENT_NAME]
- Role: [DOWNSTREAM_AGENT_ROLE]
- Required inputs: [DOWNSTREAM_REQUIRED_INPUTS]
- Input schema: [DOWNSTREAM_INPUT_SCHEMA]

CONSTRAINTS
- Latency budget between agents: [LATENCY_BUDGET_MS]ms
- Retry policy: [RETRY_POLICY]
- Timeout behavior: [TIMEOUT_BEHAVIOR]
- Risk level: [RISK_LEVEL]

TASK
Produce a complete handoff contract with these sections:

1. FIELD MAPPING: Map every field from the upstream output to the downstream input. For each field, specify:
   - Source field name and path
   - Target field name and path
   - Required (yes/no)
   - Default value if missing
   - Transformation rule if any

2. REQUIRED STATE: List all state conditions that must be true before handoff. Include:
   - Upstream completion indicators
   - Resource availability checks
   - Data freshness constraints

3. FAILURE MODES: For each required field and state condition, define:
   - What happens if missing
   - What happens if invalid
   - What happens if stale
   - Escalation path

4. TIMEOUT CONTRACT: Define:
   - Maximum wait for upstream completion
   - Downstream behavior on timeout
   - Partial result handling
   - Cleanup requirements

5. VALIDATION CHECKLIST: A list of assertions that must pass before the downstream agent begins execution.

OUTPUT FORMAT
Return a JSON object with keys: field_mapping, required_state, failure_modes, timeout_contract, validation_checklist.

Adapt this template by filling in the square-bracket placeholders with concrete schemas from your actual agents. The upstream output schema and downstream input schema should be exact JSON Schema, TypeScript interfaces, or Pydantic models—not prose descriptions. If your agents don't have formal schemas yet, write them before running this prompt. The contract this prompt produces becomes the integration test specification for your handoff layer. Store the output alongside your agent definitions and version it. When either agent's schema changes, re-run this prompt and diff the contracts to catch breaking changes before they reach production. For high-risk workflows, add a human review step that confirms the contract before deployment.

The Agent Handoff Dependency Contract prompt is not a standalone artifact; it is a design contract that must be enforced by the application harness at runtime. The prompt produces a structured specification—typically JSON—that defines the required input fields, expected output shape, failure modes, and timeout behavior for a handoff between two agents. The harness is responsible for validating that the upstream agent's output satisfies the contract before the downstream agent is invoked, logging contract violations, and deciding whether to retry, repair, or escalate. Without runtime enforcement, even a well-written contract degrades into silent context corruption at handoff boundaries.

Wire the prompt into your agent orchestration layer as a pre-handoff validation step. After the upstream agent completes its task, serialize its output and pass it alongside the contract specification to a validator function. The validator should check: (1) all required fields from the contract are present and non-null, (2) field types match the contract's expected types, (3) enumerated values fall within the contract's allowed set, (4) timestamp or version fields indicate the data is fresh, not stale, and (5) any declared preconditions (e.g., 'upstream agent must have confirmed the file was written') are satisfied. If validation fails, log the specific contract violation with the upstream agent ID, the missing or invalid field, and the contract version. Then route to a repair path: retry the upstream agent with the contract violations as feedback, invoke a dedicated repair prompt, or escalate to a human operator if the contract defines failure_mode: escalate. For timeout behavior, implement a deadline per handoff contract; if the upstream agent does not produce output within the contract's timeout_ms, abort the handoff and follow the contract's timeout action.

Model choice matters for contract generation versus contract enforcement. Use a capable instruction-following model (GPT-4o, Claude 3.5 Sonnet, or equivalent) to generate the contract from the prompt template, because contract design requires reasoning about edge cases and failure semantics. Contract validation, however, should be implemented as deterministic application code—not a second model call—to guarantee reliability and avoid hallucinated validation results. Store each generated contract with a version identifier and the timestamp of generation. When a handoff fails, the observability layer should capture the contract version, the upstream output, the validation result, and the downstream agent's eventual input (or abort reason). This trace data is essential for debugging silent handoff corruption and for iterating on contract designs across agent versions.

Before deploying a new handoff contract to production, run it through a contract test suite. Create golden examples of valid upstream outputs and confirm the validator accepts them. Create adversarial examples with missing fields, type mismatches, stale timestamps, and unsatisfied preconditions, and confirm the validator rejects each with the correct violation message. Test the timeout path by simulating an upstream agent that exceeds the deadline. Finally, test the repair path end-to-end: inject a contract violation, confirm the repair prompt or retry loop produces a compliant output, and verify the downstream agent receives clean input. Skip any of these tests and you will discover the failure mode in production, where partial context corruption is expensive to unwind across a dependency chain.