Media Streaming Architecture AGENTS.md Template

Overview

Direct answer: This AGENTS.md template defines a media streaming agent workflow with clear roles, boundaries, and orchestration rules. It supports both single-agent operation and multi-agent orchestration for ingest, transcoding, packaging, delivery, and monitoring.

The template describes how specialized AI coding agents collaborate, how context is shared, and how supervision and handoffs are conducted. It provides a concrete, paste-ready operating context for a streaming pipeline project.

When to Use This AGENTS.md Template

When building a live or on-demand media streaming pipeline requiring automated orchestration across multiple agents.
When you need reproducible operating context that can be versioned with the repository.
When you require clear handoffs, source-of-truth, and audit-ability for media ingests, transcoding, packaging, and delivery.
When tool governance and security controls must be enforced by the orchestrator.
When you want a template that teams can paste into their repo and customize per deployment.

Copyable AGENTS.md Template

# AGENTS.md

Project role: Media Streaming Architecture Orchestrator (MSAO)
Agent roster and responsibilities:
  - IngestAgent: Ingests source feeds, validates manifests, stores raw assets in landing area.
  - TranscodeAgent: Transcodes to target formats/resolutions, preserves quality metrics, writes to artifacts store.
  - PackageAgent: Creates final manifests (HLS/DASH), audio/subs, captions, and packaging metadata.
  - DeliveryAgent: Publishes segments to CDN edge and purges caches as needed.
  - QualityAgent: Monitors QoE metrics, latency, dropped frames; triggers reprocessing if thresholds breached.
  - Orchestrator: Coordinates planning, memory sharing, handoffs, and audit logging.
  - MonitorAgent: Collects observability data and alerts on anomalies.
  - ResearchAgent/DomainSpecialist: Handles licensing, rights checks, and specialized metadata validation.

Supervisor or orchestrator behavior:
  - Maintains a durable memory store of state, artifacts, and decisions.
  - Plans next steps, assigns tasks, and enforces SLAs.
  - Enforces tool governance, secrets handling, and audit logging.

Handoff rules between agents:
  - Passing artifacts via a centralized store with immutable identifiers.
  - Orchestrator signals next workload; downstream agent validates inputs before processing.

Context, memory, and source-of-truth rules:
  - All decisions are derived from a single source of truth: artifact store and state DB.
  - Context is injected at start and persists across steps; memory is read/write with versioning.

Tool access and permission rules:
  - Agents can access only their designated services (ingest, transcoding, delivery, etc.).
  - Secrets are retrieved from a vault; ephemeral credentials are rotated per job.

Architecture rules:
  - Event-driven, idempotent processing; deterministic replays allowed.
  - Stateless workers; orchestrator holds the workflow state.

File structure rules:
  - Do not create irrelevant folders; mirror workflow stages under agents/{stage}/
  - Keep configuration in configs/ and manifests in artifacts/.

Data, API, or integration rules when relevant:
  - Use standardized media formats; metadata exchanged via JSON manifests.
  - APIs are RESTful where possible; use gRPC for internal services if available.

Validation rules:
  - Validate input manifests, segment integrity, and metrics before progressing.
  - Validate outputs against predefined thresholds before handoffs.

Security rules:
  - Never expose secret keys in logs or artifacts.
  - All external calls must go through approved endpoints with TLS.

Testing rules:
  - Unit tests for each agent; integration tests for end-to-end streaming pipelines.
  - Mock external services for deterministic tests.

Deployment rules:
  - CI/CD pipelines perform lint, tests, and a dry-run of orchestration changes.
  - Rollback to previous artifact if new deployment causes errors.

Human review and escalation rules:
  - Escalate anomalies to human reviewer if QoE thresholds are breached or if ingestion fails repeatedly.
  - All manual changes require a pull request with approval.

Failure handling and rollback rules:
  - On failure, revert to last successful manifest and re-run last good pipeline.
  - Capture rollback changes in audit logs.

Things Agents must not do:
  - Do not bypass the orchestrator or manipulate shared memory without logging.
  - Do not perform production changes without approval.
  - Do not ignore data integrity checks.

Recommended Agent Operating Model

Roles and decision boundaries: IngestAgent and TranscodeAgent are data-first workers; the Orchestrator holds the decision authority and enforces handoffs. DomainSpecialist provides licensing validation when required. The QualityAgent escalates on QoE breaches and requests human review when needed.

Recommended Project Structure

media-streaming-architecture/
  readme.md
  configs/
  artifacts/
  data/
  pipelines/
  agents/
    ingest/
    transcode/
    package/
    deliver/
    monitor/
    orchestrator/
    domain/
  tests/
  docs/

Core Operating Principles

Single source of truth via centralized memory/artifact store.
Idempotent, auditable actions with explicit handoffs.
Principle of least privilege for tool access.
Deterministic replays and clear failure handling.
Human review when thresholds or policy constraints are breached.

Agent Handoff and Collaboration Rules

Planner/Orchestrator computes plan, Implementer executes tasks, Reviewer validates outputs, Tester verifies end-to-end paths, Researcher/Domain Specialist confirms metadata and licensing, Domain Specialist handles rights flows as needed. Handoffs require artifact-based data transfer and state updates in the memory store.

Tool Governance and Permission Rules

Actions must pass through the orchestrator for approval gates.
Secrets must be retrieved from a vault; never stored in logs or code.
APIs require scoped tokens and TLS; production endpoints require approval.
Artifacts and logs must be immutable and time-stamped.

Code Construction Rules

Write modular, testable agents with explicit interfaces.
Ensure idempotency and deterministic outputs for each stage.
Do not hard-code production endpoints; use config-driven values.

Security and Production Rules

Restrict network egress; use private endpoints where possible.
Encrypt data at rest and in transit; rotate keys regularly.
Audit trails for all changes; implement anomaly detection on pipeline state.

Testing Checklist

Unit tests for each agent.
Integration tests covering end-to-end streaming pipelines.
Load tests simulating peak concurrent ingest and delivery.
Smoke tests in staging before production deploy.

Common Mistakes to Avoid

Skipping formal handoff contracts between agents.
Over-sharing state or secrets across agents.
Undocumented changes that drift from the intended orchestration pattern.
Ignoring QoE metrics when making decisions.

FAQ

What is the purpose of this AGENTS.md Template for media streaming architecture?

To codify roles, handoffs, and governance for a reproducible multi-agent streaming pipeline from ingest to delivery.

Who should use this AGENTS.md Template?

Platform engineers, streaming architects, and AI coding agents coordinating ingest, transcoding, packaging, delivery, and monitoring.

How are agent handoffs defined in multi-agent orchestration?

Handoffs pass immutable artifacts through a central store; the orchestrator triggers the next agent and validates inputs before processing.

What are the memory/context and source-of-truth rules?

Context persists in a durable memory store tied to artifact IDs; all decisions reference the single source of truth in the memory/artifact system.

How do you handle security, testing, and deployment?

Secrets are vault-backed, tests cover unit/integration, and deployments go through CI/CD with rollback on failure.

Target User

Use Cases