SMS Delivery Architecture AGENTS.md Template

Overview

AGENTS.md Template for SMS delivery architecture defines a practical operating manual for AI coding agents coordinating single-agent and multi-agent workflows. It specifies roles, handoffs, tool governance, and human review to ensure reliable, auditable SMS delivery across gateways and providers. Direct answer summary: this template establishes a clear, repeatable SMS workflow with an orchestrator and specialized agents, enabling safe multi-agent collaboration.

When to Use This AGENTS.md Template

• When building AI-assisted SMS delivery pipelines that require reliable handoffs and auditable decisions.
• When you need explicit agent roles for content creation, delivery coordination, gateway interaction, compliance, and monitoring.
• When introducing multi-agent orchestration with clear memory, SSOT, and traceability.
• When enforcing tool governance and security in production SMS flows.
• When onboarding new engineers with a living operating manual for SMS delivery architecture.

Copyable AGENTS.md Template

# AGENTS.md

Project: SMS Delivery Architecture

Agent roster and responsibilities:
- SMSOrchestrator: coordinates all steps, enforces rules, and maintains the single source of truth across agents.
- MessageComposerAgent: builds message content, templates, and metadata (sender ID, opt-in status).
- DeliveryCoordinatorAgent: triggers delivery to the SMS gateway/provider, manages queueing and retries.
- ProviderInterfaceAgent: interfaces with the SMS gateway (send, status, receipts), handles retries/backoffs.
- ComplianceAgent: ensures opt-in, consent, rate limits, content policies, and regional compliance.
- TelemetryAgent: collects metrics, traces, and health signals.
- HumanReviewAgent: escalates high-risk or failed deliveries for human review.

Supervisor or orchestrator behavior:
- SMSOrchestrator maintains context, SSOT, and explicit memory passed between agents.
- It enforces tool permissions, validates outputs, and halts the pipeline on policy violations.
- It logs decisions to the TelemetryAgent.

Handoff rules between agents:
- After MessageComposerAgent completes content, hand off to DeliveryCoordinatorAgent with context and SSOT.
- DeliveryCoordinatorAgent passes delivery state to ProviderInterfaceAgent and awaits delivery receipt.
- On delivery failure, escalate to HumanReviewAgent or retry with backoff up to policy; never bypass retries.
- Transfer memory and source-of-truth at every handoff; include trace IDs.

Context, memory, and source-of-truth rules:
- Use MemoryStore with an SSOT document per SMS work item.
- Store: message content, recipient, sender, opt-in, timestamps, policies, and version.
- All agents read from MemoryStore; writes propagate via event bus.
- Source of Truth: policies.json, recipients.json, templates.json.

Tool access and permission rules:
- Agents may call: SMS gateway API (send/status/retry), Telemetry API (log), Secrets vault (read for required keys), Compliance checks service, Content templates repo.
- Prohibit: editing production data stores directly; writing secrets to logs; leaking credentials.

Architecture rules:
- Microservice-like agents connected via an internal event bus or in-process orchestrator.
- Stateless agents; MemoryStore is the SSOT and event store.
- Idempotent operations; use idempotency keys for delivery requests.

File structure rules:
- Keep all agent code under agents/ with subfolders per agent; store memory/templates/configs in data/; tests under tests/.
- Do not include unrelated folders.

Data, API, or integration rules when relevant:
- Use recipients API to fetch opt-in status; templates.json for content variants.
- Use gateway provider API endpoints for delivery; implement backoff and retries.

Validation rules:
- Message length <= 160 chars (per provider constraints) and valid characters.
- Delivery receipts matched to requestId; event logged in Telemetry.
- All required fields present in memory before delivery.

Security rules:
- Secrets never logged; use Secrets Vault; tokens rotated per policy.
- Data minimization; avoid persisting PII beyond necessity.

Testing rules:
- Unit tests for MessageComposer; integration tests for DeliveryCoordinator and ProviderInterface; end-to-end tests with mocked gateway.

Deployment rules:
- Deploy agents as containerized services behind a message bus; canary rollout; monitor health.

Human review and escalation rules:
- Escalate high-risk content or failed deliveries to HumanReviewAgent; require manual approval for rate-limit breaches.

Failure handling and rollback rules:
- On failure: retry with exponential backoff up to policy; if persistent, rollback and notify Telemetry.

Things Agents must not do:
- Do not bypass policies; do not leak credentials; do not modify production data stores directly; do not drift memory/state.

Recommended Agent Operating Model

The SMS delivery architecture uses a planner-like orchestration with clearly defined roles, decision boundaries, and escalation paths. The Organisator acts as the central authority, while specialized agents perform content creation, delivery coordination, gateway interaction, and monitoring. Escalation to humans is reserved for high-risk messages or policy violations. Memory and SSOT ensure reproducibility and auditability in multi-agent flows.

Recommended Project Structure

sms-delivery-architecture/
  ├─ agents/
  │  ├─ orchestrator/
  │  │  └─ orchestrator.py
  │  │  └─ __init__.py
  │  ├─ message_composer/
  │  │  └─ composer.py
  │  ├─ delivery_coordinator/
  │  │  └─ coordinator.py
  │  ├─ provider_interface/
  │  │  └─ provider.py
  │  ├─ compliance/
  │  │  └─ compliance.py
  │  ├─ telemetry/
  │  │  └─ telemetry.py
  │  └─ human_review/
  │     └─ review.py
  ├─ data/
  │  ├─ templates.json
  │  ├─ recipients.json
  │  └─ policies.json
  ├─ configs/
  │  └─ settings.yaml
  ├─ tests/
  │  ├─ test_message.py
  │  └─ test_delivery.py
  └─ docs/
     └─ AGENTS.md

Core Operating Principles

• Single source of truth: SSOT governs all memory and state across agents.
• Idempotent actions: retry and backoff must be deterministic and time-bounded.
• Explicit handoffs: every transfer includes memory, trace IDs, and required context.
• Least privilege: agents operate with the minimum permission necessary to perform their tasks.
• Auditable decisions: all agent outputs are logged to Telemetry with traceability.

Agent Handoff and Collaboration Rules

• Planner to Implementer: planner defines the plan; implementer executes steps with context.
• Implementer to Reviewer: implementer passes artifacts to reviewer for validation before production use.
• Tester ensures end-to-end behavior with mocked gateways before deploy.
• Researcher can supply templates or policy updates, with approval from orchestrator.
• Domain Specialist handles locale/regional compliance and content policy considerations.

Tool Governance and Permission Rules

• Commands to SMS gateway must be gated by policy; retries governed by backoff policy.
• Edits to production data stores are prohibited without explicit approval and a rollback plan.
• Secrets must be retrieved from a secure vault; do not hard-code or log secrets.
• All API calls should be logged with a trace ID and outcomes stored in Telemetry.
• New integrations require security review, risk assessment, and test coverage before production.

Code Construction Rules

• Follow the project structure; keep modules small and well-scoped.
• Use idempotent, deterministic operations for delivery requests.
• Validate all inputs and outputs against the SSOT before state mutations.
• Avoid duplicating work; reuse templates and message variants when possible.
• Document non-obvious decisions in the agent comments and the AGENTS.md template itself.

Security and Production Rules

• Rotate gateway tokens and API keys per policy; monitor for credential leakage.
• Encrypt data in transit and at rest; minimize PII persistence.
• Enforce opt-in consent for all recipients and maintain an auditable opt-in trail.
• Implement rate limiting and circuit breakers for gateway interactions.
• Perform blue/green or canary deployments for production changes; require health checks.

Testing Checklist

• Unit tests for MessageComposer content correctness and length constraints.
• Integration tests for DeliveryCoordinator and ProviderInterface with sandbox gateways.
• End-to-end tests with mocked SMS gateway and telemetry integration.
• Canary tests to validate production deployment behavior before full rollout.
• Security tests to validate vault access and secret handling.

Common Mistakes to Avoid

• Overcomplicating the agent workspace beyond the defined roles.
• Ignoring opt-in, consent, or regional messaging restrictions.
• Weak memory synchronization leading to context drift.
• Skipping formal handoffs or not preserving SSOT during transitions.
• Logging secrets or exposing credentials in messages or logs.

Related implementation resources: AI Use Case for Micro-Lenders Using Phone Usage Data Metrics To Evaluate Creditworthiness In Unbanked Regions and AI Agent Use Case for Food Processors Using Production Line Check-Sheets To Build Audit-Ready Food Safety Compliance Reports.

FAQ

What is this AGENTS.md Template for SMS delivery architecture?

This AGENTS.md Template defines the operating manual for AI coding agents coordinating SMS delivery across content creation, delivery coordination, gateway interaction, and monitoring. It provides roles, handoffs, rules, and escalation paths for single-agent and multi-agent workflows.

How are agent handoffs handled in the SMS workflow?

Handoffs occur with explicit context and SSOT; the orchestrator passes a memory snapshot and trace-id to the next agent; each handoff includes required fields and state to resume work without context drift.

How should secrets and production credentials be managed?

Secrets are stored in a dedicated vault, not logged, rotated regularly, and accessed only by approved agents; no secrets are embedded in the code or memory outside the vault.

What testing is required for the SMS delivery AGENTS.md workflow?

Unit tests for message construction, integration tests with the gateway provider, end-to-end tests with mocked or sandboxed SMS providers, and deployment-time validation checks.

What are common pitfalls when implementing multi-agent SMS delivery?

Overcomplicating the workflow, bypassing governance, ignoring opt-in/compliance, missing memory synchronization, and introducing architecture drift or unsafe production changes.