# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/agent-marketing/agent-workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.