API Gateway Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md template governs the API gateway architecture workflow using AI coding agents to coordinate design, policy enforcement, and deployment through a multi-agent orchestration model.

The AGENTS.md template defines a project-level operating context for building and governing an API gateway architecture with AI agents. It supports both single-agent execution and multi-agent orchestration, including handoffs between planner, implementer, reviewer, and researcher agents, along with governance over tools, secrets, and production deployments.

When to Use This AGENTS.md Template

• You need a repeatable, auditable operating model for API gateway design and policy enforcement using AI coding agents.
• You require clear handoff rules between agents to manage architecture drift and tool access.
• You want centralized memory and source-of-truth for gateway configuration, routing rules, and security policies.
• You must govern tool usage, credentials, and production changes with escalation and human review gates.

Copyable AGENTS.md Template

# AGENTS.md

Project role: API gateway architecture designer and coordinator.
Agent roster and responsibilities:
- planner: defines gateway topology, routing strategy, and policy goals.
- implementer: translates planner decisions into configuration changes and code.
- tester: validates routing, latency, and policy correctness.
- researcher: gathers external service constraints, security requirements, and compliance needs.
- reviewer: ensures changes meet security and reliability standards.
- domain specialist: provides domain-specific constraints (e.g., OAuth, mTLS, JWT policies).

Supervisor / orchestrator behavior:
- Central orchestrator maintains project context, triggers handoffs, and records decisions.
- Organize sprints around gateway feature sets and policy updates.

Handoff rules between agents:
- Planner → Implementer: handoff topology, routing decisions, and required configs.
- Implementer → Tester: provide test cases, simulated traffic, and expected outcomes.
- Tester → Reviewer: deliver test results and policy validation.
- Researcher → Planner/Domain Specialist: supply constraints that affect design.

Context, memory, and source-of-truth rules:
- Source of truth: gateway-config.json, policies.yaml, and service registry.
- Memory: maintain a shared memory board with the latest topology, routes, and policy versions.
- All agents reference the canonical source in read-only mode unless writing is explicitly granted.

Tool access and permission rules:
- Access: only authorized gateways, service registries, and secrets vaults.
- Secrets must be retrieved via a secure vault and never exposed in logs.
- API calls limited to approved endpoints with rate limits.

Architecture rules:
- Use a layered gateway architecture (edge, regional, internal).
- Enforce zero-trust policies for inbound traffic.
- Implement circuit breakers and retries per route policy.

File structure rules:
- gateway/
  - configs/
  - policies/
  - routes/
- docs/
- scripts/

Data, API, or integration rules:
- All gateway configs are versioned in git and accompanied by release notes.
- Use OpenAPI specs for public routes; keep internal routes private.

Validation rules:
- Validate routing table consistency, policy assignments, and token validation.
- Run synthetic traffic tests and latency budgets.

Security rules:
- Secrets never logged; rotate credentials; enforce mTLS where required.
- Audit logs must be immutable and backed by a WORM store.

Testing rules:
- Unit tests for policy logic, integration tests for routing behavior, end-to-end tests for gateway startup.

Deployment rules:
- Changes require dual approval and can only be deployed to staging before production.
- Canary or blue-green deployment when updating critical routes.

Human review and escalation rules:
- All security-critical changes require human review before merge.
- Escalations trigger a governance ticket and rollback if anomalies detected.

Failure handling and rollback rules:
- Rollback to previous gateway-config on failure; maintain last good state.
- Disable affected routes automatically if health checks fail persistently.

Things Agents must not do:
- Do not bypass security or skip approvals.
- Do not mutate memory without source-of-truth updates.
- Do not perform production deployments without checks.

Recommended Agent Operating Model

The agent roster above defines responsibilities and decision boundaries. The orchestrator enforces escalation paths, while domain specialists provide constraint-driven input. Agents should operate within the defined memory, sources of truth, and tool governance boundaries to prevent architecture drift and unsafe changes. Escalations happen through the supervisor with clear rollback steps.

Recommended Project Structure

gateway-architecture/
  gateway-configs/
    gateway-config.yaml
  policies/
    rate-limit.yaml
  routes/
    v1-routes.yaml
  docs/
  scripts/
  tests/
    unit/
    integration/

Core Operating Principles

• Operate with a single source of truth for gateway configurations and policies.
• Keep all agent decisions auditable with traceable handoffs.
• Enforce strict tool governance and secrets handling.
• Prioritize secure, resilient, and observable gateway behavior.

Agent Handoff and Collaboration Rules

Handoff rules specify how planner, implementer, tester, reviewer, researcher, and domain specialist agents collaborate. Always reference the canonical data sources before making changes and require explicit approvals for security-sensitive updates.

Tool Governance and Permission Rules

All tool actions go through the orchestrator with role-based access. Secrets must be fetched from a vault and never logged. Production changes require governance ticketing and human sign-off.

Code Construction Rules

Follow the gateway architecture design and policy definitions strictly. Use OpenAPI specs for public interfaces; ensure consistent versioning and documentation. Do not introduce config drift.

Security and Production Rules

Enforce client and inter-service mTLS, short-lived tokens, and strict access controls. Production deployments require canary testing and manifest-based rollbacks.

Testing Checklist

• Unit tests for policy logic and route validators.
• Integration tests for gateway configuration loading and service discovery.
• End-to-end tests for failover, circuit breakers, and observability.
• Deployment validation in staging with canary checks.

Common Mistakes to Avoid

• Skipping human review on security-critical changes.
• Assuming all routes are read-only; never assume without validation.
• Bypassing the source-of-truth for memory and config.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Visa Consultants Using Government Portals To Check Application Documents for Missing Requirements.

FAQ

What is the purpose of this AGENTS.md Template?

Defines a repeatable operating manual for API gateway architecture with multi-agent orchestration.

Which agents are involved in this workflow?

The planner, implementer, tester, reviewer, researcher, and domain specialist work together under a central orchestrator that manages handoffs and tool access.

How is memory managed?

Canonical sources for gateway config and policies are stored in a single repository; agents reference it as the single source of truth and avoid drift.

What safety rules govern tool use?

Secrets must be retrieved from a vault, no sensitive data in logs, approvals for production changes.

How are failures rolled back?

Rollback to last good gateway-config and disable affected routes pending fix.