Vector Search RAG Architecture AGENTS.md Template

Overview

Direct answer style: This AGENTS.md template governs the vector search RAG architecture workflow and supports both single-agent and multi-agent orchestration in AI coding agents.

This AGENTS.md template defines roles, memory policies, handoff rules, tool governance, and escalation procedures to ensure reproducible results and auditable operations in a vector-based retrieval and answer generation loop.

When to Use This AGENTS.md Template

• When building AI coding agents that rely on vector search to retrieve relevant passages and code references.
• When orchestrating multi-agent workflows with clear handoffs among planner, retriever, context builder, reformulator, synthesizer, and verifier.
• To enforce tool governance, secrets handling, and human review in RAG pipelines.
• To establish a shared memory model and source-of-truth discipline for vector databases and knowledge bases.

Copyable AGENTS.md Template

# AGENTS.md
Project Role: Vector Search RAG Orchestration Lead
Agent roster and responsibilities:
- Planner/Orchestrator: Oversees the end-to-end vector search RAG pipeline, assigns tasks, enforces rules, and handles handoffs.
- Retriever Agent: Executes vector search queries against the embedding DB, retrieves top-K documents with metadata.
- Context Builder Agent: Builds a coherent context blob from retrieved passages, applies memory rules, and records sources-of-truth.
- Reformulator Agent: Transforms user intent and retrieved context into concrete agent prompts, ensuring tool usage policies.
- Answer Synthesis Agent: Generates the final answer by combining synthesized context with user prompt.
- Verifier Agent: Validates factual accuracy, safety, and alignment with policies; raises flags if uncertain.
- Human Reviewer: Optional escalation point for ambiguous or high-risk outputs.
- Monitor Agent: Tracks latency, success rate, and error signals.

Supervisor/Orchestrator behavior:
- Maintains a single plan per user query; enforces memory scope; routes outputs to next agents; triggers human review when risk signals occur.
- Stores decisions and provenance in a structured memory/log; references sources-of-truth for all outputs.
- Enforces tool governance, permission checks, and audit trails.

Handoff rules between agents:
- Planner -> Retriever: supply user query, constraints, and tool access scope.
- Retriever -> Context Builder: pass top-K passages with scores and metadata; include source-of-truth references.
- Context Builder -> Reformulator: deliver structured context and intent; provide any constraints or safety guards.
- Reformulator -> Answer Synthesis: provide prompt template and assembled context; pass policy controls.
- Answer Synthesis -> Verifier: pass final answer draft for validation.
- Verifier -> Human Reviewer (if needed) or -> Planner: output verdict and recommended next steps; otherwise -> final delivery.

Context, memory, and source-of-truth rules:
- Memory scope per session; do not leak across sessions.
- Primary sources: vector store for retrieved passages; code repositories and knowledge bases as secondary sources.
- All outputs must reference source URLs and IDs; maintain a canonical citation per passage.

Tool access and permission rules:
- Retriever, Context Builder, Reformulator, Answer Synthesis, and Verifier have read access to data sources; no write access to production systems.
- Secrets must be stored in a separate secrets store; never embed in prompts or outputs.
- Any API calls are mediated by the Planner; sensitive operations gated by approval gates.

Architecture rules:
- Microservice boundaries: each agent is a separate function; memory accessible via a central memory store.
- Stateless prompts; idempotent outputs; deterministic routing logic.

File structure rules:
- Keep artifacts under a single project namespace; do not create unrelated folders; store prompts, templates, and memory in dedicated folders.

Data, API, or integration rules:
- Use standardized schemas for passages; record or annotate with metadata; attach source URLs.

Validation rules:
- Each step must produce a structured JSON or Markdown artifact; outputs must be validated against schemas.

Security rules:
- Secrets stored securely; no secrets in prompts; access controls for tools; audit trails.

Testing rules:
- Unit tests for prompts; integration tests for the full chain; end-to-end tests on synthetic queries.

Deployment rules:
- Deploy plan with feature flags; monitor for failures; rollback if latency above threshold.

Human review and escalation rules:
- Escalate to Human Reviewer for high-stakes outputs; require explicit approval before production delivery.

Failure handling and rollback rules:
- If any step fails, roll back memory to last stable state; pause pipeline and notify planners.
- Retry limits and backoff; if repeated failures, trigger manual review.

Things Agents must not do:
- Do not reveal internal tool secrets; do not bypass approvals; do not perform destructive actions in production.

Recommended Agent Operating Model

The planner orchestrates the end-to-end flow, sets decision boundaries, and triggers escalation when risk signals appear. The agent roster operates with narrow, well-defined responsibilities and shared provenance. In vector search RAG, collaboration patterns rely on explicit memory references to retrieved passages, citations, and source-of-truth IDs. Escalation to a human reviewer is mandatory for highly uncertain or high-stakes outputs.

Recommended Project Structure

vector-rag/
  agents/
    planner/
    retriever/
    context_builder/
    reformulator/
    synthesizer/
    verifier/
    human_reviewer/
    monitor/
  prompts/
  memory/
  tools/
  data/
  tests/
  deployment/
  docs/

Core Operating Principles

• Clear memory scope and source-of-truth discipline
• Explicit, auditable handoffs between agents
• Tool governance with restricted permissions and approvals
• Idempotent, deterministic outputs per query
• Fail-fast on uncertain outputs and escalate promptly

Agent Handoff and Collaboration Rules

• Planner communicates objectives and constraints to Retriever
• Retriever passes retrieved passages to Context Builder with sources
• Context Builder builds context and forwards to Reformulator
• Reformulator creates a safe, constrained prompt for Answer Synthesis
• Answer Synthesis passes draft to Verifier
• Verifier either approves to deliver or escalates to Human Reviewer
• Human Reviewer can instruct Planner to retry, modify constraints, or escalate

Tool Governance and Permission Rules

• Only read access to data sources; write actions gated by Planner
• Secrets kept in a dedicated secrets store; never surfaced in prompts or outputs
• All API calls logged with provenance; rate limits enforced

Code Construction Rules

• Prompts must be deterministic and testable
• Code outputs must reference sources of truth via citations
• Avoid scaffolds that bypass queueing and approvals

Security and Production Rules

• Encrypt sensitive data at rest and in transit where applicable
• Run in protected environments; production changes require approval
• Monitor for anomalous queries; trigger auto-disable if threats detected

Testing Checklist

• Unit tests for each agent function and prompt
• Integration tests across Planner, Retriever, Context Builder, and Verifier
• End-to-end tests with synthetic user queries
• Performance tests to ensure latency thresholds

Common Mistakes to Avoid

• Skipping explicit memory and source-of-truth references
• Over-permitting tools or bypassing approvals
• Unclear handoffs leading to context drift
• Ignoring security and data handling policies

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Policy Documents and Internal Question Answering.

FAQ

What is this AGENTS.md template for vector search RAG architecture?

It provides an operating manual for single and multi-agent workflows in a vector-based retrieval-augmented generation setup, including roles, handoffs, prompts, and governance.

Which agents are part of the roster?

The roster typically includes Planner/Orchestrator, Retriever, Context Builder, Reformulator, Answer Synthesis, Verifier, and optional Human Reviewer and Monitor.

How are handoffs defined?

Handoffs are explicit, with inputs, outputs, and memory references passed to the next agent, and logged for provenance.

What about tool access and secrets?

Tools are governed with restricted permissions; secrets are stored separately and never exposed in prompts or outputs.

How is memory managed?

Memory is scoped to the session and the vector store serves as the primary source of truth; code repositories provide secondary sources.