AGENTS.md Template for Hybrid Search Architecture

Overview

Direct answer: This AGENTS.md template defines a hybrid search architecture that coordinates AI coding agents for both vector and keyword search, enabling single-agent and multi-agent orchestration with clear handoffs and governance.

This AGENTS.md template for hybrid search architecture provides project level operating context to align planners, indexers, and responders in a single cohesive workflow.

When to Use This AGENTS.md Template

You are building a hybrid search experience that combines vector similarity with keyword matching
You need a reproducible operating model for multi agent coordination
You want explicit handoff rules between planner, indexers, and responder agents
You require tool governance, source of truth, and memory rules
You want a simple, copyable template to bootstrap a project quickly

Copyable AGENTS.md Template

This is a copyable AGENTS.md block that sets the operating context for a hybrid search workflow. Copy it into your project root as AGENTS.md.

# AGENTS.md
Project role
Hybrid Search Platform Owner
Agent roster and responsibilities
Planner: creates a plan for how to satisfy a user query using both keyword and vector search
VectorIndexAgent: builds and updates vector embeddings in the vector store
KeywordIndexAgent: validates and queries the keyword index
FusionOrchestrator: coordinates agent work, handles memory and context propagation
ResponderAgent: composes final answer from ranker results
QAAgent: runs lightweight validations
Supervisor: oversees workflow, enforces rules, triggers human review

Handoff rules between agents
Planner to FusionOrchestrator logs plan and context
FusionOrchestrator distributes tasks to VectorIndexAgent and KeywordIndexAgent
ResponderAgent receives final results or ranked candidates from indexers for final assembly

Context memory and source of truth
Memory is stored in a centralized context store with last updated timestamp
All data sources are declared in a data map and source-of-truth

Tool access and permission rules
Access to vector store, keyword index, search API endpoints, and data warehouse is restricted by role
Secrets are never embedded in prompts

Architecture rules
Stateless planner, idempotent indexers, centralized orchestrator state
All changes go through approved pipelines

File structure rules
/agents
  /planner
  /vector-index
  /keyword-index
  /fusion-orchestrator
  /responder
  /qa
/memory
/tools
/configs
/docs

Data API and integration rules
Use standard JSON over HTTP
Schema validated input and output
Audit logs for each step

Validation rules
Unit tests for each agent
Integration tests for end to end flow
Contract tests for data formats
Manual review for new data sources

Security rules
Secrets in vault with rotation
Least privilege access
Audit and alerting on failures

Testing rules
Unit, integration, end to end
Staging environment before production

Deployment rules
CI pipeline gates
Blue green or canary deployments for critical endpoints

Human review and escalation rules
If an agent fails, retry with backoff
Fallback to keyword only path if vector path fails
Rollback to last good state

Failure handling and rollback rules
If an agent fails, retry with backoff
Fallback to keyword only path if vector path fails
Rollback to last good state

Things Agents must not do
Do not bypass governance gates
Do not leak secrets in prompts or logs
Do not perform destructive changes without approval
Do not drift from source of truth or context

Recommended Agent Operating Model

The planner defines a hybrid path that leverages both vector and keyword search. The vector indexer and keyword indexer operate in parallel under the Fusion Orchestrator. The responder assembles the final answer and triggers human review when needed. Escalation paths ensure human input for ambiguous results.

Recommended Project Structure

project/
  hybrid-search/
    agents/
      planner/
      vector-index/
      keyword-index/
      fusion-orchestrator/
      responder/
      qa/
    memory/
    tools/
    configs/
    docs/

Core Operating Principles

Single source of truth for memory and data provenance
Clear agent responsibility with explicit handoffs
Deterministic planning and idempotent actions
Observability and traceability for all steps
Fail safe with human review when confidence is low

Agent Handoff and Collaboration Rules

Planner to fusion orchestrator handoff with plan and context. Fusion orchestrator delegates to vector index and keyword index, then to responder. The QA agent validates results before delivery to the user, with escalation to human review if needed.

Tool Governance and Permission Rules

Access to search endpoints, vector store, and data sources follows least privilege. All tool usage is auditable and subject to approvals for production changes.

Code Construction Rules

Follow clean code standards. Validate all inputs. Avoid hard coded secrets. Use typed interfaces and contract tests.

Security and Production Rules

Secrets in vault, encryption in transit and at rest. Deploy changes via approved pipelines and with monitoring.

Testing Checklist

Unit tests for each agent
Integration tests for end to end pathway
Performance tests for latency in hybrid search
Security and dependency checks
Manual sanity tests in staging

Common Mistakes to Avoid

Skipping memory and source of truth management
Uncontrolled handoffs causing context drift
Hard coding secrets or credentials
Assuming experiments can be deployed without review

FAQ

What is this AGENTS.md Template for Hybrid Search Architecture?

This AGENTS.md template describes how to govern a hybrid search workflow with AI coding agents. It details roles, handoffs, tool governance, and escalation rules for reliable multi agent orchestration.

How does multi agent orchestration work in this template?

The template defines a Fusion Orchestrator that coordinates planner, vector indexer, and keyword indexer, with a responder for final assembly and human review when needed.

Who should use this AGENTS.md Template?

Engineering teams building hybrid search experiences that combine vector and keyword search and require repeatable operating models.

What are the security and production considerations?

Use vault secrets, enforce least privilege, require approvals for production changes, and validate changes through tests and human review.

How are failures handled and rolled back?

Failures trigger retries with backoff, fallback paths to keyword search, and escalation to human review with an audit trail.

Target User

Use Cases