AGENTS.md Template: Pinecone Production Architecture

Overview

AGENTS.md template for Pinecone production architecture describes how AI coding agents operate within a Pinecone-backed vector search environment, covering both single-agent and multi-agent orchestration patterns. It provides a declarative operating manual that teams can paste into an AGENTS.md file to establish a single source of truth for roles, handoffs, memory, and tool governance.

Direct answer: This template defines concrete roles, interaction rules, and governance to run Pinecone-based AI agent workflows with clear handoffs, versioned steps, and auditable decisions.

When to Use This AGENTS.md Template

• When building a production-grade Pinecone vector search pipeline that relies on AI coding agents.
• When you need strong multi-agent orchestration, explicit handoffs, and a single source of truth.
• When enforcing tool governance, secrets handling, and security controls across data ingestion, embedding, and indexing.
• When you require repeatable deployment and human review checkpoints for Pinecone operations.

Copyable AGENTS.md Template

Copy the block below into your AGENTS.md at project root.

# AGENTS.md

Project: Pinecone production architecture for AI coding agents

Agent roster and responsibilities:
- Planner: designs objectives and tasks; decomposes features into actionable steps for Pinecone-based indexing and retrieval workflows.
- Orchestrator (Supervisor): coordinates all agents, maintains memory, and enforces policy; triggers downstream tasks and handles escalations.
- Ingestor: validates and ingests data sources into the pipeline; ensures data conforms to embedding requirements.
- EmbeddingAgent: generates embeddings for text/doc data via the chosen model; publishes vectors to Pinecone.
- PineconeIndexAgent: manages Pinecone index lifecycle (create, update, upsert, delete) and namespace management.
- Implementer: implements tasks, writes code, updates pipelines or notebooks.
- Tester: runs unit/integration tests on components; validates output quality and consistency.
- Reviewer: reviews changes, approves deployments, and ensures security/compliance checks pass.
- Domain Specialist: provides Pinecone-specific guidance, tuning, and governance for production architecture.

Supervisor or orchestrator behavior:
- Maintain an up-to-date plan; orchestrate tasks according to acceptance criteria; surface blockers to human review when needed; log decisions with provenance.
- Update memory with outcomes, artifacts, and evidence; propagate context to downstream agents on handoffs.

Handoff rules between agents:
- Planner -> Orchestrator: produce plan with tasks, owners, and success criteria.
- Orchestrator -> Ingestor/EmbeddingAgent/PineconeIndexAgent/Implementer: assign tasks with context and success criteria.
- Implementer -> Tester: pass artifacts, outputs, and test results.
- Tester -> Reviewer: attach test results and request approval.
- Reviewer -> Orchestrator: approve or request revisions; if approved, trigger deployment sequence.

Context, memory, and source-of-truth rules:
- Memory: store in memory.json and a persistent log; include provenance, timestamps, and task owners.
- Source-of-truth: Pinecone index metadata, input data sources, code repository, and secret store; all agents must read from memory and sources before acting.

Tool access and permission rules:
- Pinecone API: allowed for index management and vector operations.
- Secrets: read-only from a secret manager; never log secrets.
- External services: permitted only via whitelisted endpoints; use adapters when possible.
- No direct shell access to production systems; orchestrator acts as single control plane for changes.

Architecture rules:
- Central orchestrator coordinates decoupled services; tasks are idempotent and replayable.
- All changes are auditable; outputs are versioned; vector data and metadata are consistent across steps.

File structure rules:
- Keep a minimal, coherent folder layout focused on the Pinecone workflow.
- Avoid irrelevant folders; maintain a single source of truth per component.

Data, API, or integration rules:
- Data: ensure consistent embedding dimensions; namespace management in Pinecone.
- API: standard timeouts, retry policies, and error handling.
- Integration: clear adapters for data sources and embedding models.

Validation rules:
- Validate data shapes, embedding dimensions, and index health in Pinecone.
- End-to-end checks from ingestion to search results with expected accuracy.

Security rules:
- Enforce least privilege for all agents; rotate credentials; log access events.

Testing rules:
- Unit tests for each agent; integration tests for ingestion, embedding, and Pinecone indexing.
- End-to-end tests for search results and latency budgets.

Deployment rules:
- Use CI/CD with canary deployments; monitor latency, error rates, and index health; rollback on anomaly.

Human review and escalation rules:
- Any risk or failure beyond defined thresholds requires human review and approval before production deployment.

Failure handling and rollback rules:
- On failure, revert to last known-good state; roll back index changes; preserve audit logs for root cause analysis.

Things Agents must not do:
- Do not bypass approval gates; do not modify production data outside approved workflows; never log secrets; do not degrade embeddings or index health intentionally.

Recommended Agent Operating Model

The Pinecone production architecture AGENTS.md model assigns clear roles with decision boundaries and escalation paths. The Planner crafts the plan, the Orchestrator enforces flow and policy, and domain experts provide Pinecone-specific tuning. Handoffs require explicit context and memory updates to avoid drift. Escalations go to human reviewers when risk exceeds thresholds.

Recommended Project Structure

pinecone-arch/
  agents/
    planner/
    orchestrator/
    ingestor/
    embedding/
    pinecone-index/
    implementer/
    tester/
    reviewer/
    domain-specialist/
  services/
    data-ingest/
    embedding-service/
    pinecone/
  config/
  memory/
  tests/

Core Operating Principles

• Single source of truth for decisions, plans, and provenance.
• Idempotent tasks and auditable state changes.
• Explicit handoffs with memory and context in every transfer.
• Least privilege for all tool access and secrets handling.
• Continuous validation from ingestion through search results.

Agent Handoff and Collaboration Rules

Define clear collaboration points for planner, orchestrator, ingestor, embedding, index, tester, reviewer, and domain-specialist agents, including required inputs, outputs, and acceptance criteria at each handoff.

Tool Governance and Permission Rules

List permitted tools, required approvals, and credential handling protocols relevant to Pinecone operations and data sources.

Code Construction Rules

Provide concrete implementation constraints for indexing, embedding, data validation, and integration with Pinecone. Enforce deterministic builds, clear error handling, and traceable outputs.

Security and Production Rules

Address production-grade security, secret management, access controls, and compliance considerations for Pinecone workloads.

Testing Checklist

• Unit tests for each agent's functions.
• Integration tests for ingestion, embedding, and Pinecone indexing.
• End-to-end tests for search results and latency budgets.
• Canary deployment checks and rollback readiness.

Common Mistakes to Avoid

• Skipping memory updates during handoffs causing context drift.
• Bypassing approvals or secrets handling norms.
• Assuming Pinecone index health without periodic validation.
• Overfitting plan without traceable evidence in memory logs.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Use Case for Xero Reports and Business Performance Insights.

FAQ

What is the purpose of this AGENTS.md Template for Pinecone?

It provides a production-ready operating manual for how AI coding agents interact within a Pinecone-backed vector workflow and how multi-agent orchestration is governed.

Who should own the Pinecone index during production?

The PineconeIndexAgent under orchestrator oversight maintains and updates the index; human review is required for major changes.

How are agent handoffs enforced?

Handoffs require explicit context, memory updates, and acceptance criteria prior to task transfer; failures trigger escalation.

Where are secrets stored and how are they used?

Secrets live in a vault/secret manager; agents read them at runtime and never log secrets; do not hard-code credentials.

What happens on failure in production?

Failures trigger rollback to last known-good state, alert stakeholders, and rollback Pinecone changes if necessary.

How do you validate that the system is healthy?

Regular health checks for ingestion, embeddings, Pinecone index health, and search latency are validated through automated tests and dashboards.