Prompt Details
Model
(claude-5-5-sonnet)
Token size
4,031
Example input
[MULTI_AGENT_SYSTEM_DESCRIPTION]: Enterprise customer support system with multiple AI agents.
[AGENT_ROLES_AND_COMMUNICATION_REQUIREMENTS]: Supervisor Agent: Assigns and monitors tasks. Intent Agent: Identifies customer intent. Knowledge Agent: Retrieves relevant information. Response Agent: Generates customer responses. Quality Agent: Validates response accuracy.
[MESSAGE_TYPES_AND_PAYLOAD_REQUIREMENTS]: Task Assignment Task Acceptance Agent Request Agent Response Task Completion Error Notification
[TECHNOLOGY_STACK_AND_SCHEMA_FORMAT]: JSON JSON Schema Draft 2020-12 Python Pydantic
[VALIDATION_VERSIONING_AND_COMPATIBILITY_REQUIREMENTS]: Required-field validation. Strict payload validation. Semantic validation. Semantic versioning. Backward compatibility. Correlation ID tracking.
Example output
### PHASE 1: MESSAGE CONTRACT REQUIREMENTS DISCOVERY
### 1.1 System Analysis
The system contains five independent AI agents communicating through structured JSON messages.

Communication workflow:
* Customer submits a support query.
* Supervisor Agent creates a task.
* Intent Agent identifies the query category.
* Knowledge Agent retrieves relevant information.
* Response Agent generates an answer.
* Quality Agent checks the answer.
* Supervisor Agent receives the final result.
### 1.2 Agent Communication Inventory
| Agent | Responsibility | Message Role |
| ---------- | --------------------- | --------------------- |
| Supervisor | Task coordination | Producer and consumer |
| Intent | Intent classification | Producer and consumer |
| Knowledge | Information retrieval | Producer and consumer |
| Response | Answer generation | Producer and consumer |
| Quality | Response validation | Producer and consumer |
### 1.3 Message Producer-Consumer Mapping
| Producer | Consumer | Message |
| ---------- | ---------- | ------------------ |
| Supervisor | Intent | Task Assignment |
| Intent | Supervisor | Task Completion |
| Supervisor | Knowledge | Task Assignment |
| Knowledge | Supervisor | Task Completion |
| Supervisor | Response | Task Assignment |
| Response | Quality | Agent Request |
| Quality | Response | Agent Response |
| Quality | Supervisor | Task Completion |
| Any Agent | Supervisor | Error Notification |
### 1.4 Message Contract Requirements
Requirements defined
| Requirement | Design decision |
| ----------------------- | ------------------------------ |
| Message format | JSON |
| Schema format | JSON Schema |
| Schema dialect | Draft 2020-12 |
| Message identification | UUID |
| Timestamp | ISO 8601 UTC |
| Correlation | correlation_id |
| Task tracking | task_id |
| Versioning | Major.Minor.Patch |
| Unknown properties | Rejected |
| Missing required fields | Rejected |
| Invalid payload | Rejected |
| Duplicate messages | Deduplication using message_id |
Assumptions:
* Messages are exchanged through an asynchronous messaging layer.
* Delivery guarantees are not yet specified.
* Each agent has a registered identity.
* Supervisor Agent owns task assignment and final task status.
* Authentication is handled outside JSON Schema validation.
### 1.5 Required Message Categories
We will implement six primary message categories:
* TASK_ASSIGNMENT
* TASK_ACCEPTANCE
* AGENT_REQUEST
* AGENT_RESPONSE
* TASK_COMPLETION
* ERROR_NOTIFICATION
Unnecessary message categories are excluded from this initial implementation.
### 1.6 Data Ownership Rules
| Data | Owner |
| --------------------- | --------------- |
| Task ID | Supervisor |
| Intent classification | Intent Agent |
| Retrieved knowledge | Knowledge Agent |
| Generated response | Response Agent |
| Quality assessment | Quality Agent |
| Final task status | Supervisor |
Agents must not silently overwrite another agent's owned data.
### 1.7 Contract Design Constraints
The following rules apply:
* Every message must have a unique message ID.
* Every message must identify its sender and recipient.
* Every message must contain a supported schema version.
* Related messages must share a correlation ID.
* Task-related messages must contain a task ID.
* Payload structure must match the declared message type.
* Invalid messages must not enter agent processing.
* Error messages must not expose credentials or confidential customer data.
### Phase 1 Deliverable
Requirements Discovery
Completed
### 7/7
Core discovery areas covered
* Agent inventory
* Communication relationships
* Producer-consumer mapping
* Message categories
* Data ownership
* Validation requirements
* Contract constraints
### PHASE 2: AGENT MESSAGE TAXONOMY
### 2.1 Message Classification
We define six message types.
| Message Type | Purpose | Expected Response |
| ------------------ | ---------------------------- | --------------------------- |
| TASK_ASSIGNMENT | Assign work | TASK_ACCEPTANCE |
| TASK_ACCEPTANCE | Accept assigned work | Processing |
| AGENT_REQUEST | Request another agent's work | AGENT_RESPONSE |
| AGENT_RESPONSE | Return requested information | Processing |
| TASK_COMPLETION | Report completed work | Acknowledgment or next task |
| ERROR_NOTIFICATION | Report processing failure | Recovery or escalation |
### 2.2 Message Specifications
A. TASK_ASSIGNMENT
Required fields:
* task_id
* assigned_agent
* task_description
* input_data
Optional fields:
* deadline
* parent_task_id
B. TASK_ACCEPTANCE
Required fields:
* task_id
* acceptance_status
* accepted_by
Optional fields:
\- estimated_completion
C. AGENT_REQUEST
Required fields:
* request_id
* requested_operation
* input_data
Optional fields:
\- constraints
D. AGENT_RESPONSE
Required fields:
* request_id
* response_status
* output_data
Optional fields:
\- confidence_score
E. TASK_COMPLETION
Required fields:
* task_id
* task_status
* result
Optional fields:
\- result_reference
F. ERROR_NOTIFICATION
Required fields:
* error_code
* error_category
* error_message
* retryable
Optional fields:
* diagnostic_reference
* recovery_instruction
### PHASE 3: CANONICAL MESSAGE ENVELOPE DESIGN
### 3.1 Universal Envelope
All six message types share the same envelope structure.
```json
{
"message_id": "uuid",
"message_type": "TASK_ASSIGNMENT",
"schema_version": "1.0.0",
"sender": "supervisor_agent",
"recipient": "intent_agent",
"conversation_id": "uuid",
"correlation_id": "uuid",
"timestamp": "2026-11-19T06:30:00Z",
"content_type": "application/json",
"payload": {},
"metadata": {}
}
```
### 3.2 Field Definitions
| Field | Type | Required |
| --------------- | --------- | -------- |
| message_id | UUID | Yes |
| message_type | Enum | Yes |
| schema_version | String | Yes |
| sender | String | Yes |
| recipient | String | Yes |
| conversation_id | UUID | Yes |
| correlation_id | UUID | Yes |
| timestamp | Date-time | Yes |
| content_type | String | Yes |
| payload | Object | Yes |
| metadata | Object | No |
Design decision: `task_id`, `request_id`, and `error_code` remain inside their respective payloads instead of being duplicated in the universal envelope.
### PHASE 4: MESSAGE PAYLOAD SCHEMA ENGINEERING
### 4.1 TASK_ASSIGNMENT Schema
File: `schemas/task-assignment-v1.schema.json`
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/task-assignment/1.0.0",
"title": "Task Assignment",
"type": "object",
"additionalProperties": false,
"required": [
"task_id",
"assigned_agent",
"task_description",
"input_data"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid"
},
"assigned_agent": {
"type": "string",
"enum": [
"intent_agent",
"knowledge_agent",
"response_agent",
"quality_agent"
]
},
"task_description": {
"type": "string",
"minLength": 5,
"maxLength": 2000
},
"input_data": {
"type": "object"
},
"deadline": {
"type": "string",
"format": "date-time"
},
"parent_task_id": {
"type": "string",
"format": "uuid"
}
}
}
```
### 4.2 TASK_COMPLETION Schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/task-completion/1.0.0",
"title": "Task Completion",
"type": "object",
"additionalProperties": false,
"required": [
"task_id",
"task_status",
"result"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid"
},
"task_status": {
"type": "string",
"enum": ["COMPLETED"]
},
"result": {
"type": "object"
},
"result_reference": {
"type": "string",
"maxLength": 500
}
}
}
```
### 4.3 ERROR_NOTIFICATION Schema
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/error-notification/1.0.0",
"title": "Error Notification",
"type": "object",
"additionalProperties": false,
"required": [
"error_code",
"error_category",
"error_message",
"retryable"
],
"properties": {
"error_code": {
"type": "string",
"pattern": "^[A-Z_]{3,50}$"
},
"error_category": {
"type": "string",
"enum": [
"VALIDATION",
"AUTHORIZATION",
"PROCESSING",
"TIMEOUT",
"VERSION"
]
},
"error_message": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"retryable": {
"type": "boolean"
},
"diagnostic_reference": {
"type": "string"
},
"recovery_instruction": {
"type": "string",
"maxLength": 500
}
}
}
```
### PHASE 5: FIELD SEMANTICS AND DATA CONTRACT RULES
| Field | Rule |
| -------------- | ------------------------------- |
| message_id | Unique per message |
| task_id | Stable across task lifecycle |
| correlation_id | Shared across related exchanges |
| timestamp | UTC ISO 8601 |
| schema_version | Semantic version |
| sender | Registered agent identity |
| recipient | Authorized destination |
| payload | Type-specific object |
Important distinctions:
* Missing field: Field was not supplied.
* Null: Field explicitly has no value.
* Empty string: String exists but has no content.
* Empty array: Collection exists but contains no items.
* Default: Explicitly defined application behavior.
Null is not interchangeable with missing.
### PHASE 6: AGENT IDENTITY AND MESSAGE ROUTING CONTRACTS
### 6.1 Identity Structure
```json
{
"agent_id": "intent_agent",
"agent_type": "CLASSIFICATION",
"agent_instance": "intent-worker-01"
}
```
### 6.2 Routing Rules
* Sender must be a registered agent.
* Recipient must exist.
* Sender must be authorized to send the requested message.
* Agents cannot impersonate another agent.
* Unknown recipients must trigger a routing error.
* Authentication must be verified independently of message fields.
### PHASE 7: TASK HANDOFF AND RESPONSE CONTRACTS
### 7.1 Task Lifecycle
CREATED
ASSIGNED
ACCEPTED
IN_PROGRESS
COMPLETED
FAILED
CANCELLED
Terminal states cannot transition back to IN_PROGRESS without creating a new task or explicitly defined recovery operation.
### 7.2 Task Completion Example
```json
{
"task_id": "8d50c16b-8b12-4a4e-95b8-891b0a2d7a11",
"task_status": "COMPLETED",
"result": {
"intent": "ORDER_TRACKING",
"confidence": 0.96
}
}
```
### PHASE 8: STRUCTURED ERROR AND FAILURE SCHEMAS
### 8.1 Error Classification
| Error | Code | Retryable |
| --------------------- | -------------------- | ----------- |
| Invalid schema | SCHEMA_INVALID | No |
| Missing field | FIELD_MISSING | No |
| Unauthorized sender | SENDER_UNAUTHORIZED | No |
| Unknown recipient | RECIPIENT_UNKNOWN | No |
| Version mismatch | VERSION_UNSUPPORTED | Conditional |
| Processing timeout | PROCESS_TIMEOUT | Yes |
| Business rule failure | BUSINESS_RULE_FAILED | Conditional |
### 8.2 Error Handling Policy
* Permanent errors should not be retried automatically.
* Transient errors may be retried with bounded exponential backoff.
* Error messages must not expose private customer information.
* Diagnostic details should be stored separately and referenced securely.
### PHASE 9: JSON SCHEMA VALIDATION ENGINEERING
### 9.1 Validation Example
Valid payload
```json
{
"task_id": "8d50c16b-8b12-4a4e-95b8-891b0a2d7a11",
"assigned_agent": "intent_agent",
"task_description": "Classify customer support intent",
"input_data": {
"customer_message": "Where is my order?"
}
}
```
Invalid payload
```json
{
"task_id": "INVALID_ID",
"assigned_agent": "unknown_agent",
"task_description": "Hi",
"input_data": {},
"unexpected_field": true
}
```
Expected validation failures:
* Invalid UUID.
* Unsupported agent identity.
* Description shorter than five characters.
* Unknown property rejected.
Note: JSON Schema format validation requires the validator to enable format assertion/checking; declaring `format` alone may not enforce it.
### PHASE 10: CROSS-FIELD AND SEMANTIC VALIDATION
Basic schema validation is not sufficient.
Additional rules:
* Sender and recipient must be different where self-messaging is prohibited.
* The payload's message type must match the envelope.
* A completion message must reference an existing task.
* A response must reference its original request.
* A correlation ID must remain consistent across an exchange.
* An expired message must not be processed.
* A completed task cannot be completed again with a conflicting result.
These checks require application-level validation.
### PHASE 11: MESSAGE CONTRACT VERSIONING
Use Semantic Versioning.
| Version | Meaning |
| ------- | -------------------------------------- |
| 1.0.0 | Initial release |
| 1.1.0 | Compatible optional addition |
| 1.1.1 | Documentation or validation correction |
| 2.0.0 | Breaking contract change |
Released schemas must remain immutable.
### PHASE 12: BACKWARD AND FORWARD COMPATIBILITY
| Change | Classification |
| ------------------------ | -------------------- |
| Add optional field | Usually compatible |
| Add required field | Breaking |
| Remove field | Potentially breaking |
| Rename field | Breaking |
| Change string to integer | Breaking |
| Add enum value | Consumer-dependent |
| Change field meaning | Breaking |
Example:
Version 1.0.0:
```json
{
"task_id": "uuid",
"task_description": "Classify intent"
}
```
Version 1.1.0:
```json
{
"task_id": "uuid",
"task_description": "Classify intent",
"priority": "HIGH"
}
```
The new field is optional, so existing consumers can remain compatible if they correctly ignore or tolerate it.
### PHASE 13: SCHEMA REGISTRY AND GOVERNANCE
Recommended architecture:

Registry responsibilities:
* Store immutable schema versions.
* Track schema ownership.
* Validate schema publication.
* Maintain compatibility history.
* Record approvals.
* Provide schema discovery.
* Track deprecation.
For the initial Python and JSON Schema stack, a version-controlled Git repository can serve as the initial schema source of truth. A dedicated registry can be introduced as the platform scales.
### PHASE 14: CONTRACT TESTING FRAMEWORK
### 14.1 Test Cases
| Test ID | Scenario | Expected |
| ------- | -------------------- | ------------------ |
| CT-001 | Valid assignment | PASS |
| CT-002 | Missing task_id | FAIL |
| CT-003 | Invalid UUID | FAIL |
| CT-004 | Unknown agent | FAIL |
| CT-005 | Extra property | FAIL |
| CT-006 | Unsupported version | FAIL |
| CT-007 | Valid completion | PASS |
| CT-008 | Missing error_code | FAIL |
| CT-009 | Wrong correlation ID | FAIL semantic |
| CT-010 | Duplicate message ID | Deduplicate/reject |
### 14.2 Python Test Example
```python
import json
from jsonschema import Draft202012Validator
with open(
"schemas/task-assignment-v1.schema.json",
"r"
) as file:
schema = json.load(file)
validator = Draft202012Validator(schema)
payload = {
"task_id": "8d50c16b-8b12-4a4e-95b8-891b0a2d7a11",
"assigned_agent": "intent_agent",
"task_description": "Classify customer intent",
"input_data": {
"customer_message": "Track my order"
}
}
errors = list(validator.iter_errors(payload))
if errors:
for error in errors:
print("FAILED:", error.message)
else:
print("PASSED: Contract validation successful")
```
### PHASE 15: MESSAGE SERIALIZATION AND DESERIALIZATION
Selected format: JSON.
| Format | Advantage | Limitation |
| -------- | ------------------------ | ----------------------- |
| JSON | Human-readable | Larger payloads |
| Protobuf | Efficient binary format | Requires generated code |
| Avro | Schema evolution support | More infrastructure |
Recommended initial configuration:
* Encoding: UTF-8.
* Content type: application/json.
* Timestamp: UTC ISO 8601.
* UUID: Standard textual representation.
* Unknown fields: Rejected under the strict contract.
* Invalid serialized data: Rejected before agent execution.
### PHASE 16: MESSAGE INTEGRITY AND SECURITY CONTRACTS
Security requirements:
* Authenticate the sender independently.
* Authorize the sender-recipient relationship.
* Encrypt messages in transit.
* Protect sensitive payload fields.
* Implement replay protection.
* Apply message expiration.
* Keep audit logs.
* Never trust sender identity merely because it appears in JSON.
Critical distinction: JSON Schema validates message structure, not sender authenticity.
### PHASE 17: MESSAGE CORRELATION AND TRACEABILITY
### Identifier Relationships
| Identifier | Purpose |
| --------------- | ----------------------------- |
| message_id | Individual message |
| conversation_id | Customer conversation |
| correlation_id | Related request-response flow |
| causation_id | Direct triggering message |
| task_id | Task lifecycle |
| trace_id | Distributed tracing |
Example:
```json
{
"message_id": "message-001",
"correlation_id": "correlation-100",
"causation_id": "message-000",
"conversation_id": "conversation-500"
}
```
Use actual UUID values in production wherever UUIDs are required by the contract.
### PHASE 18: CONTRACT RELIABILITY AND EDGE-CASE TESTING
| Scenario | Expected behavior |
| ----------------------- | ------------------------------------- |
| Duplicate message | Deduplicate |
| Delayed message | Check expiration |
| Out-of-order message | Validate task state |
| Partial payload | Reject |
| Expired message | Reject |
| Unknown message type | Reject |
| Oversized payload | Enforce size limit |
| Missing correlation ID | Reject |
| Conflicting task status | Reject transition |
| Unsupported schema | Reject or route to compatible handler |
| Malformed JSON | Reject before schema validation |
Delivery guarantees such as exactly-once processing cannot be guaranteed by the schema itself. They require messaging infrastructure and application-level idempotency.
### PHASE 19: IMPLEMENTATION BLUEPRINT
### Recommended Project Structure
```text
agent-message-contracts/
│
├── schemas/
│ ├── envelope-v1.schema.json
│ ├── task-assignment-v1.schema.json
│ ├── task-acceptance-v1.schema.json
│ ├── agent-request-v1.schema.json
│ ├── agent-response-v1.schema.json
│ ├── task-completion-v1.schema.json
│ └── error-notification-v1.schema.json
│
├── models/
│ ├── messages.py
│ └── enums.py
│
├── validators/
│ ├── schema_validator.py
│ └── semantic_validator.py
│
├── tests/
│ ├── test_valid_messages.py
│ ├── test_invalid_messages.py
│ ├── test_compatibility.py
│ └── test_semantics.py
│
└── README.md
```
### Dependencies
```bash
pip install jsonschema pydantic pytest
```
### Pydantic Model Example
```python
from pydantic import BaseModel, ConfigDict
from uuid import UUID
from typing import Any
class TaskAssignment(BaseModel):
model_config = ConfigDict(extra="forbid")
task_id: UUID
assigned_agent: str
task_description: str
input_data: dict[str, Any]
```
### PHASE 20: FINAL MESSAGE CONTRACT DOCUMENTATION
### Contract Specification Summary
| Component | Specification |
| ---------------- | -------------------------- |
| System | Enterprise Support Agents |
| Agents | 5 |
| Message types | 6 |
| Serialization | JSON |
| Schema dialect | Draft 2020-12 |
| Validation | JSON Schema + Semantic |
| Language | Python |
| Model validation | Pydantic |
| Versioning | Semantic Versioning |
| Traceability | Correlation IDs |
| Security | Independent authentication |
### Example End-to-End Message
```json
{
"message_id": "11111111-1111-4111-8111-111111111111",
"message_type": "TASK_ASSIGNMENT",
"schema_version": "1.0.0",
"sender": "supervisor_agent",
"recipient": "intent_agent",
"conversation_id": "22222222-2222-4222-8222-222222222222",
"correlation_id": "33333333-3333-4333-8333-333333333333",
"timestamp": "2026-11-19T06:30:00Z",
"content_type": "application/json",
"payload": {
"task_id": "44444444-4444-4444-8444-444444444444",
"assigned_agent": "intent_agent",
"task_description": "Classify customer support intent",
"input_data": {
"customer_message": "Where is my order?"
}
}
}
```
### PHASE 21: FINAL CONTRACT QUALITY AUDIT
### 21.1 Audit Results
| Quality Area | Result |
| ---------------- | ------ |
| Agent inventory | |
| Message taxonomy | |
| Envelope design | |
| Payload schemas | |
| Field semantics | |
| Routing rules | |
| Error contracts | |
| Versioning | |
| Compatibility | |
| Security | |
| Testing | |
| Implementation | |
### 21.2 Critical Improvements Required
* Complete JSON Schemas for all six message types.
* Define a reusable envelope schema with conditional payload validation.
* Implement all Pydantic message models.
* Implement task-state transition enforcement.
* Define authentication and authorization integration.
* Establish formal schema compatibility testing.
* Define maximum payload size and message expiration policies.
* Test all contracts against actual producer and consumer implementations.
### 22\. RISKS AND LIMITATIONS
| Risk | Severity | Mitigation |
| --------------------------- | -------- | ----------------------------- |
| Incompatible schema updates | High | Registry compatibility checks |
| Unauthorized agent messages | Critical | Identity verification |
| Duplicate processing | High | Idempotency |
| Missing correlation | Medium | Mandatory identifiers |
| Invalid task transitions | High | State machine validation |
| Sensitive data leakage | Critical | Payload minimization |
| Incomplete schemas | High | Full contract coverage |
### 23\. FINAL ENGINEERING RECOMMENDATIONS
Recommended production architecture:
* JSON Schema Draft 2020-12 for formal message validation.
* Pydantic for Python application models.
* Git-based schema governance initially.
* Automated pytest contract testing.
* UUID-based message and task identifiers.
* Strict envelope and payload validation.
* Explicit schema versioning.
* Independent authentication and authorization.
* Application-level idempotency and state validation.
Sample Test 01
Completed
### 24 Sections
Engineering specification demonstrated across all requested phases and final output sections.
Overall assessment: The architecture is a strong initial contract design, but it is not yet production-certified. Complete all message schemas, semantic validators, and integration tests before deployment.
By purchasing this prompt, you agree to our terms of service
CLAUDE-5-5-SONNET
Are your AI agents exchanging inconsistent messages, breaking integrations, or losing critical information during task handoffs?
This prompt helps developers engineer reliable, versioned message contracts for multi-agent systems through:
📦 Standardized agent message envelope design
🧩 JSON Schema and structured payload definitions
🔐 Sender, receiver, identity, and authorization fields
🔄 Schema versioning and backward compatibility
✅ Payload validation and contract enforcement
🔍 Message
...more
Added 5 minutes ago
