Input/Output Contract Definition Prompt for Sub-Agents

This prompt is for integration engineers and platform developers who need to define strict, machine-readable contracts between an orchestrator agent and its sub-agents. The job-to-be-done is converting a natural language task description into a typed schema that a sub-agent must satisfy, eliminating ambiguity about required fields, data types, enum constraints, and error handling expectations. Use this when you are building a multi-agent system where downstream agents consume structured output from upstream agents, and a parsing failure or missing field would break the entire workflow.

The ideal user has already decomposed a complex task into sub-tasks and assigned them to specialized agents. They now need to lock down the data contract for a specific sub-agent before it executes. Required context includes the sub-agent's assigned task description, the expected output schema (even if rough), any known constraints (e.g., date formats, allowed enum values), and the risk level of the workflow. Do not use this prompt for open-ended creative generation, for agents that return unstructured natural language, or when the contract is so simple that a one-line JSON schema would suffice. It is overkill for trivial data shapes and underkill for workflows that require legal or clinical review—those should always include a human-in-the-loop step.

The prompt produces a complete contract definition: required fields with types and descriptions, optional fields with defaults, enum constraints, validation rules, and explicit error handling expectations for the sub-agent. It also generates schema validation tests and contract compliance checks that you can wire directly into your agent harness. Before using the output, verify that the contract does not over-constrain the sub-agent to the point of brittleness—every required field should have a clear downstream consumer. If a field exists only for hypothetical future use, mark it optional. The next step is to feed this contract into your sub-agent's system prompt and pair it with the Sub-Task Output Validation Contract Prompt Template to build an automated acceptance gate.

This prompt template produces a typed contract definition that a sub-agent must fulfill. The contract specifies required fields, optional fields, enum constraints, data types, validation rules, and error handling expectations. Use this template when you need to define the exact shape of data that a sub-agent will receive and must return, ensuring that orchestrators can validate outputs programmatically before passing results to downstream agents or systems.

codeCopy
You are defining a strict input/output contract for a sub-agent that will execute a specific task. The contract must be machine-validatable and unambiguous.

## Task Description
[TASK_DESCRIPTION]

## Required Inputs
Define every input the sub-agent needs to execute this task. For each input, specify:
- Field name
- Data type (string, integer, float, boolean, array, object)
- Whether it is required or optional
- Valid values, ranges, or regex patterns
- Default value if optional and omitted
- Example value

## Required Outputs
Define every output the sub-agent must produce. For each output, specify:
- Field name
- Data type
- Whether it is required or optional
- Valid values, ranges, or regex patterns
- Null handling rules (when can this field be null?)
- Example value

## Constraints
[CONSTRAINTS]

## Validation Rules
Define rules that the orchestrator will use to validate the sub-agent's output before accepting it:
- Schema compliance checks
- Business logic rules (e.g., start_date must be before end_date)
- Cross-field validation rules
- Completeness checks (all required fields present and non-null)

## Error Handling Contract
Define how the sub-agent must signal errors:
- Error code field and valid error codes
- Error message format
- Partial result rules (can the agent return partial results with errors?)
- Retry eligibility (which errors are retryable?)

## Output Schema
Produce the contract as a JSON Schema object with the following structure:
{
  "contract_version": "1.0",
  "task_type": "string identifying the task",
  "inputs": { ... JSON Schema for inputs ... },
  "outputs": { ... JSON Schema for outputs ... },
  "validation_rules": [
    {
      "rule_id": "string",
      "description": "human-readable rule",
      "field_path": "jsonpath to field(s)",
      "condition": "expression or predicate",
      "severity": "error | warning"
    }
  ],
  "error_contract": {
    "error_field": "field name for error codes",
    "valid_error_codes": ["list of codes"],
    "partial_results_allowed": true/false,
    "retryable_errors": ["list of retryable codes"]
  }
}

## Risk Level
[RISK_LEVEL]

## Examples
[EXAMPLES]

Adapt this template by replacing the square-bracket placeholders with concrete values. For [TASK_DESCRIPTION], provide a clear statement of what the sub-agent must accomplish. For [CONSTRAINTS], list any domain-specific rules, such as regulatory requirements, data residency restrictions, or latency budgets. For [RISK_LEVEL], specify whether the task is low-risk (automated validation sufficient), medium-risk (require human spot-checking), or high-risk (require full human review before downstream consumption). For [EXAMPLES], provide one or two valid input/output pairs that demonstrate correct contract fulfillment. After generating the contract, validate it against your actual sub-agent implementations by running schema compliance tests and checking that all required fields are populated in representative outputs.

The contract definition prompt is not a standalone utility; it is a pre-execution gate inside an agent orchestration layer. Before any sub-agent receives a task, the orchestrator calls this prompt to produce a typed contract—a machine-readable schema that defines required fields, optional fields, enum constraints, data types, and validation rules. The output of this prompt becomes the input to two downstream systems: the sub-agent that must satisfy the contract, and the validation harness that will reject non-conforming outputs. Wire this prompt into your orchestration framework as a synchronous step after task decomposition and before sub-agent dispatch. If the contract generation fails or produces an invalid schema, do not proceed to execution—re-prompt with more context or escalate to a human operator.

Model choice and structured output enforcement. Use a model that supports strict structured output modes (e.g., GPT-4o with response_format set to json_schema, or Claude 3.5 Sonnet with tool-use mode for schema generation). Pass the contract definition prompt with a pre-registered JSON Schema that describes the contract object itself: task_id, agent_role, input_schema, output_schema, validation_rules, error_handling, and example_valid_output. This ensures the model returns a parseable contract, not free text. On the application side, validate the returned contract against this meta-schema immediately. If validation fails, retry once with the validation error injected into the prompt as additional [CONSTRAINTS]. After two failures, log the full prompt and response, then route to a human reviewer or a fallback default contract template.

Validation, logging, and contract compliance checks. Once a sub-agent completes its task, the orchestrator must validate its output against the contract's output_schema and validation_rules fields. Implement this as a two-stage check: first, structural validation (does the JSON match the schema? are required fields present? do enum values match allowed sets?); second, semantic validation using the contract's custom rules (e.g., 'confidence must be between 0 and 1', 'citations must reference document IDs present in the input context'). Log every contract generation, every sub-agent output, and every validation result with the task_id as the correlation key. This traceability is essential for debugging multi-agent failures—when a downstream agent produces garbage, you need to know whether the contract was ambiguous, the sub-agent violated it, or the validation rules were too strict. For high-risk domains (legal, healthcare, finance), add a human approval step before any contract is used to gate a sub-agent that will take a destructive or irreversible action.

Retry and escalation wiring. When a sub-agent output fails contract validation, do not silently discard it. Implement a retry loop: send the sub-agent its original task, the contract, and the specific validation errors with a repair prompt. Limit retries to 2–3 attempts. If the sub-agent still cannot satisfy the contract, the orchestrator should invoke the Dynamic Re-Decomposition Prompt for Failed Sub-Tasks to re-plan the work, or escalate to a human with the full trace: original task, generated contract, sub-agent outputs, and validation failure details. Avoid the trap of loosening validation rules to reduce failures—that masks contract ambiguity and produces unreliable downstream behavior. Instead, treat persistent validation failures as a signal that the contract itself may need revision, and feed that signal back into your prompt improvement cycle.