Architecture

The Base Class

All agents inherit from an abstract base class that enforces a lifecycle: queued → running → success/failure/skipped. Every agent registers in a central Map (not an object, for security), making them discoverable by ID. When triggered, an agent is instantiated and its execute() method is called inside a Datadog trace span.

Token Counting & Cost

Every Claude call is tracked: input tokens, output tokens, model used. Costs are calculated at runtime using a pricing table (Sonnet, Opus, Haiku variants each have different rates). The final cost is written to the run record, making it auditable.

Fire-and-Forget Execution

When a user triggers an agent (or cron triggers it), the API responds in ~100ms with the run ID, even though the agent hasn't executed yet. The actual work happens in the background via Next.js after() callback, keeping the response time fast and predictable. The studio dashboard polls for live status every ~3 seconds.

The Seven Agents

• WRITER-02: Drafts essays given a topic. Stores draft to database with status='draft'.
• CRITIC-04: Scores drafts against a 7-axis rubric (clarity, originality, audience fit, etc.). Chained after WRITER automatically.
• SCOUT-01: Generates topic candidates for future essays. Fills a topic pool that WRITER draws from.
• PUBLISHER-05: Creates LinkedIn companions for published essays (in-progress, not yet verified in production).
• ANALYTICS-07: Writes weekly digests of internal pipeline activity (essays published, run costs, tokens used, etc.).
• MATCH-06: Scores sponsor/partner inquiries for fit (in-progress, unverified).
• PRODUCER-03: Drafts a video script for a published essay (in-progress, not yet verified in production). No voice synthesis or rendering — script only.

Triggers: Manual & Scheduled

Agents are triggered manually from the studio (e.g., "Run WRITER-02") or automatically on a schedule. A daily orchestrator runs at a fixed time (UTC), checking if the draft queue is below target (default: 3 pending drafts). If so, it triggers WRITER-02 with the next topic. It also runs SCOUT-01 to top up the topic pool, PUBLISHER-05 to draft LinkedIn companions, PRODUCER-03 to draft video scripts, ANALYTICS-07 to write weekly digests, and MATCH-06 to triage sponsor inquiries.

Agent Chaining

After WRITER-02 completes successfully, it automatically triggers CRITIC-04 with the draft ID. This fire-and-forget chain means essays are scored immediately, without manual intervention. Other agents are not chained; they run independently on manual or scheduled triggers.

Concurrency & Schema Drift

When database migrations are deployed, there's a window where code has been updated but the schema hasn't. We handle this with fallback logic: WRITER catches "column does not exist" errors and retries without the new column. Other agents use optimistic concurrency guards (unique partial indexes, edit-version incrementing triggers) to prevent race conditions where two agents try to create the same record simultaneously.