AGENTS.md Template for Message Queue Architecture

Overview

Direct answer: This AGENTS.md Template defines the operating context for a message queue architecture and governs an AI coding agent workflow that coordinates producers, a broker, and consumers. It supports both single-agent and multi-agent orchestration with clear handoffs, memory rules, and tool governance.

The AGENTS.md template serves as a project-level operating manual for single-agent and multi-agent work in an event-driven, queue-based system. It captures roles, data flows, decision boundaries, and escalation paths so teams can implement, test, and operate the workflow with confidence.

When to Use This AGENTS.md Template

• When building an event-driven workflow that relies on a queue to decouple producers and workers.
• When you need reliable message delivery, dead-letter handling, and replay-safe processing.
• When multi-agent orchestration is required, including planner, producer, broker, consumer, and reviewer roles.
• When governance, security, and auditability are critical for production services.

Copyable AGENTS.md Template

Copy this block into your AGENTS.md at the project root to establish the operating context for a message queue architecture.

# AGENTS.md

Project role: AI coding agents coordinating a message queue workflow for task processing, routing, and auditing across producers, a broker, and consumers.

Agent roster and responsibilities:
- Planner: designs the queue-based pipeline, defines message schemas, and schedules handoffs across agents
- Producer: validates and enqueues messages according to the schema, handles idempotent enqueuing
- Broker: manages the queue, routing, retry logic, and dead-letter handling
- Consumer: processes messages, emits results, and reports back to the orchestrator
- Orchestrator: supervises multi-agent flow, enforces timeouts, retries, and escalation paths
- Reviewer: validates outputs against quality gates and regulatory constraints
- Researcher: supplies domain data, external references, and test data when needed

Supervisor or orchestrator behavior:
- Maintain live state of in-flight messages, queues, and agent assignments
- Enforce timeouts, retries, backoffs, and escalation rules
- Trigger handoffs and coordinate backpressure or throttling as needed

Handoff rules between agents:
- Producer -> Broker: publish with validated schema and correlation id
- Broker -> Consumer: deliver with correlation id and next-step hints
- Consumer -> Orchestrator: report outcome and required follow-up
- Orchestrator -> Reviewer: trigger review for high-risk or high-value tasks
- Researcher -> Planner: supply domain data for subsequent stages

Context, memory, and source-of-truth rules:
- All messages carry correlation id, timestamp, and source log in a central store
- Memory window: last N messages for auditing and anomaly detection

Tool access and permission rules:
- Only designated agents may perform queue operations
- Secrets retrieved from a secure vault; never hard-coded
- All API calls logged with correlation id

Architecture rules:
- Event-driven, decoupled components; idempotent producers/consumers
- Exactly-once delivery where supported; at-least-once fallback with deduplication
- Clear retry and rollback policies

File structure rules:
- AGENTS.md at repository root and within workflow subfolders
- Standardized naming for task definitions, schemas, and configs

Data, API, or integration rules:
- Use a common message schema for tasks; validate before enqueue
- All external API calls logged with context data

Validation rules:
- Messages include required fields: id, type, payload, timestamp, correlationId
- Outcomes include status, success flag, and result hash

Security rules:
- Do not expose secrets in messages or logs
- Enforce least privilege for queues and services

Testing rules:
- Unit tests for producers/consumers; integration tests with a simulated queue
- End-to-end tests covering multi-agent handoffs and failure modes

Deployment rules:
- Staged rollouts; feature flags; rollback plan for queue reprocessing

Human review and escalation rules:
- Critical failures require human review; escalation paths configured in the orchestrator

Failure handling and rollback rules:
- On failure, requeue with backoff; handle idempotent replays
- If irreversible errors occur, route to manual remediation

Things Agents must not do:
- Do not bypass validation or memory rules
- Do not modify historical messages or logs outside approved channels
- Do not bypass escalation or governance gates

Recommended Agent Operating Model

The operating model defines roles, decision boundaries, and escalation paths for single-agent or multi-agent execution in a message queue architecture. It pairs a planner orchestrator with producers, brokers, and consumers to ensure safe, auditable handoffs and controlled deployments.

Recommended Project Structure

project-root/
├── agents/
│   ├── planner/
│   ├── producer/
│   ├── broker/
│   ├── consumer/
│   ├── orchestrator/
│   ├── reviewer/
│   └── researcher/
├── configs/
├── infra/
├── tests/
└── docs/

Core Operating Principles

• Explicitly defined agent roles and responsibilities
• Deterministic handoffs with correlation IDs
• Single source of truth for task state and outcomes
• Isolated agents with least-privilege access
• Auditable changes with clear rollback paths

Agent Handoff and Collaboration Rules

• Planner/Orchestrator coordinates task sequencing and dependency resolution
• Producer validates inputs and enqueues with schema conformance
• Broker ensures queue health, partitions work, handles retries
• Consumer performs work and emits measurable results
• Reviewer validates outcomes and gates progress to next stage
• Researcher supplies data and context for domain-specific decisions

Tool Governance and Permission Rules

• Operate queues and APIs only via authorized agents
• Secrets must be fetched securely; never embedded in code
• All tool actions require auditable approvals and logging
• Changes to production queue configurations require change approval

Code Construction Rules

• Write idempotent producers/consumers
• Validate all messages against a schema before enqueue
• Do not bypass memory or source-of-truth invariants
• Use deterministic message IDs and versioned schemas

Security and Production Rules

• Enforce least privilege on all queue accesses
• Encrypt sensitive payloads in transit and at rest where applicable
• Monitor queues for anomalies and enforce circuit breakers
• Capture full audit trails for deployment and rollback actions

Testing Checklist

• Unit tests for producers/consumers
• Integration tests covering broker interactions and handoffs
• End-to-end tests with simulated queues and failure modes
• Performance tests for throughput and backpressure

Common Mistakes to Avoid

• Skipping schema validation and correlation tracking
• Uncontrolled handoffs leading to orphaned tasks
• Hard-coded secrets or credentials in code
• Unclear escalation paths and lack of auditability

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Ndas and Risk Flagging.

FAQ

What is the purpose of this AGENTS.md Template for a message queue architecture?

It defines roles, rules, and handoffs for AI coding agents coordinating producers, brokers, and consumers in a queue-based workflow.

Who are the primary agents and what do they do?

Planner orchestrates, Producer enqueues, Broker manages the queue, Consumer processes, Orchestrator oversees flow, Reviewer validates outputs, and Researcher supplies data.

How are handoffs enforced between agents?

Handoffs occur through predefined sequences with correlation IDs, schema validation, and central state updates.

What are the safety and governance requirements?

Secrets are vaulted, access is least-privilege, and production changes require approvals with full traceability.

How is testing approached for this workflow?

Unit tests for producers/consumers, integration tests for queue interactions, and end-to-end tests with simulated queues.