AGENTS.md Template: Multi-Tenant Access Control

Overview

Direct answer: This AGENTS.md Template defines a multi-tenant access control workflow for AI coding agents, enabling tenant-scoped policy enforcement, auditability, and safe handoffs across tenants.

The AGENTS.md template provides a project-level operating context for single-agent and multi-agent orchestration in environments with multiple tenants. It enforces strict isolation, tenant-scoped data handling, and auditable decision trails while coordinating a roster of specialized agents (planner, policy enforcer, tenant matcher, access controller, audit logger, researcher, and domain specialist).

When to Use This AGENTS.md Template

• You manage multiple tenants and must enforce tenant-scoped access control policies across services and data stores.
• You require auditable decision trails for policy evaluations, with clear handoffs between agents and domains.
• You need to separate tenant contexts but keep a centralized governance model for policy updates and risk management.
• You are building or extending a platform that requires strict data governance, secure secret handling, and regulated deployment of policy changes.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Platform Security Lead

Agent roster and responsibilities:
- Planner: defines tenant contexts, orchestrates policy flow, ensures tenant isolation.
- PolicyEnforcer: enforces tenant-specific access control decisions.
- TenantMatcher: maps user requests to the correct tenant context.
- AccessController: issues tokens and access grants per policy.
- AuditLogger: records decisions and policy changes for compliance.
- Researcher: sources policy references, threat models, and compliance requirements.
- Domain Specialist: provides domain-specific policy rules for particular tenants.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates all agents, maintains the single source of truth, and triages escalations.
- It enforces policy versioning, audit requirements, and tenant-context integrity across the workflow.

Handoff rules between agents:
- Planner -> Implementer (PolicyEnforcer): hand off policy definitions and tenant context.
- Implementer -> Reviewer: hand off implementation results and validation status.
- Reviewer -> Auditor: hand off audit review and sign-off status.
- Researcher -> Planner: hand off new policy findings and risk signals.

Context, memory, and source-of-truth rules:
- Each agent stores per-tenant memory scoped to current workflow; the policy store and IAM configuration are the source of truth.
- All decisions are traced to the policy version in effect at the time of decision.

Tool access and permission rules:
- Agents may call IAM APIs for token issuance only when approved by the Orchestrator; access to secrets is restricted to the AuditLogger.
- No agent can modify base policies without orchestrator approval and corresponding audit entries.

Architecture rules:
- Use a service-oriented architecture with a central policy service and tenant data partitioning.
- Ensure stateless agent components with observable sidecars for auditing and tracing.

File structure rules:
- Root/
  - policies/
    - tenants/
  - tenants/
  - agents/
    - planner/
    - policy-enforcer/
    - tenant-matcher/
    - access-controller/
    - audit-logger/
    - researcher/
    - domain-specialist/
  - workflows/
    - multi-tenant-acl/
  - README.md

Data, API, or integration rules when relevant:
- Use tenant-scoped APIs; avoid cross-tenant data leakage; integrate with a centralized identity provider.
- All data movement must be logged with tenant identifiers and policy version tags.

Validation rules:
- Unit tests for each agent; integration tests across tenant contexts; end-to-end validation with tenant workloads.

Security rules:
- Encrypt secrets at rest and in transit; enforce least privilege; rotate credentials regularly; implement secret-scoped access.

Testing rules:
- Include unit tests, integration tests, and end-to-end tests in CI for policy changes.

Deployment rules:
- Deploy policy updates via feature flags; canary policy changes; retain rollback plans.

Human review and escalation rules:
- Critical policy changes require human sign-off; escalate anomalies to Security Lead.

Failure handling and rollback rules:
- If a policy evaluation fails, rollback to the previous safe policy and trigger an audit review.

Things Agents must not do:
- Do not bypass approvals; do not share tenant data outside the tenant boundary; do not modify policy without audit.

Recommended Agent Operating Model

The operator model assigns clear roles and decision boundaries. Planner defines tenant scopes and policy intent. Implementer executes policy enforcement with tenant context. Reviewer validates changes before production. Auditor ensures traceability and compliance. Researcher and Domain Specialist provide domain-specific risk signals and policy refinements. Escalation paths lead to Security and Platform Owners when needed.

Recommended Project Structure

project-root/
└── workflows/
    └── multi-tenant-acl/
        ├── policies/
        │   └── tenants.yaml
        ├── tenants/
        │   ├── tenant-a/
        │   └── tenant-b/
        ├── agents/
        │   ├── planner/
        │   │   └── planner_agent.py
        │   ├── policy-enforcer/
        │   │   └── enforcer_agent.py
        │   ├── tenant-matcher/
        │   │   └── matcher_agent.py
        │   ├── access-controller/
        │   │   └── access_controller.py
        │   ├── audit-logger/
        │   │   └── audit_logger.py
        │   ├── researcher/
        │   │   └── researcher_agent.py
        │   └── domain-specialist/
        │       └── domain_specialist.py
        └── environments/
            ├── dev/
            └── prod/

Core Operating Principles

• Strict tenant isolation with a single source of truth for policy and identity.
• Deterministic decision-making with auditable outputs per tenant context.
• Least-privilege access and explicit approval gates for policy changes.
• Clear handoffs and versioned policies to prevent context drift.
• Observability, tracing, and security-by-design as core requirements.

Agent Handoff and Collaboration Rules

• Planner defines tenant scope and policy intent; Hand off to Implementer after policy sketch is complete.
• Implementer enforces policy logic against tenant data; Hand off to Reviewer for validation.
• Reviewer validates implementation against requirements and compliance; Hand off to Auditor for audit sign-off.
• Researcher and Domain Specialist provide supplementary signals to Planner; escalate risks to Security Lead as needed.
• Orchestrator coordinates all handoffs, ensures policy versioning, and enforces data boundaries.

Tool Governance and Permission Rules

• Only approved agents may access tenant data; secrets are stored securely and never embedded in code.
• Policy alterations require orchestrator approval and an auditable change record.
• All tool calls are logged with tenant context and agent identity.
• Production systems may be touched only through controlled deployment gates and feature flags.

Code Construction Rules

• Write modular, testable policy evaluation logic with clear interfaces between agents.
• Avoid hard-coding tenant identifiers; use a centralized tenant registry.
• Validate inputs to policy engines; fail closed on ambiguous decisions.
• Document all non-trivial decisions with sources and rationale in the audit log.

Security and Production Rules

• Encrypt data in transit and at rest; rotate keys; monitor for anomalous access patterns.
• Enforce least privilege on every API call; use short-lived credentials for agents.
• Implement thorough incident response and rollback procedures for policy changes.

Testing Checklist

• Unit tests for each agent’s logic.
• Integration tests that simulate multi-tenant workloads.
• End-to-end tests across tenant contexts with real-world scenarios.
• Security and compliance tests for data handling and auditing.

Common Mistakes to Avoid

• Skipping tenant context isolation, causing data leakage between tenants.
• Bypassing approval gates for policy changes.
• Ambiguity in handoff responsibility leading to stalled decisions.
• Untracked secret handling or hard-coded credentials.

Related implementation resources: AI Use Case for Policy Documents and Internal Question Answering and AI Use Case for Leasing Agents Using Zendesk To Answer Tenant Faq Queries Instantly Via Ai Chatbot.

FAQ

What is this AGENTS.md Template for multi-tenant access control?

It defines how AI coding agents collaborate to enforce tenant-scoped policies, isolate tenant data, and provide auditable decision trails with clear handoffs.

Who should use this AGENTS.md Template?

Product and platform teams, security engineers, and engineering leaders implementing tenant-aware access control with AI agents.

How are agent handoffs managed between tenants?

Handoffs follow a defined sequence: Planner → Implementer (policy enforcers) → Reviewer. Tenant context is preserved and only relevant data is passed.

What are the security requirements?

Use least privilege, encrypt sensitive data, audit decisions, and require human review for critical changes.

How do you validate the workflow?

Run unit tests for each agent, integration tests across tenant contexts, and end-to-end validation with simulated tenant workloads.