AGENTS.md Template for Load Balancing Architecture

Overview

This AGENTS.md template defines the operating manual for AI coding agents working in a load balancing architecture. It governs both single-agent execution and multi-agent orchestration across edge nodes, regional gateways, and the control plane. The template provides a copyable project-level AGENTS.md page that states roles, handoffs, memory, tool access, and governance rules for reliable traffic routing and health management.

Direct answer: This template gives you a concrete, paste-ready AGENTS.md that codifies the load balancer orchestration workflow and the interactions among agents so changes are auditable and reversible.

When to Use This AGENTS.md Template

• You are implementing AI-guided load balancing orchestration that spans multiple nodes or regions.
• You need explicit handoff rules between planners, implementers, reviewers, testers, and domain specialists.
• You require tool governance, secrets handling, and secure production changes with auditable trails.
• You want a single source of truth for architecture rules, file structure, and validation steps.

Copyable AGENTS.md Template

# AGENTS.md

Project Role
- This AGENTS.md defines the project level operating context for a load balancing architecture guided by AI coding agents.

Agent roster and responsibilities
- OrchestratorAgent: coordinates routing decisions across edge and regional load balancers
- EdgeNodeAgent: enforces local routing rules and reports health to the orchestrator
- HealthCheckAgent: monitors target health and availability and flags anomalies
- RouteEngineAgent: applies routing policies and weights to traffic streams
- ObservabilityAgent: collects metrics and provides audit logs

Supervisor or orchestrator behavior
- OrchestratorAgent builds a desired state from inputs, pushes changes through safe, idempotent actions, and validates outcomes
- Maintains a single source of truth in the central config store and enforces versioned changes

Handoff rules between agents
- Planner to Implementer: transfer of plan with context and version
- Implementer to Reviewer: after applying changes, hand off for validation
- Reviewer to Orchestrator: grant approval or request adjustments

Context, memory, and source-of-truth rules
- All decisions reference the central config store and a versioned baseline
- Agent memory caches recent health, metrics, and policy decisions but does not persist beyond the session without explicit save

Tool access and permission rules
- Agents can call LB provider APIs, read metrics, and update config via the orchestrator
- Secrets must be retrieved from a vault; no plaintext secrets in code

Architecture rules
- Stateless edge agents, deterministic routing decisions, and idempotent changes
- Clear rollback path to the previous config version

File structure rules
- Only load balancing related components live in this AGENTS.md project

Data, API, or integration rules when relevant
- Use real-time health data, valid routing policies, and auditable API calls to LB services

Validation rules
- Validate state changes in a staging canary environment before production
- All changes require at least one reviewer approval

Security rules
- Encrypt data in transit; store secrets securely; audit all changes

Testing rules
- Unit tests for routing logic; integration tests for LB API calls; end-to-end tests for traffic routing

Deployment rules
- Canary deploys with gradual traffic shift; automatic rollback on failure

Human review and escalation rules
- Escalate to on-call engineering lead if health or policy violations persist after remediation

Failure handling and rollback rules
- Revert to the prior config version; re-run health checks and traffic tests

Things Agents must not do
- Do not expose secrets; do not perform production changes outside approval gates

Recommended Agent Operating Model

In this load balancing workflow, agent roles are bounded with clear decision boundaries and escalation paths. The Orchestrator coordinates state, the Edge nodes enforce routing, and specialized agents focus on health and policy enforcement. Handoffs occur with explicit context transfer and versioned configuration to prevent drift.

Recommended Project Structure

load-balancing-architecture/
  agents/
    orchestrator/
    edge/
    health/
    route-engine/
    observability/
  configs/
  policies/
  docs/
  tests/
  deployments/

Core Operating Principles

• Single source of truth for config and policy in a central store
• Idempotent, deterministic actions with versioning
• Auditable changes with proper escalation gates
• Clear separation of concerns among agent types

Agent Handoff and Collaboration Rules

• Planner to Implementer: share desired state and required outcomes
• Implementer to Reviewer: provide changes with evidence and test results
• Reviewer to Orchestrator: approve or request adjustments
• Domain Specialist: applies policy nuances and handles edge-case routing rules

Tool Governance and Permission Rules

• Execution of commands to LB services must go through the orchestrator with audit trails
• Edits to configs are versioned and require review gates
• Secrets are sourced from a secure vault; no plaintext secrets in code
• Production changes require explicit approval gates

Code Construction Rules

• Write idempotent code; avoid stateful side effects without persistence
• Respect the central config store as the truth source
• Avoid duplicating logic across agents; extract common routing rules

Security and Production Rules

• Least privilege for all agents; rotate credentials regularly
• Encrypt traffic between agents and LB services; monitor for anomalous access
• Maintain immutable changelogs and audit trails for all production actions

Testing Checklist

• Unit tests for routing logic and policy evaluation
• Integration tests with LB API endpoints and config stores
• Canary tests to validate traffic shift and rollback
• End-to-end tests for health checks and failover scenarios

Common Mistakes to Avoid

• Assuming instant propagation of config changes across all edges
• Overly complex handoffs without clear state transfer
• Skipping staging validation for production changes

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for load balancing?

This AGENTS.md Template defines a reusable operating manual for AI coding agents coordinating load balancer topology, health checks, and traffic routing decisions.

How does multi-agent orchestration handle routing decisions?

Routing decisions are made by a central orchestrator with input from edge agents and policy engines, ensuring deterministic changes with audit trails.

What are the handoff rules between agents?

Handoffs occur with explicit context transfer, versioned configs, and validation by reviewers before execution.

What about security when controlling load balancers via agents?

Agents use least privilege access, secrets in vaults, and production changes require approved gates and auditable logs.

How is change validation and rollback handled?

Changes are validated in staging or canary environments with defined rollback paths to prior configurations.