# Agent Workflows

Detailed examples for common agent-driven brand operations.

### Example 1: Weekly Brand Cadence

A complete weekly brand maintenance routine:

```
Monday: Content Creation
  1. get_brand_performance → check KPI trends
  2. get_content_health → identify striking distance keywords
  3. research_keywords → expand on opportunities
  4. create_content (x2-3 articles) → target top keywords
  5. create_planner_item → schedule remaining articles

Wednesday: Optimization + Visual + Social
  1. grade_content → grade Monday's articles
  2. optimize_content → improve any <70 scores
  3. generate_images_bulk (article_ids, use_brand_colors: true)
  4. publish_content → push completed articles to CMS
  5. generate_social_multi → social posts for each article
  6. generate_image → custom visuals for social posts
  7. schedule_social → distribute through the week

Friday: Newsletter + Analytics
  1. generate_newsletter → weekly roundup from published articles
  2. get_social_analytics → review social performance
  3. get_ai_visibility → check for new LLM citations
  4. update_content_strategy → adjust based on data
```

### Example 2: New Brand Setup

First-time configuration for a brand joining Cuppa:

```
Phase 1: Brand Foundation
  1. create_site (domain)
  2. update_brand_context → company name, industry, voice, audience
  3. update_brand_visual_style → colors, fonts, logo URL
  4. create_knowledge → upload key brand documents, FAQs, style guides

Phase 2: Visual Identity
  1. create_mood_board (name: "Brand Direction", site_id)
  2. generate_mood_board (mood_board_id, site_id)
     → Auto-generates visual direction from Brand DNA
  3. get_mood_board → review generated images, colors, fonts
  4. generate_image (prompt: "hero image for homepage",
     site_id) → brand-colored hero

Phase 3: Content Strategy
  1. research_keywords (industry seed terms)
  2. generate_cluster (topic clusters from research)
  3. activate_cluster → add to content plan
  4. update_content_strategy → set article defaults, enable social,
     configure newsletter

Phase 4: Initial Content
  1. create_project (10-15 articles from clusters)
  2. Monitor with get_content_status
  3. grade_content → grade all completed
  4. generate_images_bulk (article_ids, use_brand_colors: true)
  5. publish_content → push to CMS
  6. generate_social_multi → announce each article
  7. generate_video_script (brief: "brand intro",
     format: "logo_brand_reveal", site_id)
  8. create_video → brand reveal video for social
```

### Example 3: Competitor Response Campaign

React to a competitor's content move:

```
1. research_competitors (competitor URLs)
   → Identify topics they cover that you don't

2. get_ai_visibility (your site)
   → Check citation gaps where competitor is cited, you aren't

3. get_backlinks (your site)
   → Compare DR and referring domains

4. For each gap:
   a. research_keywords → find the specific keyword
   b. create_content → write a better article
   c. create_knowledge → add structured data for AI citation
   d. generate_images_bulk ([article_id], use_brand_colors: true)

5. generate_social_multi (topic: each gap topic)
   → Create social posts driving awareness

6. Strengthen with links:
   - refresh_link_sitemaps → ensure Link Engine indexes new content
   - Link Marketplace (UI) → browse guest post opportunities
     to build backlinks to new content

7. For critical articles, request expert review:
   - Expert Reviews (UI) → human specialist review for E-E-A-T

8. Monitor:
   - get_brand_performance → track visibility score
   - get_ai_visibility → watch for new citations
```

### Example 4: Social-First Campaign (No Articles)

Launch a social presence around a theme without article creation:

```
1. get_brand → load brand voice and identity

2. Define campaign topics (5-10 related posts):
   - Topic 1: Industry insight
   - Topic 2: Behind-the-scenes
   - Topic 3: Customer story
   - Topic 4: Educational tip
   - Topic 5: Contrarian take

3. For each topic:
   generate_social (site_id, topic, platform: "linkedin",
     tone: "professional", hook_type: varies)

4. Generate visuals for each post:
   generate_image (prompt based on topic, site_id,
     aspect_ratio: "1:1")

5. For video-first platforms:
   generate_video_script (brief: topic, format: "ugc_style",
     platform: "tiktok", site_id)
   create_video (prompt, model: "sora-2",
     duration_seconds: 15, aspect_ratio: "9:16")

6. Schedule across the week:
   schedule_social (content, scheduled_at: staggered times)

7. For the best topic, create a deep-dive:
   generate_carousel (topic, slide_count: 8, generate_images: true)
   publish_carousel (caption, image_urls)

8. Track:
   get_social_analytics → measure after 7 days
```

### Example 5: Content Refresh Sprint

Fix content decay identified by performance data:

```
1. get_content_health → get contentDecay list
   (pages losing >20% traffic in last 14 days)

2. For each decaying page:
   a. list_contents (url filter) → find the Cuppa article
   b. grade_content (id) → check current grade
   c. fetch_serp_data (id) → see what competitors do better
   d. optimize_content (id) → apply AI suggestions
   e. grade_content (id) → verify improvement
   f. publish_content (id) → push updated version

3. For striking distance keywords (pos 4-20):
   a. get_content_health → strikingDistance list
   b. For each keyword without an article:
      create_content (keyword)
   c. For each keyword with an existing article:
      optimize_content → push to page 1

4. Regenerate social for refreshed content:
   generate_social_multi → new social posts for each updated article
```

### Example 6: Visual Content Sprint

Create a batch of brand-consistent visual assets for a campaign:

```
Phase 1: Establish Visual Direction
  1. get_brand (site_id) → load brand DNA + visual style
  2. create_mood_board (name: "Q2 Campaign", site_id)
  3. generate_mood_board (mood_board_id, site_id)
     → Auto-generates images + colors from Brand DNA
  4. get_mood_board → review and confirm direction

Phase 2: Static Images
  1. list_image_models → choose the right model
     (gpt-image-1 for versatile, flux-1.1-pro for photorealistic,
      imagen-4.0 for Google quality)
  2. generate_image (prompt: "hero banner for Q2 launch",
     model: chosen, aspect_ratio: "16:9", site_id)
  3. generate_image (prompt: "social thumbnail variant",
     aspect_ratio: "1:1", site_id)
  4. generate_image (prompt: "story format visual",
     aspect_ratio: "9:16", site_id)

Phase 3: Article Images (bulk)
  generate_images_bulk (article_ids, model, use_brand_colors: true)
  → Generates featured images for all articles at once

Phase 4: Video Assets
  1. generate_video_script (
       brief: "Q2 product launch teaser",
       format: "product_showcase", site_id)
  2. create_video (prompt, model: "sora-2",
     duration_seconds: 15, aspect_ratio: "16:9",
     use_brand_context: true)
  3. get_video_status → poll until complete
  4. generate_video_script (
       brief: "Behind the scenes of our team",
       format: "ugc_style", platform: "tiktok", site_id)
  5. create_video (prompt, model: "replicate:kling-v2.6",
     duration_seconds: 10, aspect_ratio: "9:16")

Phase 5: Carousel Content
  1. generate_carousel (site_id,
     topic: "5 things you didn't know about [product]",
     slide_count: 8, tone: "educational",
     generate_images: true)
  2. publish_carousel → LinkedIn
  3. generate_carousel (different topic, slide_count: 5)
     → Lighter version for later in the week
```

### Example 7: Link Building + Authority Sprint

Build backlink profile and domain authority:

```
Phase 1: Audit Current State
  1. get_backlinks (site_id)
     → Check DR, total backlinks, referring domains
  2. get_link_stats
     → Link Engine overview (active sites, URLs indexed)
  3. list_link_sites
     → Review all sites with Link Engine status

Phase 2: Internal Linking
  1. refresh_link_sitemaps (site_ids)
     → Re-index after recent content publishes
  2. get_link_categories
     → Review how sites are organized
  3. create_link_category (name: "Q2 Priority")
     → Group sites for targeted interlinking
  4. bulk_update_link_sites (site_ids, category_id)

Phase 3: External Link Acquisition
  - Link Marketplace (UI at /link-marketplace):
    → Filter by: DR > 40, organic traffic > 5K,
      your niche category, dofollow, guest post
    → Auto-matches your site's language and region
    → Compare prices across publishers

Phase 4: E-E-A-T Boost
  - Expert Reviews (UI at /author-reviews):
    → Request expert review for key pillar articles
    → Experts matched to your industry via Brand DNA
    → Adds real authorship and expertise signals

Phase 5: Monitor Impact
  1. get_backlinks → track DR changes over weeks
  2. get_brand_performance → check organic visibility
  3. get_content_health → see if target pages are climbing
```

### Example 8: Newsletter-Driven Content Strategy

Use newsletters as the anchor for content creation:

```
1. update_content_strategy (newsletter: {
     enabled: true, cadence: "weekly", send_day: "friday"
   })

2. Each week, ensure 3-5 articles are published by Thursday:
   - Monday: create_content x2
   - Wednesday: create_content x2, publish previous batch
   - Thursday: publish remaining, generate_newsletter

3. Review newsletter content:
   get_newsletter (id) → check subject, summaries, HTML

4. Track newsletter performance over time:
   list_newsletters → compare article counts and engagement
   get_social_analytics → check if newsletter topics drive social
```