Agents & Enrichment
When you create content in LeftFold, agents enrich it automatically. Agents subscribe to traits, not types — so custom aggregates get the same enrichment pipeline as built-in ones.
How enrichment works
Every piece of content flows through the same pipeline:
- You create content — via MCP, CLI, SDK, or the HTTP API. An event is appended to the event store.
- Dispatch finds matching agents — the dispatcher reads the aggregate's traits and finds every active agent that subscribes to at least one of them.
- Agents run — each agent processes the content and produces an enrichment (summary, entity list, alt text, structured data, etc.).
- Enrichment events are appended — each result becomes an
.enrichedevent on the aggregate, attributed to the agent. - Mailbox task created — unless the enrichment is auto-approved (embeddings and kind detection), a task appears in your mailbox for review.
- You review — approve, edit, or reject. Approved enrichments are folded into the aggregate's projection on next read.
This pipeline runs for every content event, on every aggregate, across every surface. No configuration per aggregate type — traits handle the routing.
Trait-based dispatch
Agents don't subscribe to specific aggregate types — they subscribe to traits. This is the key design decision that makes custom aggregates work immediately.
When you create an article (content-bearing + publishable), five agents fire: summarizer, embedder, entity extractor, structured data generator, and linker.
When you create a custom Recipe aggregate with the same traits, the same five agents fire. No setup, no configuration, no agent changes.
Media-bearing agents (kind detector, image analyzer) are dispatched with higher priority than content-bearing agents, so file classification and analysis happen before NLP processing.
The 7 internal agents
Every workspace ships with seven internal agents, registered automatically on signup:
| Agent | Subscribes to | Produces | Review |
|---|---|---|---|
| Kind Detector | media-bearing | File type classification | Auto-approved |
| Embedder | content-bearing | 1536-dimensional vector embedding for semantic search | Auto-approved |
| Summarizer | content-bearing | 2-3 sentence summary | Needs review |
| Image Analyzer | media-bearing | Alt text, color palette, scene description | Needs review |
| Entity Extractor | content-bearing | People, places, organizations mentioned in text | Needs review |
| Structured Data | publishable | JSON-LD markup for SEO | Needs review |
| Linker | publishable | Cross-link suggestions based on the knowledge graph | Needs review |
"Auto-approved" means the enrichment is applied immediately without appearing in the mailbox. Embeddings and file classification are mechanical operations that don't need human judgment. Everything else — summaries, alt text, entity lists, structured data, link suggestions — goes through the mailbox for review.
Brand guardrails
Every agent prompt is augmented with your brand context, loaded from the brand aggregate. This ensures enrichments match your voice and terminology.
| Guardrail | What it does |
|---|---|
| Voice | Tone and style guidelines (e.g. "professional but approachable") |
| Glossary | Preferred terminology (e.g. "use 'practitioner' not 'therapist'") |
| Taxonomy | Content categories for consistent tagging |
| Content guardrails | Topics to avoid, claims not to make, regulatory constraints |
Guardrails are soft constraints injected into the system prompt — not hard validation rules. The mailbox is the enforcement point. Update your brand aggregate at any time; changes take effect on the next agent run.
Failure handling
When an agent fails, the system retries with exponential backoff:
- Retry schedule: 1 second, 5 seconds, 30 seconds, 5 minutes (3 retries max)
- Dead letter queue: after 3 failures, the task is moved to the dead letter queue and a notification appears in your mailbox
- Circuit breaker: after 5 consecutive failures, the agent is automatically paused and a notification alerts the workspace owner
Paused agents can be re-enabled from the dashboard or via the CLI.
Budget controls
Every agent call tracks token usage and estimated cost. Budgets are managed at the workspace level:
- Monthly budget: when exceeded, all agents pause until the next billing cycle
- Per-agent tracking: total tasks and total cost visible in the dashboard
- Cost breakdown: input tokens, output tokens, and estimated cost per task