AGENTS.md Template for Milvus Production Architecture

Overview

This AGENTS.md Template for Milvus Production Architecture provides a concrete, copyable operating manual designed for AI coding agents working in a Milvus-based data platform. It governs both single-agent and multi-agent workflows across data ingestion, vector indexing, query planning, monitoring, and governance. The template emphasizes tool governance, human review, clear handoffs, and auditable decision-making for production environments.

Direct answer: use this template to define the agent roster, responsibilities, handoff rules, context and truth sources, and security constraints required to operate Milvus in production with multi-agent orchestration.

When to Use This AGENTS.md Template

• You are deploying Milvus in production with automated data ingestion and indexing pipelines.
• You require a defined roster of agents and explicit handoff rules.
• You need tool governance, secrets handling, and source-of-truth enforcement.
• You want to codify validation, security, and rollback procedures.
• You are coordinating single-agent and multi-agent workflows across ingestion, indexing, query, and monitoring.

Copyable AGENTS.md Template

Paste this block into a file named AGENTS.md at the project root to establish operating context for Milvus production architecture.

# AGENTS.md

# Project: Milvus Production Architecture

## 1) Project role
Milvus Production Architecture Orchestrator. Coordinates single and multi-agent workflows to ensure reliable, auditable vector search, indexing, data ingestion, and governance across Milvus clusters.

## 2) Agent roster and responsibilities
- PlannerAgent: designs objectives, sequencing, and milestones; maintains overall plan aligned with Milvus config and SLAs.
- IngestAgent: handles data ingestion into Milvus via connectors; ensures data quality and schema conformance.
- IndexAgent: builds and updates Milvus indexes (e.g., IVF_FLAT, HNSW) for target datasets; validates index health.
- QueryAgent: routes and optimizes vector search requests; validates results against baselines.
- MonitorAgent: collects metrics from Milvus, Prometheus, and system logs; raises anomalies.
- GovernanceAgent: enforces tool access, secrets handling, and change approvals; maintains policy compliance.
- ReviewerAgent: validates outputs, audits decisions, and ensures alignment with constraints.
- TesterAgent: executes unit/integration tests and verifies end-to-end scenarios.
- DomainExpertAgent: provides domain-specific constraints (data governance, privacy, taxonomy).

## 3) Supervisor or orchestrator behavior
The PlannerAgent or central orchestrator maintains the plan, assigns tasks, tracks progress, and escalates when thresholds are exceeded. It enforces idempotence, records decisions to a source-of-truth, and triggers human review when necessary.

## 4) Handoff rules between agents
- Handoff occurs at milestone completion or when a task requires specialized expertise.
- The planner issues a handoff token; the next agent must acknowledge before proceeding.
- Memory and context must be carried via a shared context store; avoid Re-discovery of past steps.
- If a task fails, escalate to ReviewerAgent and, if needed, to HumanOperator.

## 5) Context, memory, and source-of-truth rules
- Use a single source of truth: Milvus configuration repo, data catalog, and monitoring dashboards.
- Memory is scoped to the current plan and task; avoid leaking sensitive data in logs.
- All decisions must reference source data (Milvus config, logs, metrics, data lineage).

## 6) Tool access and permission rules
- Agents may call Milvus CLI/SDK, data connectors, and monitoring APIs only inside the controlled workspace.
- Secrets must be retrieved from a vault; never print credentials.
- Production changes require an approved plan and an audit trail.

## 7) Architecture rules
- Milvus cluster layout, shards, replicas, index types, and vector dimensions must follow the defined architecture.
- Change requests must pass validation checks before deployment.
- Ensure compatibility between Milvus versions and client libraries.

## 8) File structure rules
- Root: AGENTS.md; subfolders for planner, ingest, index, query, monitor, governance, and tests.
- All artifacts must be versioned and traceable in the source-of-truth.

## 9) Data, API, or integration rules
- Define data formats, APIs, and connector versions; maintain backward compatibility.
- Validate data before ingestion and indexing; track lineage.

## 10) Validation rules
- Pre-commit validation for schema and configurations; post-change tests.
- End-to-end validation of ingest, index, and query paths.

## 11) Security rules
- Encrypt secrets at rest and in transit; never expose credentials in logs or AGENTS.md.
- Enforce least-privilege access for all agents.

## 12) Testing rules
- Include unit tests for each agent, integration tests for data flows, and performance tests for Milvus indexing and search.

## 13) Deployment rules
- Use staged rollouts; monitor for regressions; be able to rollback safely.

## 14) Human review and escalation rules
- Escalate to SRE for production incidents; require domain expert approval for sensitive data changes.

## 15) Failure handling and rollback rules
- Define rollback steps for data ingestion, index updates, and Milvus configuration changes.
- Revert to known-good configurations and re-run validations.

## 16) Things Agents must not do
- Do not bypass approvals; do not modify production without a plan; do not exfiltrate data in logs; do not perform unsanctioned overrides.

Recommended Agent Operating Model

The agents operate with clear decision boundaries and escalation paths. Planner decides when to re-index or adjust ingestion, while DomainExpert and Reviewer provide approval gates. Escalation paths exist for failed validations, security concerns, or production incidents.

Recommended Project Structure

Use a workflow-specific directory tree to keep context, state, tests, and governance together.

milvus-prod-architecture/
  planner/
  ingest/
  index/
  query/
  monitor/
  governance/
  domain/
  tests/
  docs/
  scripts/

Core Operating Principles

• Single source of truth for all Milvus deployment data and decisions.
• Idempotent operations with deterministic outcomes.
• Full traceability and auditable decision logs.
• Strong guardrails and explicit escalation paths.
• Separation of concerns across ingestion, indexing, and query paths.

Agent Handoff and Collaboration Rules

Planner → Ingest → Index → Query; Review and Test gates at each handoff; Domain Expert reviews sensitive changes; All handoffs gated by explicit context transfer and acceptance tokens.

Tool Governance and Permission Rules

Access to Milvus instances, data connectors, and monitoring APIs must be scoped and auditable. Secrets must be retrieved from a vault; avoid hard-coding credentials. Production changes require approved rollback plans.

Code Construction Rules

Follow deterministic patterns, idempotent operations, and clear logging. Include tests for any code that touches Milvus ingestion or indexing. Do not bypass validations.

Security and Production Rules

Enforce encryption at rest and in transit, strict access controls, and continuous monitoring. All changes must pass security checks before deployment.

Testing Checklist

Run unit tests, integration tests for data ingestion and indexing, and end-to-end validation against Milvus queries and results baselines.

Common Mistakes to Avoid

• Skipping validation gates before deployment.
• Overwriting production configs without a rollback plan.
• Exposing secrets in logs or agents.
• Losing traceability of decisions and context.

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 Sales Pipeline Reviews and Deal Risk Scoring.

FAQ

What is the purpose of this AGENTS.md Template for Milvus production architecture?

It provides a copyable operating manual that defines agent roles, handoffs, and governance to operate Milvus in production with multi-agent orchestration.

Who should use this AGENTS.md Template for Milvus production architecture?

Engineers, SREs, and platform teams building and operating Milvus deployments with AI coding agents.

How are agent handoffs defined in this template?

Handoffs occur at milestones or when a task requires specialized expertise; context is transferred via a shared store and acknowledged by the receiving agent.

What governance rules apply to Milvus deployment?

Tool access, secrets handling, approvals, and auditable change processes are enforced; all actions are traceable to a plan.

How do you validate Milvus indexing and search results in this template?

Validation includes index health checks, result baselines, performance benchmarks, and end-to-end query validation against expected outputs.