Blob Storage Architecture AGENTS.md Template

Overview

The AGENTS.md Template for Blob Storage Architecture defines the operating context for AI coding agents that manage blob storage workflows. It governs a multi-agent orchestration pattern including agent handoffs, tool governance, and human review, while also supporting single-agent execution when appropriate.

When to Use This AGENTS.md Template

• When building automation around blob storage ingest, retention, lifecycle, and access control.
• When you need explicit agent roles, handoff rules, and governance for cloud storage workflows.
• When you require a copyable, project-scoped operating manual that teams can customize.

Copyable AGENTS.md Template

# AGENTS.md

Project: Blob Storage Architecture Automation

Agent roster and responsibilities:
- PlannerAgent: orchestrates tasks and sequencing across blob storage flows.
- IngestAgent: handles blob ingestion from sources and metadata extraction.
- ValidateAgent: validates data integrity and schema adherence.
- PolicyAgent: enforces access controls, retention policies, and lifecycle rules.
- AccessAgent: manages keys, secrets, and credentials with least privilege.
- AuditorAgent: monitors actions, security events, and cost anomalies.
- DomainAgent: subject-matter expert for blob storage domain rules.

Supervisor / orchestrator behavior:
- The PlannerAgent maintains the current plan, tracks progress, and assigns tasks to subordinate agents.
- Orchestrator output feeds into memory and the single source of truth: BlobInventoryCatalog.
- All outputs are versioned and stored in the Workspace/State store.

Handoff rules between agents:
- on TaskComplete from one agent, trigger the next agent's TaskStart with the produced IO.
- If an agent fails to produce valid output, escalate to human reviewer and roll back to a safe state.

Context, memory, and source-of-truth rules:
- context is persisted in WorkspaceState. stateSnapshot contains inputs, outputs, and decisions.
- source of truth is BlobInventoryCatalog.

Tool access and permission rules:
- Tools: CLI for cloud storage (e.g., az storage blob), REST APIs, and SDKs.
- Permissions: least privilege; secrets stored in a vault with rotation.

Architecture rules:
- 3-tier blob storage; tiering, lifecycle rules, and access boundaries are explicit.

File structure rules:
- All artifacts live under project/workflows/blob-storage-architecture/

Data, API, or integration rules when relevant:
- Ingest Agents fetch data via secure endpoints; all calls are logged and versioned.

Validation rules:
- Outputs must meet schema, retention, and correctness constraints; validate with unit tests.

Security rules:
- Encrypt at rest, in transit; rotate keys; enforce access controls.

Testing rules:
- Unit, integration, and end-to-end tests for ingestion, policy, and access flows.

Deployment rules:
- Deploy via CI/CD with canaries; require PR approvals and validation tests.

Human review and escalation rules:
- Any anomaly escalates to security/operations; humans can approve or rollback.

Failure handling and rollback rules:
- If critical failure occurs, revert to latest known-good BlobInventoryCatalog state and pause ingestion.

Do not:
- Do not bypass authentication, bypass validations, or mutate production data without approval.

Things Agents must not do:
- Never edit production policies without supervisor approval.
- Do not access secrets outside the vault.

Recommended Agent Operating Model

Roles and responsibilities are defined to minimize overlap and ensure clear escalation paths. Planner blends strategy with execution, while specialized agents perform concrete storage operations. Decision boundaries keep humans involved for security-sensitive or high-impact changes.

Recommended Project Structure

blob-storage-architecture/
├── agents/
│   ├── planner/
│   ├── blob-ingest/
│   ├── blob-validate/
│   ├── blob-policy/
│   ├── access-manager/
│   └── domain-specialist/
├── configs/
├── data/
├── policies/
├── manifests/
├── workflows/
└── tests/

Core Operating Principles

• Explicit roles and boundaries for each agent.
• Single source of truth and versioned state snapshots.
• Human review for security-sensitive changes and production deployments.
• Idempotent, auditable actions with rollback support.

Agent Handoff and Collaboration Rules

• Planner to Ingest: pass task and input context.
• Ingest to Validate: provide ingest outputs and schema, trigger validation.
• Validate to Policy: if valid, apply policy rules; otherwise escalate.
• Policy to Access Manager: enforce access and secrets handling before data access.
• All handoffs require a signed, versioned artifact and an event log entry.

Tool Governance and Permission Rules

• Execute only approved commands and SDK calls with least privilege.
• Secrets must be retrieved from a vault; no hard-coded credentials.
• All external calls must be logged and traceable.
• Approve production actions via a human gate.

Code Construction Rules

• Follow the AGENTS.md Template style for consistency.
• All data paths and storage operations must be idempotent.
• Include unit, integration, and contract tests for storage interfaces.
• Document every change with a rationale in the action history.

Security and Production Rules

• Encrypt data at rest and in transit.
• Rotate and audit credentials; restrict production write access.
• Perform security reviews for new storage policies and orchestration changes.

Testing Checklist

• Unit tests for each agent action.
• Integration tests for ingest, policy application, and access controls.
• End-to-end tests covering multi-agent handoffs.
• Canary deployments and post-deploy smoke tests.

Common Mistakes to Avoid

• Avoid context drift between agents; rely on a single source of truth.
• Do not bypass security reviews for quick changes.
• Do not create overlapping agent responsibilities.
• Do not deploy without proper tests and approvals.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is an AGENTS.md Template for blob storage architecture?

An AGENTS.md Template provides a project-level operating context for AI coding agents and multi-agent orchestration to govern blob storage workflows.

How does multi-agent orchestration work in this template?

A planner coordinates tasks while specialized agents—ingest, validation, policy, and access managers—execute work. Memory and a single source of truth synchronize outputs.

What are the handoff rules between agents?

Handoffs occur on event triggers and task completion. Outputs feed the next agent, with escalation rules if a handoff fails to produce valid results.

What security considerations are included?

Least-privilege access, secret management, audit logging, and production gating are enforced. No production changes without human review.

How do I customize and validate this template for blob storage?

Follow the Code Construction Rules, implement unit and integration tests, and use the Deployment Rules and Human Review guidelines to validate changes.