AGENTS.md Template for Enterprise Integration Agents

Overview

AGENTS.md Template for enterprise integration agents is a project-level operating manual that governs both single agent workflows and multi-agent orchestration. It provides a copyable block you can paste into an AGENTS.md file to establish roles, rituals, and governance across integration tasks.

Direct answer: This template defines an enterprise-grade agent roster, delegated responsibilities, and orchestrator rules to ensure predictable handoffs, secure data handling, and auditable executions across systems.

When to Use This AGENTS.md Template

• You are building an enterprise integration platform that requires multiple AI coding agents to collaborate across SaaS and on-premises systems.
• You need explicit agent roles, handoff rules, and an orchestrator to coordinate tasks and data flow.
• You want an auditable, repeatable operating manual that can be versioned with your codebase.
• You require tool governance, secrets handling, and human review as part of the workflow.

Copyable AGENTS.md Template

# AGENTS.md
Project role
- Enterprise Integration Platform Automation Lead

Agent roster and responsibilities
- Planner: defines goals, milestones, and plans for the enterprise integration flow.
- Integrator: implements adapters for enterprise apps, models data transformations, and maintains mapping rules.
- Orchestrator: coordinates all agents, maintains the task queue, triggers handoffs, and enforces constraints.
- Implementer: executes integration steps, performs API calls, data shaping, and error handling.
- Reviewer: validates outputs, ensures data quality, and approves handoffs to production.
- Data Engineer: maintains schemas, lineage, and source-of-truth alignment.
- Security Auditor: reviews secrets usage and access controls.

Supervisor or orchestrator behavior
- The orchestrator maintains a single source of truth, logs progress, and retries failed steps with safe defaults.
- It enforces boundaries, ensures idempotency, and escalates issues when human review is required.

Handoff rules between agents
- Handoffs occur only after a successful validation or when a task transitions to a new phase.
- Each handoff must include a context payload, memory keys, and a reference to the source-of-truth.
- The receiving agent must acknowledge and demonstrate readiness before execution.

Context, memory, and source-of-truth rules
- Context is the current task, goals, and constraints.
- Memory stores task state, decisions, and observations with a canonical memory key per task.
- Source of truth is the canonical data store or contract that all agents consult before acting.

Tool access and permission rules
- Tools and adapters are accessed through a controlled permissions model.
- Secrets are stored in a vault and never hard-coded.
- External calls are logged, monitored, and limited to approved scopes.

Architecture rules
- Use event-driven, idempotent components with clear contracts.
- All agents operate under a single orchestrator for multi-agent flows.
- Each step is auditable and replay-safe.

File structure rules
- Keep per-flow modules under a dedicated folder with explicit names.
- Avoid duplicating logic across agents.

Data, API, or integration rules when relevant
- Validate input data against canonical schemas.
- Respect rate limits and pagination when calling external services.
- Prefer incremental updates and idempotent writes.

Validation rules
- Validate outputs against data contracts and schemas.
- Fail fast on schema drift and incompatible responses.

Security rules
- Rotate credentials regularly; use role-based access control.
- Do not log secrets; encrypt sensitive data at rest in transit.

Testing rules
- Include unit tests for adapters and data transforms.
- Include integration tests that exercise end-to-end flows with mocks for external services.

Deployment rules
- Gate deployments behind feature flags and approvals.
- Run canary tests in staging before production.

Human review and escalation rules
- Escalate any anomaly or data drift to a human reviewer.
- Maintain an auditable trail of decisions and approvals.

Failure handling and rollback rules
- Implement idempotent rollback steps and compensating actions.
- Maintain a rollback plan and a recovery checklist.

Things Agents must not do
- Do not bypass approvals or skip tests.
- Do not expose secrets in logs or error messages.
- Do not modify production data without validation and rollback capability.
- Do not drift from the canonical source of truth.

Recommended Agent Operating Model

In enterprise integration, define agent roles and decision boundaries. The orchestrator is the guardian of process state; planners design strategies; integrators implement adapters; implementers execute steps; reviewers ensure quality; domain specialists can be added for particular apps. The escalation path: if a task fails or is blocked, escalate to human owner or senior architect. The model supports both single-agent and multi-agent flows; the orchestrator handles handoffs and ensures data integrity across steps.

Recommended Project Structure

Workflow-specific directory tree.

enterprise-integration/
  orchestrations/
  agents/
    planner/
    integrator/
    orchestrator/
    reviewer/
  connectors/
  data/
  configs/
  tests/
  docs/
  scripts/

Core Operating Principles

• Single source of truth for each task
• Idempotent actions and safe retries
• Explicit ownership and clear escalation paths
• Auditable decisions and traceable handoffs
• Secure handling of secrets and restricted tool access

Agent Handoff and Collaboration Rules

• Planner to Integrator: share goals, schemas, and mapping rules
• Integrator to Orchestrator: report readiness and task state
• Orchestrator to Implementer: trigger execution with context
• Reviewer to Production: require validation before production
• Domain Specialist to any agent: provide app-specific constraints and approvals

Tool Governance and Permission Rules

• Execute commands only through approved adapters
• Access to secrets strictly limited by role
• All API calls audited and rate-limited
• Production system changes require supervisor approval

Code Construction Rules

• Write adapters as pure, idempotent functions
• Validate inputs and outputs against contracts
• Avoid side effects outside designated tool calls
• Document interfaces and data contracts inline

Security and Production Rules

• Secrets in vault, rotated on schedule
• Least privilege access for all agents
• Encrypt data in transit and at rest
• Enable audit logs for all external interactions

Testing Checklist

• Unit tests for adapters and transformers
• Contract tests for data contracts
• End-to-end tests with mocks and approved data
• Canary tests in staging before production

Common Mistakes to Avoid

• Skipping formal handoffs and context sharing
• Bypassing the source of truth or secret controls
• Unbounded retries without rollback paths
• Ignoring privacy and security requirements

FAQ

What is the purpose of this AGENTS.md Template for enterprise integration agents?

It defines an operating manual for single and multi-agent workflows to automate enterprise integration tasks, enforce handoffs, tool governance, and human review.

Who should use this AGENTS.md Template?

Platform teams, automation engineers, and engineering leaders building enterprise integration flows with multiple agents.

What are the key rules for agent handoffs?

Handoffs require context payloads, memory keys, source-of-truth alignment, and explicit acceptance by the next agent.

How is security enforced in this workflow?

Secrets must be stored securely, access is restricted by role, and every external call is audited and validated.

How do you validate outputs from agents?

Validated against schemas, contracts, and end-to-end tests; failures trigger human review and rollback if needed.