Agents — Master Index

Leadmetrics v3 uses a single-function agent design: every agent does exactly one thing, has one input schema, one output schema, and one system prompt short enough to fit on a page. The Activity Planner chains them into pipelines. Agents stay small and testable.

Architecture at a Glance

SETUP CHAIN (once per tenant)
  Client Researcher ──┐
                      ├──► Context File Writer ──► Client Context File
  Competitor Researcher ──┘

STRATEGY CHAIN (once, on context approval)
  Strategy Writer ──► Deliverable Planner ──► Goals + Monthly Plan

ORCHESTRATION (each deliverable period)
  Activity Planner ──► dispatches tasks to workers below

SEO CHAIN
  Keyword Researcher ──► Content Brief Writer
  Site Auditor
  Backlink Researcher ──► Backlink Outreach Writer

CONTENT CHAIN
  Blog Writer · GBP Post Writer · Social Post Writer
  Email Writer · Landing Page Writer
  Google Ads Writer · Meta Ads Writer
  Content Repurposer · Blog Image Generator

PLANNING & ANALYSIS
  Social Calendar Planner · Ads Analyst
  Report Writer · Anomaly Detector

RESEARCH (Ollama/local — cost-free)
  Topic Researcher ──► Research Note Writer

CONTENT QUALITY
  Content Auditor

REACTIVE (event-triggered)
  Review Response Writer

SYSTEM / LIVE
  Blog AI Agent · Billing Agent

Agent Index

Setup Chain

Strategy Chain

Orchestration

SEO Chain

Content Chain

Planning, Analysis & Reporting

Research (Ollama/local)

Content Quality

Reactive

System Agents (Live)

Runtime — Where Agents Run

All agents run as BullMQ workers inside a dedicated background process: apps/servers/agents.

[API / Next.js]  ──enqueue job──►  [Redis / BullMQ queue]
                                            │
                               [apps/servers/agents polls]
                                            │
                               [picks up job → calls adapter]
                                            │
                               [adapter spawns LLM subprocess]
                                            │
                               [result written back to DB]

Entry point: apps/servers/agents/src/index.ts

To start in dev:

cd apps/servers/agents && pnpm dev

Worker files (in packages/agents/src/workers/):

Scaling: queues are shared across all tenants. Run multiple replicas of the server-agents container in production — BullMQ distributes jobs across all active instances automatically.

Agent Event Protocol (Apr 2026)

Every worker emits agent:started and agent:completed (or agent:failed) events via publishAgentEvent. These are persisted to the AgentRun DB table and broadcast via Redis pub/sub to the manage portal’s Execution Queue dashboard.

agent:started must include:

inputPrompt: prompt,   // full prompt string

agent:completed must include:

inputTokens:  result.usage?.inputTokens,   // nested under .usage — NOT result.inputTokens
outputTokens: result.usage?.outputTokens,
transcript:   result.transcript,           // full AdapterExecutionResult transcript array

The transcript field captures every turn of the Claude Code session (assistant messages, tool_use, tool_result, system, user, error). All LLM-calling workers emit this as of Apr 2026. Runs before that date have transcript: null in the DB.

Standard Agent Doc Structure

Every agent doc follows the same sections:

1. Overview — function, type, model, queue, cost, plan, status
2. Input — TypeScript interface + field descriptions
3. Output — TypeScript interface + sample output
4. How It Works — numbered steps
5. System Prompt — the actual prompt used
6. Skills Injected — which skill files + their content
7. Tools Required — external APIs and methods
8. HITL Gates — where human review happens
9. Guardrails — output validators
10. Cost Profile — token estimates
11. Error Handling — failure modes and responses

Superseded Agents — Replacement Map

The old multi-function agents have been deleted. For reference, here is how they mapped to the new single-function agents: