Blog Agent Reference: C# Implementation vs TypeScript

var mainAgent = new BlogAgent(config, imageGenService, imageUtilities, promptBuilder, cacheManager, loggerFactory);
var result = await mainAgent.RunBlogPipelineAsync(request, siteUrl, cancellationToken);

BlogAgent.RunBlogPipelineAsync(request, siteUrl)
  │
  ├─ 1. GetCachedSitemapLinksAsync(siteUrl, tenantId)
  │      Cache key: "sitemap:links:{tenantId}" (24-hour Redis TTL)
  │      On miss: SitemapHelper.FetchSitemapUrlsForCacheAsync(siteUrl)
  │      Caps at 50 URLs (random sample) to control prompt size
  │
  ├─ 2. BuildBlogWriterInstructionsAsync(sitemapUrls)
  │      Loads BlogWriterAgentInstructions.txt
  │      Replaces [[existing_links]] with CSV of URL,Title
  │
  ├─ 3. BuildBlogWriterPromptAsync(request)
  │      Loads BlogWriterAgentPrompt.txt + BlogBestPracticesPrompt.txt + ImageCreationPrompt.txt
  │      Replaces all {{placeholders}} with sanitized request fields
  │
  ├─ 4. BuildBlogReviewerInstructionsAsync(blogContext, sitemapUrls)
  │      Loads BlogReviewerAgentInstructions.txt
  │      Replaces {{BusinessContext}} and [[existing_links]]
  │
  ├─ 5. Instantiate agents: BlogWriterAgent, BlogReviewAgent, BlogImageGenerationAgent
  │
  └─ 6. BlogAgentOrchestrator.RunAsync(blogWriterPrompt, description)
         │
         ├─ Stage 1: BlogWriterAgent.CreateBlogPostAsync(prompt)
         │            → BlogResponse (JSON)
         │
         ├─ Stage 2: Review-revision loop (max 3 iterations, configurable)
         │    for iteration = 1 to maxReviewIterations:
         │      BlogReviewAgent.ReviewAsync(blog, description, iteration)
         │        → BlogReviewResult { is_approved, review_summary, feedback_items[] }
         │      if is_approved: BREAK
         │      if iteration < max:
         │        BlogWriterAgent.ReviseBlogPostAsync(blog, reviewResult)
         │          → Revised BlogResponse
         │      if iteration == max: proceed with current draft (log warning)
         │
         └─ Stage 3: Image generate-review loop (max 3 iterations)
              imagePrompt = blog.ImageGenerationPrompt ?? "Professional editorial photo: {blog.Title}"
              BlogImageGenerationAgent.GenerateImageAsync(imagePrompt, blog.Slug)
                → ImageGenerationResult
              for imgIteration = 1 to maxReviewIterations:
                BlogReviewAgent.ReviewImageAsync(blog.Title, image)
                  → BlogReviewResult { is_image_approved, image_feedback }
                if is_image_approved: BREAK
                if imgIteration < max:
                  enhancedPrompt = "{imagePrompt}\n\nAdditional requirements: {image_feedback}"
                  BlogImageGenerationAgent.GenerateImageAsync(enhancedPrompt, blog.Slug)
              On image generation failure: CreatePlaceholderImage() — blog is never blocked

Output: OrchestratedBlogResult { blog, image, totalReviewIterations, reviewHistory, activityLog }

BlogEditorOrchestrator.RunAsync(BlogEditRequest)
  │
  ├─ Stage 1: BlogCommentAnalyserAgent.AnalyzeEditInstructionsAsync(existingBlog, editInstructions)
  │            Classifies what kind of edit is needed
  │            → BlogCommentAnalyserResult { contentEditNeeded, imageEditNeeded,
  │                                          contentInstructions, imageInstructions, summary }
  │            If neither needed: return immediately with original blog unchanged
  │
  ├─ Stage 2 (if contentEditNeeded):
  │    BlogEditorAgent.EditContentAsync(existingBlog, contentInstructions)
  │      → BlogEditorResponse (revised blog JSON)
  │    Review-revision loop (same max iterations as creation):
  │      BlogReviewAgent.ReviewEditedBlog(blog, iteration)
  │        → BlogReviewResult
  │      if not approved: BlogEditorAgent.ReviseContentAsync(blog, instructions, reviewFeedback)
  │
  └─ Stage 3 (if imageEditNeeded, after content is finalised):
       if request.ExistingImageBytes provided:
         BlogImageGenerationAgent.GenerateImageWithReferenceAsync(prompt, slug, referenceImageBytes)
       else:
         BlogImageGenerationAgent.GenerateImageAsync(prompt, slug)
       Image review loop (same pattern as creation pipeline)
       Image failure does NOT block — edited blog is returned without new image

Output: OrchestratedBlogEditResult { editedBlog, image, reviewHistory, contentEdited, imageRegenerated, activityLog }

public class BlogRequest
{
    public string RequestId { get; set; }         // Unique request identifier
    public string TenantId { get; set; }          // Tenant for cache key scoping
    public string Topic { get; set; }             // Blog topic / title hint
    public string PrimaryKeywords { get; set; }   // Main SEO keywords
    public string SecondaryKeywords { get; set; } // Supporting keywords
    public string Description { get; set; }       // Priority requirements (overrides best practices)
    public string BlogContext { get; set; }        // Tenant business context (injected into reviewer)
    public string RequiredDate { get; set; }       // Target publish date
    public string BlogMonth { get; set; }          // Publication month
    public string RequestedBy { get; set; }        // Requester name
    public string CompanyName { get; set; }        // Company name (for context file lookup)
    public int? ImageWidth { get; set; }           // Hero image width (default 1200)
    public int? ImageHeight { get; set; }          // Hero image height (default 400)
    public string WebsiteUrl { get; set; }         // Used for sitemap fetching
}

public class BlogResponse
{
    [JsonPropertyName("slug")]
    public string Slug { get; set; }                  // kebab-case, keyword-rich URL slug
 
    [JsonPropertyName("title")]
    public string Title { get; set; }                 // SEO title, ~70 chars, 7-9 words
 
    [JsonPropertyName("preview_content")]
    public string PreviewContent { get; set; }         // 40-60 word plain-text summary, no HTML
 
    [JsonPropertyName("content")]
    public string Content { get; set; }                // Full HTML fragment (no html/head/body tags)
 
    [JsonPropertyName("tags")]
    public List<string> Tags { get; set; }             // 4-6 tags
 
    [JsonPropertyName("seo")]
    public BlogSeo Seo { get; set; }                   // title (50-60 chars), description (140-150 chars), keywords
 
    [JsonPropertyName("faq")]
    public List<FaqItem> Faq { get; set; }             // Exactly 10 Q&A items (35-45 words each)
 
    [JsonPropertyName("image_generation_prompt")]
    public string ImageGenerationPrompt { get; set; }  // Detailed prompt passed to image agent
}

public class BlogReviewResult
{
    [JsonPropertyName("is_approved")]
    public bool IsApproved { get; set; }               // Exits review loop when true
 
    [JsonPropertyName("review_summary")]
    public string ReviewSummary { get; set; }          // Human-readable summary
 
    [JsonPropertyName("feedback_items")]
    public List<string> FeedbackItems { get; set; }    // Specific actionable items for writer
 
    [JsonPropertyName("is_image_approved")]
    public bool IsImageApproved { get; set; }          // Used in image review loop
 
    [JsonPropertyName("image_feedback")]
    public string ImageFeedback { get; set; }          // Injected into enhanced image prompt
 
    [JsonPropertyName("iteration")]
    public int Iteration { get; set; }                 // Set by orchestrator, not LLM
}

public class ImageGenerationResult
{
    public byte[] ImageBytes { get; set; }          // Raw image data
    public string SuggestedFileName { get; set; }   // e.g. "ai-ocr-ports-hero.jpg"
    public string AltText { get; set; }             // SEO alt text from slug
    public string MimeType { get; set; }            // "image/jpeg" or "image/png" (detected from magic bytes)
    public long FileSizeBytes { get; set; }
    public string PromptUsed { get; set; }          // Audit trail of what was sent to Gemini
    public bool IsPromptOnly { get; set; }          // true = generation failed, only prompt stored
    public string PromptOnlyReason { get; set; }    // Explanation when IsPromptOnly is true
}

public class OrchestratedBlogResult
{
    public BlogResponse Blog { get; set; }
    public ImageGenerationResult Image { get; set; }
    public int TotalReviewIterations { get; set; }
    public List<BlogReviewResult> ReviewHistory { get; set; }
    public List<ActivityLogEntry> ActivityLog { get; set; }  // Timestamped step audit trail
}

PromptFiles/
├── AgentInstructions/                    ← System instructions (agent identity + rules)
│   ├── BlogWriterAgentInstructions.txt
│   ├── BlogReviewerAgentInstructions.txt
│   ├── BlogEditorAgentInstructions.txt
│   ├── BlogCommentAnalyserAgentInstructions.txt
│   └── BlogEditReviewerAgentInstructions.txt
├── BlogWriterAgentPrompt.txt             ← User-turn prompt (per-request)
├── BlogReviewerAgentPrompt.txt           ← Review turn prompt
├── BlogRevisionPrompt.txt                ← Revision turn prompt
├── BlogEditorAgentPrompt.txt             ← Editor turn prompt
├── BlogEditReviewerAgentPrompt.txt       ← Edit review turn prompt
├── BlogCommentAnalyserAgentPrompt.txt    ← Comment analysis prompt
├── BlogImageReviewerPrompt.txt           ← Image review prompt
├── BlogBestPracticesPrompt.txt           ← Injected into writer prompt
└── ImageCreationPrompt.txt               ← Injected into writer prompt

URL,Title
https://example.com/blog/ai-marketing,Ai Marketing
https://example.com/services/seo,Seo

PromptSecurity.SanitizePromptInput(input, maxLength = 500)
// Removes: IGNORE PREVIOUS, SYSTEM:, OVERRIDE, ASSISTANT:, [INST], <s>, </s>
// Truncates to maxLength
// Case-insensitive matching
 
PromptSecurity.SanitizeFileName(name)
// Removes: ../, ..\, path separators, invalid filename chars
// Prevents directory traversal when loading BusinessContext/{name}.txt

You are an expert SEO blog writer. You produce complete, structured blog posts
in valid JSON where the entire blog body is a single publication-ready HTML string.

HTML CONTENT RULES:
- Write the full blog in one "content" field as a valid HTML fragment (no <html>, <head>, or <body> tags)
- Use <p> for paragraphs, <h2> for main headings, <h3> for sub-headings
- Use <ul><li> for bullet lists
- Wrap ALL internal and external links as <a target="_blank" rel="noopener" href="URL"> tags
- Key Takeaways section: <h3>Key Takeaways</h3> followed by <ul><li> items, immediately after intro
- Never use em dashes, en dashes, or emojis

JSON ESCAPING RULES (critical for valid JSON):
- NEVER use straight double quotes inside the content field — use single quotes
- All HTML attributes use single quotes: <a href='URL'> not <a href="URL">
- Put the entire "content" field on ONE CONTINUOUS LINE — no line breaks
- Response must be ONLY the JSON object, starting with { and ending with }

FAQ RULES:
- Always generate EXACTLY 10 FAQ items
- Each answer: 35-45 words
- At least 1-2 internal links per 5 FAQs, linking to pages not already in the blog
- Links must be woven naturally into sentences, not standalone CTAs

EXISTING INTERNAL LINKS:
[[existing_links]]
Only use URLs from this list. Do not invent or modify URLs.

JSON structure:
{
  "slug": "string",
  "title": "string",
  "preview_content": "string",
  "content": "string",
  "tags": ["string", ...],
  "seo": { "title": "string", "description": "string", "keywords": "string" },
  "faq": [{"question": "string", "answer": "string"}],
  "image_generation_prompt": "string"
}

Instruction:
I want to create a blog post for the business for the blog title {Topic}.
First, read the BLOG DESCRIPTION below carefully - these requirements have PRIORITY
over all other instructions and must be followed strictly.
Then, learn about the business and their goals from the BUSINESS CONTEXT below.
Finally, study the blog writing best practices from the BLOG BEST PRACTICES below.
Generate a blog post using the primary keywords {PrimaryKeywords} and secondary
keywords {SecondaryKeywords} and try to create at least [4] internal links
from the blog post using the valid URLs provided in your instructions.
STRICTLY FOLLOW meta title in range of 50-60 characters and
meta description in range of 155-158 characters.

=============================
BLOG DESCRIPTION (PRIORITY)
=============================
{Description}

=============================
BUSINESS CONTEXT
=============================
{BlogContext}

=============================
BLOG BEST PRACTICES
=============================
{BlogBestPracticesPrompt.txt content}

=============================
IMAGE BEST PRACTICES
=============================
{ImageCreationPrompt.txt content}

for (int attempt = 1; attempt <= 3; attempt++)
{
    // On retry, prepend: "[IMPORTANT: Previous response was invalid. Respond with ONLY valid JSON...]"
    var raw = await RunAsync(prompt, ct, new AgentRunOptions {
        ResponseFormat = ChatResponseFormat.ForJsonSchema<BlogResponse>()  // JSON schema mode
    });
 
    var result = JsonParsingHelper.ParseWithStrategies<BlogResponse>(raw);
 
    if (result != null) return result;
 
    // Save failed JSON to DebugLogs/ folder for inspection
    // Wait 2 seconds before retry
}
throw new InvalidOperationException("Failed after 3 attempts");

You previously produced this blog post (JSON):
{{CurrentDraft}}

The reviewer (iteration {{Iteration}}) has NOT approved it.
Review summary: {{ReviewSummary}}

Specific feedback to address:
{{FeedbackList}}     ← numbered list: "1. Feedback item\n2. ..."

Return a fully revised blog post in the same JSON structure.
Address every feedback point. Do not change the overall topic or primary keywords.
Respond with raw JSON only — no markdown, no preamble.

Review the following blog draft (iteration {{Iteration}}) against all criteria
and return your verdict as JSON.

=============================
BLOG DESCRIPTION (PRIORITY)
=============================
{{Description}}

=============================
BLOG DRAFT
=============================
{{BlogDraft}}     ← full BlogResponse JSON, pretty-printed

Return raw JSON only - no markdown, no preamble.

{
  "is_approved": true,
  "review_summary": "One paragraph summary of quality and issues",
  "feedback_items": ["Specific actionable instruction 1", "..."]
}

Review the hero image for the blog post titled "{{BlogTitle}}".

Assess the image on:
- Relevance: Does it clearly relate to the blog topic?
- Quality: Is it visually professional and sharp?
- Composition: Is the subject well-framed and not awkward?
- Tone: Does it match a professional B2B/editorial style?
- Text (if included): should be large enough to read on mobile and have no spelling mistakes.

Return raw JSON only:
{
  "is_image_approved": true,
  "image_feedback": ""
}

for attempt = 1 to 3:
  imageBytes = await _imageGenService.GenerateImageFromPromptAsync(imagePrompt)
    → Gemini outputs 1024x1024 JPEG/PNG by default

  if imageBytes is null or empty:
    throw InvalidOperationException (triggers retry)

  (extension, mimeType) = DetectFormat(imageBytes)
    → Reads magic bytes:
      JPEG: starts with 0xFF 0xD8
      PNG:  starts with 0x89 0x50 0x4E 0x47

  fileName = "{blogSlug}-hero.{extension}"
  altText  = "Hero image for blog post: {blogSlug with hyphens→spaces}"

  resizedBytes = Resize(imageBytes, targetWidth=1200, targetHeight=400, mimeType)
    → Uses ImageSharp: ResizeMode.Crop (centered), maintains quality

  return ImageGenerationResult {
    ImageBytes, SuggestedFileName, AltText, MimeType,
    FileSizeBytes, PromptUsed, IsPromptOnly: false
  }

  on exception (any):
    delay = 2^(attempt-1) seconds  → 1s, 2s, 4s
    continue retry

throw InvalidOperationException("Failed after 3 attempts")

new ImageGenerationResult {
    AltText = blogTitle,
    SuggestedFileName = $"{blogSlug}-hero.jpg",
    PromptUsed = imagePrompt,
    IsPromptOnly = true   // caller knows no bytes are available
}

{
  "contentEditNeeded": true,
  "imageEditNeeded": false,
  "contentInstructions": "Update the introduction to mention the new product launch",
  "imageInstructions": "",
  "summary": "User wants content changes to the intro only"
}

{
  "Agent": {
    "Name": "BlogWriter",
    "DeploymentName": "gpt-4o-mini",
    "ApiKey": "...",
    "Model": "gemini-2.0-flash-exp",
    "MaxTokens": 8000,
    "Temperature": 0.7,
    "SkillsPath": "skills",
    "MaxReviewIterations": 3,
    "ImageDimensions": { "Width": 1200, "Height": 400 }
  }
}

[Orchestration Started]
[Blog creation started]
[Blog creation completed]
[Review iteration 1 started]
[Review iteration 1 failed: {summary}]
[Blog revision started (iteration 1)]
[Blog revision completed (iteration 1)]
[Review iteration 2 approved]
[Image generation completed (142,500 bytes)]
[Image review iteration 1 approved]
[Orchestration completed (BlogIterations: 2, BlogApproved: true, ImageApproved: true)]