Session Caching AGENTS.md Template

Overview

Direct answer: This AGENTS.md Template defines the session caching workflow for AI coding agents, enabling both single-agent usage and multi-agent orchestration with explicit agent roles, handoffs, and governance.

It codifies the session caching architecture for AI coding agents, including how memory, source of truth, tool access, and escalation are managed across agents and services.

When to Use This AGENTS.md Template

• Designing AI coding agents that rely on per-session state and caching to reduce latency
• Coordinating multiple agents that must share a canonical session object and a single source of truth
• Defining governance, handoffs, and escalation rules for session related decisions

Copyable AGENTS.md Template

# AGENTS.md

Project role: Session Cache Architect and Orchestrator
Agent roster and responsibilities:
- OrchestratorAgent: coordinates tasks, enforces policies, triggers handoffs across agents
- SessionCacheAgent: manages cache storage, TTL, eviction, serialization
- DataSyncAgent: fetches and synchronizes session data from services
- TokenValidatorAgent: validates tokens in a session
- InvalidationAgent: invalidates expired or stale sessions
- AuditorAgent: logs actions and changes to the cache
Supervisor or orchestrator behavior:
- The OrchestratorAgent maintains a canonical session object and a single source of truth
- It orchestrates multi agent steps via clear handoffs and idempotent transitions
- All agents report to the Orchestrator and must not bypass it
Handoff rules between agents:
- DataSyncAgent hands off to TokenValidatorAgent for validation before writing to cache
- TokenValidatorAgent hands back to SessionCacheAgent for persistence if valid
- If cache miss or invalid data, OrchestratorAgent triggers DataSyncAgent to refresh
- Handoffs must include a short data packet: sessionId, timestamp, action
Context, memory, and source-of-truth rules:
- Canonical data lives in Redis as the primary cache store
- Memory within agents is ephemeral; they must read from and write to the canonical store
- The source of truth for session attributes is the primary session service, updated via the Orchestrator
Tool access and permission rules:
- Agents may access Redis, HTTP APIs, and secret vaults through the Orchestrator
- No direct access to production databases without approval
- Secrets must never be logged and must be retrieved from a vault with scoped permissions
Architecture rules:
- Agents are stateless; the Orchestrator maintains the workflow state
- All state transitions must be deterministic and idempotent
- Use a single event log for auditing
File structure rules:
- Place the code for all agents under src/ai-skills/agents-md-templates/session-cache
- Use a separate src/ai-skills/agents-md-templates/common for shared utilities
Data API or integration rules:
- Cache writes occur through the Orchestrator after validation
- Session reads come from a read replica or cache with TTL
- In case of cache miss, fetch from session service and populate cache
Validation rules:
- Validate TTLs, data types, and required fields on every write
- Ensure session data is synchronized within a defined window
Security rules:
- Encrypt secrets at rest and in transit
- Do not expose cache data to unauthorized services
Testing rules:
- Unit tests for each agent, integration tests for end-to-end flow, and smoke tests in CI
Deployment rules:
- Deploy agents behind feature flags; perform canary rollouts
- Monitor cache hit rate and latency after deployment
Human review and escalation rules:
- Any unexpected cache invalidation or data drift triggers manual review
- Escalate to on-call if SLA is breached
Failure handling and rollback rules:
- Operations are idempotent; on failure, revert to last good cache state
- Maintain an audit trail for rollbacks
Things Agents must not do:
- Do not bypass the Orchestrator
- Do not leak tokens or secrets
- Do not perform write operations to production without validation and approval

Recommended Agent Operating Model

The agent roles for session caching leverage a collaborative, multi-agent orchestration pattern. The Orchestrator binds the workflow, while specialized agents perform cache management, data synchronization, validation, and auditing. Escalation paths are explicit to reduce handoff latency and risk.

Recommended Project Structure

session-cache-workflow/
├─ agents/
│  ├─ orchestrator/
│  ├─ session_cache_agent/
│  ├─ cache_invalidation_agent/
│  ├─ data_sync_agent/
│  ├─ token_validator_agent/
│  └─ auditor_agent/
├─ configs/
├─ services/
├─ tests/
└─ docs/

Core Operating Principles

• Single source of truth for session data in Redis
• Deterministic and idempotent state transitions
• Clear escalation paths and auditable actions
• Least privilege access and secret management
• Observability through structured logs and metrics

Agent Handoff and Collaboration Rules

• Planner defines the sequence of data flow between DataSync, TokenValidator, and SessionCache
• Implementer executes the validated steps and updates the cache
• Reviewer verifies correctness before production write
• Tester validates end-to-end flow and failure modes
• Researcher surfaces data drift or schema changes for domain specialists
• Domain Specialist provides contextual guidance for session semantics

Tool Governance and Permission Rules

• Commands and file edits require orchestrator approval
• API calls and secrets access go through a vault with scoped permissions
• Production systems can be touched only with validated changes and monitoring
• Automatic rollback triggers for SLA violations

Code Construction Rules

• All writes go through the Orchestrator with validation
• Use idempotent operations for cache writes
• Keep logic in small, composable agents
• Do not bypass memory boundaries; do not rely on in-memory state for persistence

Security and Production Rules

• Secrets encrypted at rest and in transit
• Access controls tied to individual agents and roles
• Audit logging for all cache mutations and handoffs

Testing Checklist

• Unit tests for each agent
• Integration tests for end-to-end session caching workflow
• Performance tests for TTL and cache hit rate
• Deployment tests with feature flags

Common Mistakes to Avoid

• Skipping orchestrator governance for cache writes
• Overloading agents with direct production writes
• Ignoring data drift or schema changes in session data

Related implementation resources: AI Use Case for Content Marketers Using Wordpress To Auto-Translate Blog Posts Into Multiple Languages and AI Use Case for Corporate Event Managers Using Slack To Orchestrate Day-Of Venue Tasks Across Multi-Department Teams.

FAQ

What is the purpose of this AGENTS.md Template?

To standardize the session caching workflow for AI coding agents and enable reliable single-agent and multi-agent orchestration.

How do agents hand off in this workflow?

DataSyncAgent validates data with TokenValidatorAgent before SessionCacheAgent persists it, with the Orchestrator coordinating all transitions.

What about security?

Secrets are retrieved from a vault, encrypted in transit and at rest, and never logged by agents.

How is correctness tested?

Unit tests per agent, integration tests for the end-to-end flow, and CI smoke tests focused on cache state and TTL adherence.

How are failures handled?

Operations are idempotent with rollback to the last good cache state and escalation to on-call when SLA is breached.