AGENTS.md Template for Active-Active Deployment Architecture

Overview

Direct answer: Use this AGENTS.md template to define and govern the active-active deployment orchestration across multiple regions for AI coding agents. It provides a policy-driven operating manual for single-agent runs and multi-agent coordination to maintain availability, data consistency, and controlled handoffs during deployment, scaling, and failover.

The AGENTS.md template establishes a clear operating context for roles, responsibilities, memory and truth sources, tool access, architecture constraints, and escalation paths in an active-active deployment architecture.

When to Use This AGENTS.md Template

• Architecting AI-powered systems that must stay live across two or more regions.
• Requiring cross-region data replication, low RPO/RTO, and deterministic handoffs between planners, implementers, validators, and testers.
• Formal tool governance, secret management, and approval gates for production-ready changes.
• Need a copyable, project-level operating context that can be pasted into an AGENTS.md file for single-agent or multi-agent workflows.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Platform Engineer Lead, SRE, and AI Coding Agent Coordinator for Active-Active Deployment Architecture.

Agent roster and responsibilities:
- Planner Agent: designs cross-region deployment plans, coordinates tasks across Region A and Region B, and ensures readiness for failover.
- Implementer Agent (Region A): implements deployment changes, applies configuration, and verifies region-specific actions.
- Implementer Agent (Region B): implements deployment changes, applies configuration, and verifies region-specific actions.
- Validator Agent: checks consistency, drift, and conflict resolution; validates cross-region commitments before promotion.
- DataSync Agent: ensures cross-region data replication, conflict detection, and replication health.
- Monitor Agent: runs health checks, monitors latency, and triggers alerts on drift or failure.
- Reviewer Agent: performs security and compliance reviews, approves changes for production.
- Human-in-the-loop: final approval required for production changes beyond defined presets.

Supervisor or orchestrator behavior:
- Orchestrator: coordinates all agents, enforces policy, records decisions, and triggers escalation if timing, drift, or conflicts arise.
- The orchestrator operates with strict tool governance, must log all actions, and requires explicit approval gates for production changes.

Handoff rules between agents:
1) Planner produces a plan and handoffs to Implementers.
2) Implementers complete tasks and report back; Validator validates cross-region consistency.
3) If drift is detected, handoff returns to Planner; otherwise handoffs proceed to Tester and Reviewer before production deployment.
4) In incident, handoff to On-Call Engineer for remediation with backoff and rollback scripts.

Context, memory, and source-of-truth rules:
- Source of truth: Centralized deployment/config store (versioned). Memory: Last 7 days of decisions and plan history.
- Context: All agent actions include a trace id and region context; avoid relying on ephemeral memory.
- Data lineage and provenance are captured in the deployment log and the audit trail, stored in the central store.

Tool access and permission rules:
- Agents can access Cloud API with least privilege for the deployment regions.
- Secrets are read-only through a secrets manager; no hard-coded credentials allowed.
- Approval gates required for production changes; all tool calls are audited.

Architecture rules:
- Active-Active: two or more regions remain live with synchronized configurations and data replication.
- Deterministic, idempotent operations; all actions are replayable and reversible where possible.
- Conflict resolution at the data plane using last-writer-wins with explicit metadata.

File structure rules:
- All agent code and templates reside under a single repository with clear per-region modules.
- Do not duplicate tasks; use shared libraries for common patterns.

Data, API, or integration rules:
- Use defined REST/gRPC interfaces for cross-region coordination; enforce consistent schemas.
- All data changes are versioned; migrations are atomic.

Validation rules:
- Drift checks must pass within defined thresholds; data lag must stay within SLA.
- All changes require successful end-to-end tests in both regions before promotion.

Security rules:
- Do not leak secrets; rotate credentials; enforce least-privilege and network segmentation.
- Access to production configs is restricted and auditable.

Testing rules:
- Unit tests for each agent; integration tests for cross-region workflows; canary tests for new strategy.

Deployment rules:
- Follow blue/green or canary deployment with automatic failover in active-active mode.
- Rollback to last known good state if cross-region constraint fails.

Human review and escalation rules:
- All security/compliance changes require reviewer approval; operational incidents escalate to on-call engineers and severity is logged.

Failure handling and rollback rules:
- If cross-region replication fails, automatically halt changes, revert to last good state, and trigger incident workflow.
- Ensure idempotent rollback scripts that can be retried safely.

Things Agents must not do:
- Do not bypass approval gates or run production changes without authorization.
- Do not alter shared state in a manner that breaks consistency guarantees.
- Do not assume unlimited memory or network access; respect quotas and rate limits.

Recommended Agent Operating Model

The operating model defines clear role boundaries, escalation paths, and decision rights. In an active-active deployment, the Planner orchestrates cross-region commitments; Implementers apply changes; Validators enforce cross-region consistency; Testers validate end-to-end behavior; Reviewers approve production changes; All agents log decisions for auditability.

Recommended Project Structure

ai-active-active/
├── configs/
├── docs/
├── scripts/
├── agents/
│   ├── planner/
│   ├── orchestrator/
│   ├── implementer-region-a/
│   ├── implementer-region-b/
│   ├── validator/
│   ├── tester/
│   ├── reviewer/
│   └── data-sync/
├── deployments/
├── data/
├── tests/
└── canaries/

Core Operating Principles

• Idempotent, deterministic actions; repeatable across regions.
• Single source of truth for deployments and configs.
• Strict handoffs with traceable decision logs.
• Least privilege and automatic secrets rotation.
• Explicit error handling, circuit breakers, and rollback guarantees.

Agent Handoff and Collaboration Rules

Rules specify how planners, implementers, validators, testers, reviewers, researchers, and domain specialists collaborate across regions during active-active workflows.

Tool Governance and Permission Rules

• All tool actions are auditable; no elevated rights beyond required scope.
• Secrets are accessed via a managed vault with rotation policies.
• Production changes require approval gates and sign-off from the Reviewer.
• External services use signed requests and mutual TLS where applicable.

Code Construction Rules

• Write modular, testable agent code with clear interfaces.
• Guard all external calls with timeouts and retries; log outcomes.
• Use idempotent designs and avoid race conditions across regions.
• Do not hard-code region-specific values; rely on environment/config files.

Security and Production Rules

• Do not expose credentials; use secret stores.
• Network segmentation between regions; restrict inter-region traffic to approved endpoints.
• Enable audit trails for all deployment actions and escalations.

Testing Checklist

• Unit tests for each agent; integration tests for cross-region flows.
• End-to-end tests across regions; canary deployment checks.
• Failover/failback tests and rollback verification.

Common Mistakes to Avoid

• Assuming zero data drift in active-active setups.
• Bypassing approvals for production changes.
• Ignoring race conditions in cross-region deployment steps.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts.

FAQ

What is the purpose of this AGENTS.md Template?

It defines a reproducible operating manual for active-active deployment orchestration using AI coding agents, including roles, handoffs, and governance.

Can this template be used for single-agent workflows?

Yes. It provides a baseline that can be scaled to multi-agent orchestration or simplified for single-agent tasks while preserving governance.

How are cross-region conflicts resolved?

Conflict resolution uses a defined policy: last-writer-wins with explicit metadata and an auditor review if drift exceeds thresholds.

What must be reviewed before production changes?

Security, compliance, and architecture reviews, plus automated validation checks and canary tests in both regions.

Where is the source of truth located?

Centralized, versioned deployment/config store; all decisions are traceable in the deployment log and audit trail.