Google Pub/Sub AGENTS.md Template

Overview

Direct answer: This AGENTS.md template encodes a Google Pub/Sub based multi-agent orchestration pattern with explicit roles, handoffs, memory model, and governance. It provides a project-level operating context for single-agent and multi-agent work in an event-driven Pub/Sub architecture.

The template documents the roles, responsibilities, data flow, and control points needed to run a compliant, observable, and secure Pub/Sub workflow with AI coding agents. It describes how agents interact, how context is preserved, and how handoffs are governed so the architecture remains auditable and scalable.

When to Use This AGENTS.md Template

• When you implement an event-driven pipeline using Google Pub/Sub and need explicit agent roles for planning, publishing, subscribing, and orchestrating tasks.
• When you require durable memory of task context, source-of-truth management, and controlled handoffs between agents.
• When governance, security, testing, and deployment rules must be codified in a single, copyable document.

Copyable AGENTS.md Template

Copy the block below into your AGENTS.md at the project root and customize for your Google Pub/Sub workflow.

# AGENTS.md

Project role: Google Pub/Sub event-driven pipeline with multi-agent orchestration. Enables AI coding agents to plan, publish, validate, enrich, and review messages across Pub/Sub topics. Orchestrator enforces handoffs and maintains a durable task context.

Agent roster and responsibilities:
- Planner: designs workflow, topics, message schemas, and handoff points.
- PublisherAgent: publishes messages to Pub/Sub with correct attributes and correlation identifiers.
- SubscriberAgent: consumes messages, validates structure, and forwards for processing.
- OrchestratorAgent: coordinates handoffs, enforces memory, and triggers subsequent steps.
- ResearcherAgent: sources data enrichment ideas, validates external data quality, monitors drift.
- ReviewerAgent: performs policy and quality checks before production, approves or requests changes.
- TesterAgent: runs end-to-end tests and simulates failure scenarios.

Supervisor or orchestrator behavior:
- Maintain a per-task memory store and a single source of truth for context and outputs.
- Enforce idempotency and deduplication via correlation IDs.
- Log all handoffs, decisions, and failures to a central audit trail.
- Escalate persistent failures after configured retries to human review.

Handoff rules:
- Planner -> PublisherAgent: provide topic, message schema, and keys when plan is approved.
- PublisherAgent -> SubscriberAgent: include publish result and message metadata after publish.
- SubscriberAgent -> OrchestratorAgent: on validation success, trigger next step.
- OrchestratorAgent -> ResearcherAgent/ReviewerAgent: request enrichment or policy checks as needed.
- ResearcherAgent/ReviewerAgent -> OrchestratorAgent: return enriched data or clearance.
- OrchestratorAgent -> TesterAgent: deploy to test and validate in staging before production.

Context, memory, and source-of-truth rules:
- All task context lives in a central memory store with a unique task_id.
- Pub/Sub message payloads include id, correlation_id, event_type, payload, timestamp.
- The memory store serves as the canonical source of truth for task state and outputs.
- Avoid duplicative data stores; use topic versioning to evolve schemas.

Tool access and permission rules:
- Agents may publish to designated topics only; read permissions limited to their targets.
- Secrets fetched at runtime from a managed secret store; never hard-coded.
- Use service accounts with least privilege; rotate credentials regularly.
- Production data access is restricted to approved APIs and gateways.

Architecture rules:
- Event-driven, decoupled components with strict boundaries between planning, publishing, and processing.
- Agents are stateless; state is stored in the memory store or Pub/Sub attributes.
- Validate all messages against a schema prior to processing.

File structure rules:
- Keep a single repository with explicit folders for agents, memory, configs, pipelines, tests, and deploy.
- Do not introduce duplicate pipelines or unrelated tech stacks.

Data, API, or integration rules:
- Pub/Sub messages are JSON with fields: id, correlation_id, event_type, payload, timestamp.
- Use REST or gRPC endpoints only through approved APIs; authenticate every call.

Validation rules:
- Validate message schemas before any processing step.
- Ensure idempotent operations and proper error handling.

Security rules:
- Do not bypass IAM; restrict to required topics and APIs.
- Rotate credentials and monitor secret access.
- Encrypt sensitive data in transit and at rest; enable audit logs.

Testing rules:
- Unit tests for message validation and helper utilities.
- Integration tests with Pub/Sub emulator or staging environment.
- End-to-end tests that simulate real events and replays.

Deployment rules:
- CI/CD gates require all tests and security checks to pass.
- Deploy to staging first; use feature flags or canary releases for production.

Human review and escalation rules:
- Escalate policy or safety violations to a human reviewer.
- Critical failures trigger incident response and post-incident reviews.

Failure handling and rollback rules:
- Use Pub/Sub Dead Letter Topics for failed messages.
- If failure persists, rollback to a known-good revision and reprocess.

Things Agents must not do:
- Do not publish to undeclared topics or bypass the orchestrator.
- Do not modify memory or source-of-truth without approval.
- Do not operate in production without proper monitoring and alerts.

Recommended Agent Operating Model

The model defines clear roles, decision boundaries, and escalation paths for Google Pub/Sub based multi-agent workflows. Planner designs the flow; Orchestrator coordinates handoffs; Publishers and Subscribers execute message exchange; Researchers, Reviewers, and Testers provide enrichment, quality checks, and validation. Escalation paths route issues to human review when policy or safety constraints require oversight.

Recommended Project Structure

The following directory tree is tailored for a Google Pub/Sub architecture and AGENTS.md driven workflow.

ai-pubsub-agents/
├── agents/
│   ├── planner/
│   │   └── README.md
│   ├── publisher/
│   │   └── README.md
│   ├── subscriber/
│   │   └── README.md
│   ├── orchestrator/
│   │   └── README.md
│   ├── researcher/
│   │   └── README.md
│   ├── reviewer/
│   │   └── README.md
│   └── tester/
│       └── README.md
├── memory/
│   └── tasks/
├── configs/
│   ├── topics.yaml
│   └── schemas.json
├── pipelines/
│   └── pubsub_pipeline.yaml
├── tests/
│   ├── unit/
│   └── integration/
└── deploy/
    └── deploy.sh

Core Operating Principles

• Clear ownership and explicit responsibilities for each agent.
• Strict memory model with a single source of truth per task.
• Deterministic, auditable handoffs between agents.
• End-to-end observability, including logs, metrics, and tracing.
• Security by default with least privilege access.

Agent Handoff and Collaboration Rules

• Planner communicates a concrete plan to the PublisherAgent and includes topic details, message schema, and keys.
• PublisherAgent validates publish success and hands off to SubscriberAgent with metadata.
• SubscriberAgent validates messages and triggers the OrchestratorAgent for next steps.
• OrchestratorAgent coordinates enrichment and policy checks via ResearcherAgent and ReviewerAgent.
• ResearcherAgent and ReviewerAgent return results to OrchestratorAgent to proceed or halt.
• OrchestratorAgent triggers TesterAgent before production deployment.

Tool Governance and Permission Rules

• Publish/subscription permissions limited to designated topics.
• Secrets accessed from a centralized secret store at runtime.
• Service accounts with least privilege; no hard-coded credentials.
• All tool usage requires authorization gates and audit logging.

Code Construction Rules

• Use Pub/Sub client libraries and respect regional endpoints.
• Message schemas must be enforced and versioned; avoid schema drift.
• Idempotent operations and deterministic side effects only.

Security and Production Rules

• IAM, KMS encryption, and audit logging enabled for all agents.
• Secrets rotation every 90 days; monitor unusual access patterns.
• Production changes require governance approval and staged rollout.

Testing Checklist

• Unit tests for message validation and agent logic.
• Integration tests with Pub/Sub emulator or sandbox projects.
• End-to-end tests simulating normal flow and failure scenarios.

Common Mistakes to Avoid

• Skipping memory or source-of-truth rules leading to context drift.
• Bypassing orchestration for quick hacks or direct topic writes.
• Overcomplicating handoffs or failing to log decisions for audits.

FAQ

What is this AGENTS.md Template for a Google Pub/Sub architecture?

This AGENTS.md Template provides a precise operating manual for a Pub/Sub driven multi-agent workflow, including roles, handoffs, and governance patterns.

How do agents hand off tasks in the Pub/Sub workflow?