AGENTS.md Template for Batch Processing Architecture

Overview

Direct answer: This AGENTS.md Template defines how AI coding agents operate in batch processing, enabling both single-agent execution and multi-agent orchestration with clear handoffs, memory, and governance for batch workflows.

The AGENTS.md Template for Batch Processing Architecture formalizes the operating model, roles, and interaction rules that govern AI coding agents across end-to-end batch jobs, from data ingestion to export. It provides a copyable project-level instruction block that teams can paste into an AGENTS.md file to establish a repeatable, auditable workflow.

When to Use This AGENTS.md Template

When designing batch processing workflows that require AI agents to coordinate across stages (ingest, transform, validate, export).
When you need explicit handoffs, memory management, and source-of-truth rules to prevent context drift.
When establishing tool governance, permissions, and exception handling across a batch orchestration pattern.
When you want a reproducible operating model that supports both single-agent and multi-agent orchestration.

Copyable AGENTS.md Template

Copy this AGENTS.md template block into your project as the central operating context for batch processing agents.

# AGENTS.md

Project: Batch Processing Orchestrator

Agent roster:
- Planner: designs the batch plan, schedules steps, and coordinates handoffs.
- Ingestor: handles data ingestion from sources, validates input schemas, and supplies batch inputs.
- Transformer: applies domain-specific transformations, enrichments, and normalization.
- Validator: runs quality checks, schema validation, and integrity verification.
- Exporter: writes results to target systems (data lake, warehouse, or downstream services).
- Monitor: tracks performance, SLA adherence, and anomaly detection.
- Auditor/Domain Specialist: performs security, compliance review, and domain-specific checks.
- Handover Specialist: ensures proper memory propagation and context transfer between agents.

Supervisory orchestrator behavior:
- The Planner emits a batch execution plan with step dependencies and memory handoff points.
- The Orchestrator assigns steps to agents and enforces order, retries, and timeouts.
- The memory store batch_context= {batch_id, step, inputs, outputs, notes} is the source of truth for context propagation.

Handoff rules between agents:
- Each step stores a summary of its outputs to batch_context and passes the relevant context to the next agent.
- If a step fails, the orchestrator triggers escalation, retry, or rollback according to the failure policy.

Context, memory, and source-of-truth rules:
- All batch runs share a centralized, immutable batch_context store.
- Agents must read from and write to batch_context for provenance.
- Do not rely on ephemeral in-memory state beyond a single step.

Tool access and permission rules:
- Agents may access only approved tools (db_client, http_client, shell_executor) with scoped credentials.
- Secrets must be retrieved from a secrets manager and never hard-coded.
- Production system access is gated and audited; approvals required for write actions.

Architecture rules:
- Use modular, idempotent steps with clear inputs/outputs.
- Each agent should be stateless except for batch_context memory.
- Support retries with exponential backoff; avoid cascading failures.

File structure rules:
- Organize per batch-processing/ with subfolders for planner, ingest, transform, validate, export, monitor, and docs.

Data, API, or integration rules:
- Use strict input/output schemas; document API contracts and failure modes.
- Rate-limit external calls and implement backpressure.

Validation rules:
- Validate that outputs meet schema, data quality metrics pass, and idempotency holds for retries.

Security rules:
- Encrypt sensitive data at rest and in transit; rotate credentials; audit data access.

Testing rules:
- Unit tests per agent; integration tests for end-to-end batch flow; regression tests for schema changes.

Deployment rules:
- CI/CD with observable feature flags; blue/green or canary deployments for batch orchestrator updates.

Human review and escalation rules:
- Domain expert review for edge cases; operations on-call for production incidents.

Failure handling and rollback rules:
- If a batch fails, roll back to last-good_context and notify stakeholders; preserve logs for investigation.

Things Agents must not do:
- Do not bypass validation, bypass safeguards, or perform unsupervised production changes.
- Do not access production secrets directly; use secrets manager.
- Do not delete data without explicit approval.

Recommended Agent Operating Model

The model defines the roles, responsibilities, decision boundaries, and escalation paths for batch-processing agents, enabling a clear separation of concerns and predictable handoffs.

Planner: defines sequence, dependencies, and success criteria; communicates via batch_context.
Ingestor/Transformer/Validator/Exporter: perform domain-specific steps with defined inputs/outputs; raise signals to orchestrator on completion or failure.
Monitor and Auditor: observability and governance; escalate anomalies to human reviewers when SLAs are breached.
Handover Specialist: ensures memory propagation and avoids context drift across steps.

Recommended Project Structure

Workflow-specific directory tree:

/workflows/batch-processing/
  /planner
  /orchestrator
  /ingest
  /transform
  /validate
  /export
  /monitor
  /tests
  AGENTS.md

Core Operating Principles

Idempotent steps with explicit inputs/outputs and versioned artifacts.
Single source of truth per batch (batch_context).
Explicit handoffs and memory propagation between agents.
Least privilege and auditable actions for all tools.
Deterministic behavior; traceable execution history.

Agent Handoff and Collaboration Rules

Planner to Ingestor: include batch_id, schema, and input datasets in batch_context.
Ingestor to Transformer: pass validated inputs and enrichment metadata.
Transformer to Validator: pass transformed data and quality tokens.
Validator to Exporter: pass validated batch outputs and export targets.
Monitor to Auditor: alert on SLA breaches or anomalies; provide logs for review.

Tool Governance and Permission Rules

Commands: only approved shell or API calls with strict quotas.
File edits: restrict to designated folders; require review for changes to production configs.
APIs/Integrations: use token-scoped clients; rotate tokens; respect rate limits.
Secrets/Production systems: never store plaintext secrets; fetch from vaults with access control.
Approval gates: require human approval for production data writes beyond allowed thresholds.

Code Construction Rules

Follow strict typing, linting, and documentation for each agent.
Write deterministic, side-effect-limited code; isolate external calls and handle retries.
Use idempotent batch operations; avoid global mutable state.
Document input/output contracts and error-handling strategies.

Security and Production Rules

Protect secrets; enforce encryption in transit and at rest.
Audit logs for every write; redact sensitive data in logs where possible.
Separate staging and production environments with proper access controls.
Implement blast-radius based rollback plans for batch failures.

Testing Checklist

Unit tests: agent-level tests for inputs/outputs and error handling.
Integration tests: end-to-end batch workflow with mock external systems.
Performance tests: batch size, concurrency, and backpressure tests.
Deployment tests: canary and feature-flag validations.

Common Mistakes to Avoid

Skipping validation or bypassing memory propagation between steps.
Uncontrolled handoffs resulting in context drift.
Exposed production secrets or brittle integrations.
Ignoring observability and auditability in batch jobs.

FAQ

What is the purpose of this AGENTS.md Template for Batch Processing Architecture?

It defines roles, workflows, and governance for AI coding agents in batch processing and supports both single-agent and multi-agent orchestration.

Which agents are involved in this pattern?

Planner, Ingestor, Transformer, Validator, Exporter, Monitor, Auditor, and Handover Specialist participate in the batch workflow.

How are handoffs defined between agents?

Handoffs occur via batch_context with explicit context propagation; the orchestrator enforces order and retries on failure.

What are the security considerations?

Use secrets management, least privilege, encryption, audit trails, and approvals for production actions.

How do I validate and test batch jobs?

Unit tests per agent, integration tests for the whole flow, and rollback checks for failures.

Target User

Use Cases