Media Upload Architecture AGENTS.md Template

Overview

AGENTS.md template for media upload architecture defines a copyable operating manual that governs the end-to-end media ingestion pipeline using AI coding agents. It supports both single-agent execution and multi-agent orchestration with explicit handoffs, tool governance, and human review where required. This template ensures a predictable, auditable workflow for ingest, metadata extraction, transcoding, quality checks, and publishing.

Direct answer: This page provides a complete, copyable AGENTS.md template that teams can paste into a project folder to establish a standard operating context for media upload workflows involving multiple agents and a supervisory orchestrator.

When to Use This AGENTS.md Template

• Designing a media upload pipeline that requires consistent metadata and format handling across formats and delivery targets.
• Coordinating multiple agents (ingest, metadata, transcode, quality, publish) with clear handoffs and escalation rules.
• Establishing a single source of truth for media manifests, metadata, and statuses that teams and tools rely on.
• Implementing tool governance, secret management, and permission boundaries across storage, transcoding, and CDN services.
• Enforcing reproducible deployments and auditability for media assets in production.

Copyable AGENTS.md Template

# AGENTS.md

Project role: MediaOps Lead; orchestrator and guardrails for the media upload pipeline.

Agent roster and responsibilities:
- IngestAgent: validate file format, verify checksum, write initial media manifest, trigger metadata extraction.
- MetadataAgent: extract and normalize metadata (title, credits, licensing), attach tags, populate media manifest.
- TranscodeAgent: produce target formats/resolutions, update manifest with outputs and checksums.
- QualityAgent: run automated checks (format, bitrate, frame rate), flag anomalies, request reprocess if needed.
- PublishAgent: publish final assets to CDN/asset library, update accessibility and rights metadata.
- GovernanceAgent: enforce access rights, approvals, and compliance gates; log decisions for audits.
- Orchestrator: coordinates agent handoffs, monitors state, retries on transient failures, escalates on blocking issues.

Supervisor or orchestrator behavior:
- Maintain a single source of truth (MediaManifest) and a timeline of state transitions.
- Trigger handoffs based on deterministic conditions; pause on blocking failures and route to human review if needed.
- Provide progress visibility and retry policies; ensure idempotent replays when re-run is safe.

Handoff rules between agents:
- IngestAgent → MetadataAgent once manifest is created and initial validation passes.
- MetadataAgent → TranscodeAgent after metadata is attached and manifest is normalized.
- TranscodeAgent → QualityAgent after outputs and checks are recorded in manifest.
- QualityAgent → PublishAgent once quality checks pass; any failure goes to Orchestrator for remediation.
- Any agent can escalate to GovernanceAgent if policy or permission issues are detected.

Context, memory, and source-of-truth rules:
- Use a central MediaManifest as the authoritative memory for media assets, formats, metadata, and status.
- All agents must read/write to the manifest; do not maintain independent local caches that drift from the manifest.
- Source of truth for file integrity and provenance is the original ingest payload and subsequent transforms.

Tool access and permission rules:
- Ingest: read storage bucket, verify checksum, write manifest.
- Metadata: call metadata extraction services; write tags to manifest.
- Transcode: call encoding/transcoding APIs; store outputs and checksums in manifest.
- Quality: access assets and transcoded outputs; write QC results to manifest.
- Publish: publish to CDN/asset library; update published status in manifest.
- Governance: approve/deploy changes; manage secrets with vaults; require dual control for production actions.

Architecture rules:
- Ensure idempotent operations; replays should be safe.
- Maintain strict versioning for assets and formats.
- Prefer stateless agents with persistent Memory (MediaManifest) in a durable store.
- All communications secured with TLS; rotate credentials regularly.

File structure rules:
- artifacts/ingest/
- artifacts/metadata/
- artifacts/transcode/
- artifacts/quality/
- artifacts/publish/
- orchestrator/
- configs/
- docs/

Data, API, or integration rules when relevant:
- MediaManifest is the central JSON/JSONL document containing asset metadata, formats, state, and lineage.
- Use standardized REST/GraphQL endpoints for service calls; expose idempotent operations only.

Validation rules:
- Each state transition must be validated against the manifest schema.
- On failure, capture error context and retry with backoff; surface to human review if unrecoverable.

Security rules:
- Secrets stored in vault; do not hard-code credentials.
- Access controls limited by role; least privilege principle enforced.

Testing rules:
- Unit tests for each agent, integration tests for end-to-end flow, and end-to-end smoke tests in CI.
- Include rollback tests for failed replays.

Deployment rules:
- Agent code must be rolled out via feature-flag controlled releases; canary tests before production.
- Run automated data validation after deploys.

Human review and escalation rules:
- Escalate any policy or rights violation to GovernanceAgent.
- Require human review for non-standard media assets or disputed metadata.

Failure handling and rollback rules:
- If any critical step fails, halt the pipeline, revert to prior manifest state when possible, and notify stakeholders.

Things Agents must not do:
- Do not bypass approvals or governance gates.
- Do not mutate manifest without logging a trace.
- Do not use production credentials in non-secure contexts.
- Do not perform destructive edits without a rollback plan.

Recommended Agent Operating Model

Roles, responsibilities, decision boundaries, and escalation paths are defined to enable safe, auditable multi-agent orchestration. In this model, the Orchestrator acts as the planner and coordinator, while each specialized agent performs a bounded set of tasks with explicit handoffs and validation checks. Escalation paths ensure policy compliance and human oversight when required.

Recommended Project Structure

media-upload-architecture/
├── agents/
│   ├── ingest/
│   ├── metadata/
│   ├── transcode/
│   ├── quality-check/
│   ├── publish/
│   └── governance/
├── orchestrator/
├── configs/
├── workflows/
├── tests/
└── docs/

Core Operating Principles

• Single source of truth: MediaManifest governs state and history.
• Idempotent by design: replays must be safe and deterministic.
• Explicit handoffs: every transition has a defined precondition and postcondition.
• Auditability: every action is logged with user/context, time, and rationale.
• Security by default: least privilege, secret rotation, and encrypted data at rest and in transit.

Agent Handoff and Collaboration Rules

Planner, implementer, reviewer, tester, researcher, and domain specialist agents coordinate via the MediaManifest and orchestrator signals. Key rules:

• Planner defines the sequence and preconditions for each handoff.
• Implementers execute tasks within their domain and report results to the manifest.
• Reviewers validate correctness before moving to the next stage.
• Testers run end-to-end checks and regression tests; failures revert state and trigger remediation.
• Researchers provide metadata schemes and reference data; domain specialists resolve edge cases.

Tool Governance and Permission Rules

Commands, file edits, API calls, and secret usage must follow governance gates:

• Only vetted tools with scoped permissions may be invoked by agents.
• Secrets are accessed via a vault and never embedded in code or manifests.
• Production actions require governance approvals and audit logging.
• All external calls must be authenticated and rate-limited.

Code Construction Rules

Concrete constraints for this workflow:

• All media manifests and metadata must be validated against a schema before state transitions.
• Transcoding must be deterministic; outputs are tagged with format/resolution metadata.
• API interactions must be idempotent and retry-safe with exponential backoff.
• Code changes must include tests, documentation, and rollbacks.

Security and Production Rules

Security considerations:

• Encrypt media at rest and in transit; use signed URLs for temporary access.
• Enforce access controls per role; deny operations outside scope.
• Monitor for anomalous activity and trigger incident workflows.

Testing Checklist

• Unit tests for each agent; integration tests for end-to-end flow.
• End-to-end smoke tests in CI with sample media assets.
• Performance checks for transcoding and delivery latency.
• Rollback tests for failed transitions.

Common Mistakes to Avoid

• Overloading agents with unrelated responsibilities.
• Skipping human review for critical assets or metadata discrepancies.
• Ignoring manifest drift between steps or unsynced states.
• Hard-coding credentials or bypassing governance gates.

Related implementation resources: AI Use Case for Sales Pipeline Reviews and Deal Risk Scoring and AI Agent Use Case for Refineries Using Pipeline Acoustic Monitoring Arrays To Isolate Micro-Fissures Before Leaks Occur.

FAQ

What is this AGENTS.md Template for media upload architecture?

It provides a copyable operating manual so teams can implement consistent, auditable media upload pipelines with multi-agent orchestration.

How are agent handoffs defined in this template?

Handoffs occur when preconditions are met; the orchestrator triggers the next agent and updates the manifest with outcome details.

What constitutes the source of truth in this workflow?

The MediaManifest is the authoritative record for asset metadata, status, provenance, and lineage.

How is security enforced in the media upload architecture?

Access is least-privilege, secrets are vault-managed, and production actions require governance approvals with audit logs.

How do you handle failures and rollback?

Failures trigger replays or backouts to the previous stable manifest state, with escalation to human review when needed.