AGENTS.md Template for Real Estate Analytics Agents (AGENTS.md template)

Overview

Direct answer: This AGENTS.md template defines the operating context for a real estate analytics agent system, enabling both single-agent work and multi-agent orchestration across data ingestion, modeling, and insights delivery.

The AGENTS.md template governs an end-to-end real estate analytics workflow and provides guardrails, roles, and handoff rules that ensure consistency, traceability, and safe collaboration among agents.

When to Use This AGENTS.md Template

• You are building an end-to-end real estate analytics pipeline that relies on AI coding agents to ingest data, build models, generate insights, and produce reports.
• You need a clear roster of agent roles and explicit handoff rules for multi-agent orchestration.
• You must enforce tool governance, permissions, data source controls, and security constraints.
• You want a standard operating model that can be used by product teams and engineering leaders to onboard new agents quickly.

Copyable AGENTS.md Template

# AGENTS.md

Project Role: Real Estate Analytics Agent System

Agent roster and responsibilities:
- Planner: designs the workflow, defines data sources, and creates task plans.
- IngestorAgent: connects MLS, CRM, and property data feeds; normalizes and quality-checks data.
- ValuationAgent: computes valuations using models and external benchmarks; produces confidence estimates.
- MarketTrendsAgent: collects market data and analyzes trends.
- Orchestrator: coordinates tasks, enforces dependencies, triggers handoffs, and maintains session state.
- Reviewer: validates outputs, ensures accuracy, and flags issues for escalation.

Supervisor or orchestrator behavior:
- The Orchestrator continuously monitors task progress, enforces order of operations, times out stalled tasks, and logs events for traceability.
- It initiates handoffs when data or context is ready and ensures outputs are passed with preserved context.

Handoff rules between agents:
- Planner -> IngestorAgent after the task plan and sources are defined.
- IngestorAgent -> ValuationAgent after data ingestion completes and quality checks pass.
- ValuationAgent -> MarketTrendsAgent for contextual benchmarks when needed.
- All outputs pass to Reviewer before final deployment or reporting.

Context, memory, and source-of-truth rules:
- Context keys include currentTaskId, datasetVersion, and outputArtifactRef.
- Memory persists only within the current session; long-term memory is stored in versioned artifacts.
- Source of truth is versioned data from MLS feeds, CRM systems, and verified property records.

Tool access and permission rules:
- Agents may call MLS APIs, CRM APIs, and public data sources with strict rate limits.
- Secrets are accessed only via the environment vault and are never embedded in artifacts.
- No agent may modify production data outside approved pipelines.

Architecture rules:
- System is event-driven with a central orchestrator and stateless agents.
- All changes are versioned; outputs are auditable and reproducible.

File structure rules:
- Use a clean, version-controlled repository; avoid duplicate artifacts; ensure clear naming.

Data, API, or integration rules when relevant:
- Ensure data freshness checks on MLS outputs; respect API quotas; handle missing data gracefully.

Validation rules:
- Validate input schemas, data freshness, and output quality against predefined thresholds.
- Validation results must be stored with artifacts for audit.

Security rules:
- Abide by data privacy rules; minimize PII exposure; encrypt sensitive data at rest and in transit.
- Secrets rotation is mandated; do not share keys in logs or artifacts.

Testing rules:
- Unit tests for each agent; integration tests across agent handoffs; end-to-end simulations.

Deployment rules:
- Deploy in small increments; use canary deployment; verify metrics before full rollout.

Human review and escalation rules:
- If a model output falls outside confidence thresholds or data quality flags trigger issues, escalate to a human reviewer.
- All escalations are logged and tracked.

Failure handling and rollback rules:
- If a critical failure occurs, rollback to the last known-good artifact, pause downstream tasks, and notify stakeholders.
- Retry logic is bounded; after max retries, escalate.

Things Agents must not do:
- Do not modify source data in production data sources without explicit approval.
- Do not bypass governance or skip validation steps.
- Do not leak secrets in logs or artifacts.

Recommended Agent Operating Model

The agent operating model defines role boundaries, decision rights, and escalation paths for real estate analytics tasks. Each agent has a clear scope and handoff contract, with the Orchestrator acting as the central conductor for multi-agent workflows.

Recommended Project Structure

real-estate-analytics/
├── agents/
│   ├── planner/
│   ├── ingestor/
│   ├── valuation/
│   ├── market-trends/
│   └── reviewer/
├── orchestrator/
├── data/
├── configs/
├── tests/

Core Operating Principles

• Single source of truth for data and artifacts.
• Idempotent agent operations and deterministic outputs.
• Explicit handoffs with preserved context and provenance.
• Auditable decisions and traceable execution history.
• Secure handling of data and secrets with least-privilege access.

Agent Handoff and Collaboration Rules

• Planner provides task plan and data sources to IngestorAgent.
• IngestorAgent returns cleaned data and a quality report to ValuationAgent and Reviewer.
• ValuationAgent returns valuation outputs to Reviewer and Orchestrator.
• Reviewer validates and signs off before deployment or reporting.
• Handoffs require explicit context propagation and artifact IDs to prevent drift.

Tool Governance and Permission Rules

• Commands to external services require approved scopes and audit logs.
• File edits must be done through controlled paths and with versioning.
• Secrets must never be exposed in logs; use vaults and access controls.
• Production systems require approval gates and runbooks for rollback.

Code Construction Rules

• Code must be modular, documented, and testable.
• Follow real estate data model standards; explicit input validation.
• Avoid hard-coded keys; inject via environment or secret manager.

Security and Production Rules

• Data privacy first; restrict PII; encryption in transit and at rest.
• Access control and audit trails for all agents and orchestrator actions.
• Production deployments require rollback plans and post-release monitoring.

Testing Checklist

• Unit tests for each agent with mocked data sources.
• Integration tests across agent handoffs.
• End-to-end tests simulating real estate analytics scenarios.
• Security and permission checks in CI.

Common Mistakes to Avoid

• Skipping validation or rushing to production without human review.
• Leaking secrets or bypassing tool governance.
• Drifting away from the organization data model and provenance.

FAQ

What is the purpose of this AGENTS.md Template for Real Estate Analytics Agents?

To provide a project-level operating context for single-agent and multi-agent workflows in real estate analytics.

Which agents are in the roster and what are their responsibilities?

Planner designs the workflow, IngestorAgent secures data, ValuationAgent computes valuations, MarketTrendsAgent analyzes market trends, Orchestrator coordinates, Reviewer validates outputs.

How are handoffs between agents governed?

Handoffs require preserved context, artifact IDs, data quality gates, and explicit task dependencies to avoid drift.

What are the security and data governance constraints?

Minimize PII exposure, encrypt data, rotate secrets, and require approvals for production data access and sharing.

How do you handle failures and rollbacks?

On failure, revert to last good artifact, pause downstream tasks, retry within limits, and escalate if unresolved.