SEOOptimizerAgent

AI-powered YouTube SEO optimization agent

Overview

The SEOOptimizerAgent optimizes video metadata for maximum YouTube discoverability. It generates optimized titles, descriptions, tags, hashtags, chapters, and calculates comprehensive SEO scores.

Constructor

db · Database · required

Database instance for keyword history and SEO data

credentials · Credentials · required

Credentials manager for external services

const { SEOOptimizerAgent } = require('./agents/seo-optimizer-agent');

const agent = new SEOOptimizerAgent(db, credentials);

Properties

keywordDatabase · Map

Historical keyword performance data

logger · Logger

Logger instance for tracking optimization

Methods

initialize()

Initializes the agent and loads keyword history.

return · Promise<boolean>

Returns true when initialization is complete

await agent.initialize();
// Loads keyword performance history for optimization

optimize(script, strategy)

Generates complete SEO optimization for a video.

script · Object · required

Video script object

strategy · Object · required

Content strategy object

return · Promise<Object>

Complete SEO data object

seoData.title · string

Optimized title (60-100 characters)

seoData.description · string

Comprehensive description (up to 5000 characters, first 125 optimized)

seoData.tags · Array<string>

Prioritized tags (max 500 characters total)

seoData.hashtags · Array<string>

15 relevant hashtags

seoData.chapters · Array<Object>

Video chapters with timestamps

seoData.endScreen · Object

End screen strategy

seoData.seoScore · number

Overall SEO score (0-100)

seoData.metadata · Object

Additional metadata (keywords, category, language)

const seoData = await agent.optimize(script, strategy);

console.log(seoData);
// {
//   title: 'Ultimate JavaScript Tutorial - Master JS in 2026',
//   description: 'JavaScript Tutorial - In this video, you\'ll discover...',
//   tags: ['javascript', 'tutorial', 'programming', 'how to javascript', ...],
//   hashtags: ['#JavaScript', '#Tutorial', '#Programming', ...],
//   chapters: [
//     { time: '00:00', title: 'Introduction', seconds: 0 },
//     { time: '00:20', title: 'The Challenge', seconds: 20 },
//     ...
//   ],
//   endScreen: { elements: [...], startTime: -20, template: 'standard' },
//   seoScore: 87,
//   metadata: {
//     primaryKeyword: 'javascript',
//     secondaryKeywords: ['tutorial', 'programming', 'coding', 'learn'],
//     targetLength: '10-15 minutes',
//     language: 'en',
//     category: 28
//   },
//   createdAt: '2026-03-05T10:00:00.000Z'
// }

optimizeTitle(originalTitle, strategy)

Optimizes video title for searchability and CTR.

originalTitle · string · required

Original title from script

strategy · Object · required

Content strategy

return · Promise<string>

Optimized title (max 100 characters)

const optimized = await agent.optimizeTitle(
  'JavaScript Tutorial',
  { keywords: ['javascript', 'programming'], contentType: 'Tutorial' }
);
// 'Ultimate JavaScript Tutorial (2026) - Programming'

// Optimization includes:
// - Power words (Ultimate, Complete, Essential, etc.)
// - Current year if under 70 characters
// - Primary keyword inclusion
// - Proper title case formatting
// - Length optimization (60-70 characters ideal)

generateDescription(script, strategy)

Generates comprehensive, SEO-optimized video description.

script · Object · required

Video script object

strategy · Object · required

Content strategy

return · Promise<string>

Full description (up to 5000 characters)

const description = await agent.generateDescription(script, strategy);

// Description includes:
// - Hook (first 125 characters - shown in search)
// - What you'll learn section
// - Timestamps/chapters
// - About this video (keyword-rich paragraph)
// - Useful links (channel, website, social)
// - Related videos
// - Tools & resources (for tutorials)
// - Business inquiries
// - Hashtags
// - Disclaimer
// - Copyright and music credits

generateTags(script, strategy)

Generates and prioritizes video tags.

script · Object · required

Video script

strategy · Object · required

Content strategy

return · Promise<Array<string>>

Prioritized tags (max 500 characters total)

const tags = await agent.generateTags(script, strategy);

// Tag sources:
// - Primary keywords from strategy
// - Topic variations (with spaces, without, with underscores)
// - Content type tags (tutorial, how to, guide, etc.)
// - Year tags (2026, JavaScript 2026)
// - Niche-specific tags (tech, gaming, education, etc.)
// - Long-tail keywords (how to javascript, javascript for beginners)
// - Channel branding tags

console.log(tags);
// ['javascript', 'tutorial', 'how to', 'programming', '2026', 
//  'javascript 2026', 'javascript tutorial', 'learn javascript', ...]

generateHashtags(strategy)

Generates relevant hashtags for video.

strategy · Object · required

Content strategy

return · Promise<Array<string>>

15 relevant hashtags

const hashtags = await agent.generateHashtags(strategy);

// Includes:
// - Primary topic hashtag (#JavaScript)
// - Content type hashtag (#Tutorial)
// - Trending hashtags (#YouTube, #Subscribe, #Trending)
// - Niche hashtags (#Tech, #Programming)
// - Year hashtag (#2026)

console.log(hashtags);
// ['#JavaScript', '#Tutorial', '#YouTube', '#Tech', '#Programming', 
//  '#Subscribe', '#Video', '#2026', ...]

generateChapters(script)

Generates video chapters with timestamps.

script · Object · required

Video script with sections

return · Promise<Array<Object>>

Chapter objects with time, title, and seconds

const chapters = await agent.generateChapters(script);

console.log(chapters);
// [
//   { time: '00:00', title: 'Introduction', seconds: 0 },
//   { time: '00:20', title: 'The Challenge', seconds: 20 },
//   { time: '00:50', title: 'The Solution', seconds: 50 },
//   { time: '03:05', title: 'Live Demo', seconds: 185 },
//   { time: '05:05', title: 'Conclusion & Next Steps', seconds: 305 }
// ]

generateEndScreenStrategy()

Generates end screen element configuration.

return · Promise<Object>

End screen strategy with elements and timing

const endScreen = await agent.generateEndScreenStrategy();

console.log(endScreen);
// {
//   elements: [
//     { type: 'video', position: 'left', title: 'Recommended Video', duration: 20 },
//     { type: 'playlist', position: 'right', title: 'Watch More', duration: 20 },
//     { type: 'subscribe', position: 'center-bottom', duration: 20 }
//   ],
//   startTime: -20,  // 20 seconds before end
//   template: 'standard'
// }

calculateSEOScore(title, description, tags)

Calculates comprehensive SEO score.

title · string · required

Video title

description · string · required

Video description

tags · Array<string> · required

Video tags

return · Promise<number>

SEO score (0-100)

const score = await agent.calculateSEOScore(title, description, tags);

// Scoring breakdown:
// Title (30 points max):
//   - Optimal length 60-70 chars: 10 points
//   - Contains number: 5 points
//   - Proper capitalization: 5 points
//   - Current year: 5 points
//   - Power words (how, what, why, best): 5 points
//
// Description (40 points max):
//   - Length >= 200 chars: 10 points
//   - Length >= 500 chars: 10 points
//   - Contains TIMESTAMPS: 5 points
//   - Contains links: 5 points
//   - Well formatted (10+ lines): 5 points
//   - Primary keyword in first 125 chars: 5 points
//
// Tags (30 points max):
//   - 10+ tags: 10 points
//   - 15+ tags: 5 points
//   - Contains long-tail keywords: 5 points
//   - Within 500 char limit: 5 points
//   - No duplicates: 5 points

console.log('SEO Score:', score);
// 87

identifyNiche(strategy)

Identifies content niche from strategy.

strategy · Object · required

Content strategy

return · string

Niche category: technology, gaming, education, business, lifestyle, health, entertainment, or general

const niche = agent.identifyNiche({ topic: 'Python Programming Tutorial' });
// 'technology'

selectCategory(strategy)

Selects YouTube category ID.

strategy · Object · required

Content strategy

return · number

YouTube category ID

const categoryId = agent.selectCategory(strategy);
// 28 for technology/science
// 20 for gaming
// 27 for education
// 22 for people & blogs (default)

calculateOptimalLength(contentType)

Calculates optimal video length for content type.

contentType · string · required

Content type (Tutorial, Explainer, Review, List, Story)

return · string

Recommended duration range

const length = agent.calculateOptimalLength('Tutorial');
// '10-15 minutes'

// Optimal lengths:
// Tutorial: 10-15 minutes
// Explainer: 5-10 minutes
// Review: 8-12 minutes
// List: 8-15 minutes
// Story: 10-20 minutes

Usage Example

const { SEOOptimizerAgent } = require('./agents/seo-optimizer-agent');

const agent = new SEOOptimizerAgent(db, credentials);
await agent.initialize();

const script = {
  title: 'JavaScript Promises Tutorial',
  mainContent: {
    sections: [
      { title: 'The Challenge', duration: 30 },
      { title: 'The Solution', duration: 90 },
      { title: 'Live Demo', duration: 120 }
    ]
  }
};

const strategy = {
  topic: 'JavaScript Promises',
  contentType: 'Tutorial',
  keywords: ['javascript', 'promises', 'async', 'tutorial'],
  targetAudience: 'Developers'
};

const seoData = await agent.optimize(script, strategy);

console.log('Optimized Title:', seoData.title);
console.log('SEO Score:', seoData.seoScore, '/100');
console.log('Tags:', seoData.tags.join(', '));
console.log('Chapters:', seoData.chapters.length);

// Use in video upload
const uploadMetadata = {
  title: seoData.title,
  description: seoData.description,
  tags: seoData.tags,
  categoryId: seoData.metadata.category.toString()
};

Tag Categories

The agent generates tags from multiple sources:

Primary Keywords

Direct keywords from content strategy (highest priority)

Topic Variations

Topic with spaces, without spaces, with underscores

Content Type Tags

Tutorial: how to, tutorial, guide, step by step, learn Explainer: explained, what is, understanding Review: review, comparison, vs, best, top List: top 10, best, list, countdown

Long-Tail Keywords

Multi-word phrases (e.g., “how to javascript”, “javascript for beginners”)

Niche Tags

Technology: tech, innovation, future tech Gaming: gaming, gameplay, walkthrough Education: educational, learning, study tips

Temporal Tags

Current year and “topic year” combinations

Best Practices

Optimize First 125 Characters

The first 125 characters of the description appear in search results. Include primary keywords and a compelling hook.

Use All 500 Tag Characters

The agent prioritizes tags to use the full 500-character limit. Mix broad and long-tail keywords.

Add Timestamps

Chapters improve user experience and SEO. The agent automatically generates them from script sections.

Target 80+ SEO Score

Scores above 80 indicate well-optimized content. Below 60 needs improvement in title, description, or tags.

Update Keywords Database

Store performance data for keywords to improve future optimization recommendations.

Environment Variables

WEBSITE_URL · string

Your website URL for description links

SOCIAL_LINKS · string

Social media links for description

BUSINESS_EMAIL · string

Business inquiry email for description

CHANNEL_NAME · string

Channel name for branding tags