Content Agent

Relevant source files

The following files were used as context for generating this wiki page:

• lib/agents/content/createContentPromptAgent.ts
• app/api/content-agent/%5Bplatform%5D/route.ts
• lib/content/validateCreateContentBody.ts
• lib/agents/content/tests/registerOnNewMention.test.ts
• README.md
• lib/chat/const.ts

The Content Agent is a specialized AI system within the Recoup ecosystem designed to automate the generation of music industry marketing materials, specifically video content and captions. It functions by intercepting natural language requests—either via webhooks from external platforms like Slack or through direct API calls—and transforming those requests into structured parameters for content production pipelines.

The system leverages Large Language Models (LLMs) to parse intent and manages the orchestration between incoming mentions, parameter extraction, and the triggering of background content creation tasks.
Sources: lib/agents/content/createContentPromptAgent.ts:55-65, README.md:120-130

System Architecture

The Content Agent architecture is divided into three primary layers: the Interface Layer (handling webhooks), the Intelligence Layer (parsing intent), and the Execution Layer (triggering background jobs).

The flow demonstrates how requests from both interactive platforms and programmatic APIs converge on the same background execution logic.
Sources: app/api/content-agent/[platform]/route.ts:11-15, lib/agents/content/tests/registerOnNewMention.test.ts:73-90, README.md:120-130

Intelligence Layer: Prompt Parsing

The system uses a dedicated ToolLoopAgent to convert unstructured text (e.g., "make 3 high quality lipsync videos for the hiccups song") into a strictly typed schema. This agent is configured with specific instructions regarding visual templates and extraction rules.

Content Prompt Flags

The contentPromptFlagsSchema defines the parameters the agent must extract:

Flag	Type	Description
lipsync	Boolean	True if the prompt mentions mouth-synced audio or singing.
batch	Integer	Number of videos to generate (1 to 30).
captionLength	Enum	Length of the accompanying text: 'short', 'medium', or 'long'.
upscale	Boolean	High quality/4K processing flag.
template	Enum	The specific visual scene/visual template to use.
songs	Array	Specific song names or slugs mentioned in the prompt.

Sources: lib/agents/content/createContentPromptAgent.ts:11-38, lib/agents/content/createContentPromptAgent.ts:46-52

Parsing Logic Implementation

The parsing agent uses a "lightweight model" and is designed to stop after a single step (stepCountIs(1)), ensuring efficiency while maintaining accuracy in mapping natural language to the CONTENT_TEMPLATES.
Sources: lib/agents/content/createContentPromptAgent.ts:55-65

Interface Layer: API and Webhooks

The Content Agent exposes two primary entry points: a platform-agnostic webhook endpoint and a structured POST endpoint.

Platform Webhooks

The system handles external platform interactions (primarily Slack) through a dynamic route segment.

• Path: /api/content-agent/[platform]
• Mechanism: Uses createPlatformRoutes to link the contentAgentBot to incoming GET and POST requests.
  Sources: app/api/content-agent/[platform]/route.ts:1-15

Direct API Creation

The /api/content/create endpoint allows for manual content triggering with pre-validated data.

Execution Layer: Handling Mentions

When the bot is mentioned (e.g., in a Slack thread), it executes a sequence of operations to initiate content production.

1. Attachment Extraction: Scans the message for audio (song) or image files.
2. Prompt Parsing: Passes the message text to the createContentPromptAgent.
3. Readiness Check: Verifies the artist's repository and content readiness.
4. Task Triggering: Calls triggerCreateContent for each item in the requested batch.
5. Status Polling: Initiates triggerPollContentRun to track the background job progress.

Sources: lib/agents/content/tests/registerOnNewMention.test.ts:73-120, lib/agents/content/tests/registerOnNewMention.test.ts:192-210

Media Attachment Integration

If a user attaches an image or audio file directly to the mention, the agent prioritizes these over standard database lookups.

• Audio: Added to the songs array as a URL from Vercel Storage.
• Images: Passed to the creation task in a dedicated images array.
  Sources: lib/agents/content/tests/registerOnNewMention.test.ts:212-245

Configuration and Defaults

The agent operates with a "Sandbox-First" approach, prioritizing persistent environments for content generation and data analysis.

• Default Model: openai/gpt-5-mini (General) or LIGHTWEIGHT_MODEL (Prompt Parsing).
• Message Limit: Max 55 messages per context.
• Default Template: DEFAULT_CONTENT_TEMPLATE (e.g., artist-caption-bedroom).

Sources: lib/chat/const.ts:1-15, lib/agents/content/createContentPromptAgent.ts:40-44

Summary

The Content Agent serves as a bridge between creative requests and automated production. By combining a strict validation schema for API-driven creation with a flexible LLM-based parser for platform mentions, it ensures that music teams can generate high-quality marketing assets with minimal friction across different communication channels.