AGENTS.md Template for Weaviate Production Architecture

Overview

AGENTS.md template for Weaviate production architecture defines the operating context for AI coding agents in a production vector search stack. It governs both single-agent workflows and multi-agent orchestration across data ingestion, schema management, indexing, retrieval, and governance, with explicit handoffs, memory rules, and escalation paths.

Direct answer: This AGENTS.md template provides exact roles, guardrails, and collaboration patterns to operate a Weaviate-based system using AI coding agents, ensuring predictable handoffs and human review when needed.

When to Use This AGENTS.md Template

• When deploying a Weaviate production stack that relies on AI coding agents for data ingestion, indexing, and retrieval.
• When requiring multi-agent orchestration with explicit handoffs and escalation paths.
• When you need tool governance, secrets handling, and security guardrails.
• When you want a project-level operating context for single-agent and multi-agent workflows.

Copyable AGENTS.md Template

# AGENTS.md
Project Role: Weaviate Production Architecture Ops

Agent roster and responsibilities:
- Orchestrator (Planner): coordinates tasks, sets memory, manages handoffs, enforces deadlines.
- DataIngestor: fetches data from sources, cleans and normalizes.
- SchemaArchitect: designs and updates Weaviate schema.
- VectorIndexer: indexes data into Weaviate vector store.
- DataLoader: writes data to Weaviate and keeps indices consistent.
- Validator: validates data quality and schema constraints.
- SecurityOfficer: manages secrets, access control, keys.
- Auditor: monitors health, performance, and logs for anomalies.
- Researcher: gathers docs and examples for tasks.
- Reviewer: performs human validation and sign-off.

Supervisor or orchestrator behavior:
- Orchestrator discovers goals, creates a plan, assigns tasks to agents, monitors progress, and handles timeouts.
- Orchestrator enforces memory reflectiveness and source-of-truth rules.

Handoff rules between agents:
- DataIngestor completes a batch and hands off to Validator with data summary and quality metrics.
- Validator approves clean data and hands off to SchemaArchitect.
- SchemaArchitect updates the Weaviate schema if needed, then hands off to VectorIndexer.
- VectorIndexer indexes data in Weaviate and returns index IDs to DataLoader.
- DataLoader persists data into Weaviate and passes health signals to Auditor.
- Auditor runs health checks; if anomalies detected, escalate to Reviewer; otherwise finalize.

Context, memory, and source-of-truth rules:
- Each agent maintains a short-term memory bound to the current task; memory is cleared after handoff.
- The source of truth is the Weaviate cluster state, the published data sources, and the plan in memory to avoid drift.

Tool access and permission rules:
- Agents may call Weaviate API and external data APIs within approved scopes.
- Secrets must be retrieved from a secure vault; never hard-coded.
- Production operations require the Orchestrator approval gate for changes to schemas or data.

Architecture rules:
- Use a production-grade Weaviate cluster with proper replication and backups.
- All schema changes pass through versioned migrations.
- Changes are logged to a central audit trail.

File structure rules:
- Place code and configs under a structured folder layout:
  - agents/
    - planner/
    - data-ingestor/
    - schema-architect/
    - vector-indexer/
    - data-loader/
    - validator/
    - security-officer/
    - auditor/
    - researcher/
    - reviewer/
  - config/
  - schemas/
  - logs/
  - tests/
  - docs/
- Do not include unrelated folders or technologies.

Data, API, or integration rules when relevant:
- Ingest only canonical data with stable IDs; map to Weaviate classes and properties per the current schema.
- Use GraphQL or REST to interact with Weaviate; ensure consistent batch sizes.

Validation rules:
- Validate input data conforms to schema constraints; check duplicates and missing fields.
- Verify vector dimensions and similarity thresholds post-indexing.

Security rules:
- Secrets never appear in logs; rotate keys on schedule; enforce least-privilege access.

Testing rules:
- Unit tests for each agent, integration tests for end-to-end flow, and deployment validations.
- Run tests in CI before promotions to production.

Deployment rules:
- Use canary deployments for schema or data changes; require manual approval for breaking changes.
- Rollback plan documented in AGENTS.md; revert to last stable snapshot if failures occur.

Human review and escalation rules:
- Any anomaly triggers escalation to Reviewer; if unresolved in SLA, escalate to on-call engineer.

Failure handling and rollback rules:
- If a step fails, stop downstream tasks, revert any partial changes, and notify Orchestrator for rollback actions.

Things Agents must not do:
- Do not bypass the Orchestrator or make changes outside approved plans.
- Do not operate in production without approval.
- Do not leak secrets or create, edit, or delete resources without authorization.

Recommended Agent Operating Model

Agent operating model defines the roles, decision boundaries, and escalation paths for a Weaviate production architecture using AI coding agents. The Planner (Orchestrator) is the decision maker for task assignment; individual agents execute scoped tasks with clear completion criteria. Escalation paths route uncertain or high-risk decisions to human reviewers and, if needed, to on-call engineers.

Recommended Project Structure

Workflow-specific directory tree. Use only relevant folders and avoid unused technologies.

weaviate-prod/
├── agents/
│   ├── planner/
│   ├── data-ingestor/
│   ├── schema-architect/
│   ├── vector-indexer/
│   ├── data-loader/
│   ├── validator/
│   ├── security-officer/
│   ├── auditor/
│   ├── researcher/
│   └── reviewer/
├── config/
├── schemas/
├── logs/
├── tests/
└── docs/

Core Operating Principles

• Single source of truth is the Weaviate cluster state and the canonical data sources.
• Agents perform idempotent tasks and produce deterministic outputs when given the same inputs.
• Handoffs are explicit, time-bounded, and auditable.
• Observability is required: logs, metrics, and health checks are centralized.
• Security by default: least-privilege access, secret handling, and approved vaults.
• Human review is used for high-risk decisions or anomaly remediation.

Agent Handoff and Collaboration Rules

Concrete rules for planner, implementer, reviewer, tester, researcher, and domain specialist agents ensure reliable collaboration in Weaviate production architecture.

• Planner to Implementer handoffs require a task ticket with success criteria and acceptance tests.
• Reviewer validates human-in-the-loop decisions before production changes.
• Researcher supplies source material with citations; implementers must reference sources for reproducibility.
• Domain specialist validation occurs before schema or data model changes.

Tool Governance and Permission Rules

• Command execution, file edits, API calls, and secrets must pass through orchestrator approvals and least-privilege gates.
• Production systems require audit logging, access controls, and rotation of credentials.
• External service calls must be sanctioned with scopes and rate limits.
• All changes to schemas or critical data require reviewer sign-off and change tickets.

Code Construction Rules

• Do not hard-code secrets; fetch from a secure vault at runtime.
• Write idempotent, auditable code with clear inputs and outputs.
• Avoid context drift by anchoring to the current schema and data contracts.
• Do not bypass the orchestrator for production changes.

Security and Production Rules

• Encrypt data in transit and at rest; use TLS for all API calls.
• Secrets management via a centralized vault; rotate keys regularly.
• Disable non-essential endpoints and implement production-safe defaults.
• Monitor for abnormal patterns and trigger automated or manual rollback.

Testing Checklist

• Unit tests for each agent’s logic and inputs/outputs.
• Integration tests for end-to-end ingestion, indexing, and retrieval flows.
• End-to-end tests in a staging environment before production promotion.
• Smoke tests after deployment to confirm basic functionality.

Common Mistakes to Avoid

• Bypassing the orchestrator for production changes.
• Ignoring schema drift or data-contract changes during handoffs.
• Storing secrets in logs or source code archives.
• Unbounded memory growth or missing timeouts in multi-agent workflows.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring 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 for Weaviate?

It provides a copyable, production-ready AGENTS.md with explicit roles, handoffs, and governance to operate a Weaviate-based architecture using AI coding agents.

Which agents are included and what are their responsibilities?

A planner/orchestrator coordinates tasks; data ingestor cleans data; schema architect manages Weaviate schema; vector indexer handles vectorization; data loader writes to Weaviate; validator checks quality; security officer handles secrets; auditor monitors health; researcher gathers docs; reviewer performs human validation.

How are agent handoffs defined?

Handoffs are explicit: DataIngestor -> Validator -> SchemaArchitect -> VectorIndexer -> DataLoader -> Auditor, with escalation to Reviewer if anomalies are detected.

What are the security and permission rules?

Secrets must be stored in a secure vault, access granted on a least-privilege basis, and no secrets should be logged. All API calls must adhere to approved scopes and rotation schedules.

How do we handle failures and rollbacks?

Failures trigger rollback to previous stable state, with the Orchestrator pulling back tasks, enabling human review, and applying compensating actions to revert data or schema changes.