AGENTS.md Template: Idempotency Key Design

Overview

Direct answer: This AGENTS.md template defines the project operating context to implement idempotency keys for AI coding agents, enabling reliable single-agent and multi-agent orchestration with clear boundaries for key creation, storage, and reuse across workflows.

AGENTS.md template for idempotency key design governs a workflow where multiple agents collaborate to generate, validate, and apply idempotency keys to incoming requests, deduplicate work, and preserve system state across retries. It specifies who does what, how decisions are made, how context is shared, and how memory and truth sources are synchronized across agents.

When to Use This AGENTS.md Template

• When building AI coding agent workflows that require idempotent outcomes for repeated inputs or retries.
• When multiple agents must share a single source of truth for idempotency keys and their lifecycle.
• When you need explicit handoff rules, validation gates, and rollback procedures to prevent duplicate work.
• When governance and security rules must constrain tool access, secrets, and external API calls.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Platform Engineer / AI Systems Architect

Agent roster and responsibilities:
- Planner: designs the idempotency key strategy, defines key schema, expiry rules, and the orchestration plan across agents.
- Implementer: builds the key generation and storage mechanisms, integrates with the registry and memory store.
- Verifier: validates idempotent outcomes, ensures repeated requests map to the same result, and guards against state drift.
- Researcher: gathers domain constraints, edge cases, and external system behaviors affecting idempotency.
- Domain Specialist: confirms policy and legal constraints for data and idempotent flows.

Supervisor or orchestrator behavior:
- Orchestrator coordinates inter-agent handoffs, logs decisions, enforces concurrency limits, and ensures single source of truth. It issues commands and collects results from agents, then decides next steps.

Handoff rules between agents:
- Planner -> Implementer: provide key schema, storage plan, and initial state.
- Implementer -> Verifier: hand off completed key store state and test results for validation.
- Verifier -> Orchestrator: confirm idempotent outcome and surface any drift or failure.
- Researcher/Domain Specialist -> Planner: feed constraints and changes that affect the design.

Context, memory, and source-of-truth rules:
- All idempotency keys, mappings, and statuses live in a central memory store with durable persistence.
- Source of truth: the idempotency registry database and the canonical request log.
- Context is carried via structured messages with a defined schema and versioning.

Tool access and permission rules:
- Agents may call key registry APIs, memory store, and validated external services only.
- Secrets and credentials are never embedded in prompts or logs; use secure vaults and retrievable tokens.

Architecture rules:
- Event-driven, stateless workers with a central orchestrator.
- Clear service boundaries between planner, implementer, verifier, and memory layer.
- Idempotency keys must be created before work begins and reused for repeated requests.

File structure rules:
- /ai-skills/agents-md-templates/idempotency-key
  - planner/
  - implementer/
  - verifier/
  - memory/
  - orchestrator/
  - tests/

Data, API, or integration rules when relevant:
- Use a centralized key registry API for key creation and lookup.
- All accesses must be idempotent and logged.

Validation rules:
- Any repeated input must yield the same result unless there is an explicit state change.
- Validation must check key freshness, expiry, and drift against canonical logs.

Security rules:
- Do not export keys in logs; redact secrets in all traces.
- Enforce least privilege for API calls and service accounts.

Testing rules:
- Unit tests for key generation and validation logic.
- Integration tests that simulate duplicate requests and retries.
- End-to-end tests for a full idempotent workflow across agents.

Deployment rules:
- CI/CD with stage gates for idempotency policy checks.
- Canary deployment for changes to key handling.

Human review and escalation rules:
- Escalate anomalous key collisions to the security and platform teams.
- Human-in-the-loop review for policy changes affecting idempotency behavior.

Failure handling and rollback rules:
- If a duplicate is detected with conflicting results, rollback to canonical state and return the known outcome.
- If a critical failure occurs, halt the workflow and alert operators.

Things Agents must not do:
- Do not bypass validation or reuse keys outside policy.
- Do not mutate memory state without proper logging.
- Do not perform production changes without tests and approvals.

Recommended Agent Operating Model

The agent roles above share decision boundaries as follows: Planner mostly decides what to do and how; Implementer executes the plan; Verifier ensures idempotent stability; Orchestrator coordinates handoffs and maintains global context; Domain Specialist and Researcher provide policy and edge-case guidance. Escalations follow a clear path to the platform owner when policy, security, or data concerns arise.

Recommended Project Structure

ai-system/
  agents/
    idempotency-key/
      planner/
      implementer/
      verifier/
      memory/
      orchestrator/
      domain-specialist/
      researcher/
      tests/
  orchestrator/
  infra/
  docs/
  pipelines/
  config/

Core Operating Principles

• Clarity: all pacing, decisions, and data flow are documented and versioned.
• Determinism: identical inputs yield identical outputs, given the same state.
• Observability: comprehensive logging, tracing, and metrics for idempotency workflows.
• Security: strict access controls and secrets management.
• Accountability: every action is auditable with source-of-truth alignment.

Agent Handoff and Collaboration Rules

• Planner designs the plan and passes a formal task description to Implementer.
• Implementer executes and returns artifacts and evidence to Verifier.
• Verifier validates outcomes and reports to Orchestrator.
• Researcher and Domain Specialist provide constraint updates as callbacks.
• Orchestrator maintains global memory and coordinates retries or escalations.

Tool Governance and Permission Rules

• Only approved APIs and vault services may be called by agents.
• Requests to external services must be logged and subject to approval gates.
• Secrets never appear in prompts or logs; retrieve via secure vaults.
• Any production change requires sign-off from the change advisory board or equivalent.

Code Construction Rules

• Write idempotent, deterministic code paths for key generation and lookup.
• Validate inputs with strict schemas and fail fast on invalid requests.
• Use immutable data structures where possible; avoid in-place mutations without audit.
• Document interfaces and data contracts between agents.

Security and Production Rules

• Encrypt keys at rest and in transit; use TLS everywhere.
• Rotate credentials regularly and monitor for suspicious access.
• Implement rate limits and anomaly detection on idempotency endpoints.
• Backups and disaster recovery plans for the idempotency registry.

Testing Checklist

• Unit tests for key generation, storage, and validation logic.
• Integration tests for deduplication and repeated requests.
• End-to-end tests for a full idempotent workflow across agents.
• Security tests for secrets access and API authentication.

Common Mistakes to Avoid

• Assuming idempotency means no state changes; clearly define state transitions.
• Over-sharing memory state across agents; isolate to the canonical memory store.
• Skipping validation gates to speed up execution; this invites drift and errors.
• Hard-coding secrets or bypassing vaults and auditing.

Related implementation resources: AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams and AI Use Case for Xero Reports and Business Performance Insights.

FAQ

What is the purpose of this AGENTS.md Template for idempotency key design?

The template defines how to organize agents, memory, and handoffs to implement reliable idempotent workflows in AI coding agent systems.

Who are the recommended agent roles in this workflow?

Planner, Implementer, Verifier, Memory/Orchestrator, Researcher, and Domain Specialist are outlined with explicit responsibilities and handoff rules.

How are idempotency keys generated and stored?

Keys are generated by the Implementer using a cryptographically secure method, stored in a centralized registry, and referenced by all subsequent requests to ensure idempotent outcomes.

What constitutes proper handoffs between agents?

Handoffs follow a formal protocol: Planner to Implementer to Verifier to Orchestrator, with signed artifacts and traceable context at each step.

How are failures and rollbacks handled?

We rollback to the canonical state on detected drift or conflicting results; failures trigger escalation and safe-fail states with logs.