Agents & heartbeats

Agents and heartbeats are the two primitives every Linkworld app uses to do work in the background. This page explains both, the mental model that ties them together, and how to read what the platform shows you.

What is an agent?

An agent is a configured LLM persona inside an app. Each agent has:

• A slug — cmo, researcher, replier, … unique per app
• A system prompt — the persona / role description
• Tools allowed — which platform tools this agent may call (subset of the app’s declared tools)
• Memory — durable per-(tenant, agent) facts the agent can read
• Heartbeats — recurring routines this agent runs (see below)
• Optional team — slugs of teammates this agent may delegate to intra-app
• Optional vision — an open strategic goal driving an autonomous loop

You see agents listed under each app on the Workspace Control Dashboard. Click into one for the agent detail page.

Multi-agent in one app: roles in a department

A common pattern: one app = one department, multiple agents = the roles in that department.

App: Marketing (linkworld.app.yaml)
└── agents:
    ├── cmo          (master, has vision: "hit Q4 revenue target")
    ├── content_drafter
    ├── x_monitor
    └── engagement

The cmo is the master — its team: lists the slugs it can delegate to (team: [content_drafter, x_monitor, engagement]). When you tell the CMO “draft 2 X posts for tomorrow”, the CMO’s loop calls ctx.team.delegate('content_drafter', …) instead of doing the draft itself. Each specialist has narrower tools_allowed and a focused prompt.

This isn’t a Linkworld convention — it’s just how agent declarations in the manifest map to the platform’s data model. But it’s the pattern that makes apps composable.

What is a heartbeat?

A heartbeat is a recurring routine an agent runs in the background. It’s the unit of “do this every X” in Linkworld.

Example heartbeats on a marketing app’s agents:

Agent	Heartbeat	Schedule	What it does
x_monitor	mentions_check	every 30 min	Searches X for new mentions, drafts replies for approval
kpi_tracker	hourly_kpi	every 1 hour	Reads the followers count, updates the KPI record, escalates if off-pace
content_drafter	daily_post	daily 9 am	If no posts queued for today, drafts one
engagement	outreach_window	every 2 h, 9–18 in user’s timezone	Picks an account from the Tier-1 list, drafts a reply if relevant

Each heartbeat is its own row, with its own schedule and its own prompt. You can edit them on the Agent detail page.

The cheap pre-filter

The reason heartbeats are affordable: most ticks don’t run the LLM at all.

Each heartbeat has a pre-filter — a zero-LLM check that decides “is there anything to do?”. If not, the tick ends in microseconds with no model spend.

Pre-filter sources:

• Skill calls (LOW-risk only). Example: x_search for new mentions. If the search returns no new IDs since last check → skip.
• Internal _internal_app_records query. SQL against the app’s own records (record_type='content_plan' etc.). Example: “any content due today and not yet drafted?”.
• Internal _internal_agent_memory query. Useful for “have I already addressed this?” checks.

When the pre-filter finds something, the agent is invoked with the context payload. Otherwise the tick is logged as HEARTBEAT_OK and suppressed from the conversation history (so memory doesn’t bloat with empty pings).

Empirically: well-designed heartbeats run the LLM on ~20 % of ticks. That’s the difference between “affordable to run 100 heartbeats per tenant” and “too expensive to deploy”.

Reading the schedule

In Workspace Control, each heartbeat row shows:

hourly_kpi        every 1h         next: 14:00       OK 32m ago

• Slug — identifier
• Cadence — interval, daily, weekly, or cron
• Next run — when the scheduler picks it up
• Last OK — last time it returned HEARTBEAT_OK (no action needed). If it’s been a while since the last OK, the agent has been finding things to act on.

Status indicators (the colored dot):

Color	Meaning
Green	Active and running cleanly
Amber	1 or 2 consecutive failures (transient)
Red	3+ consecutive failures (failing — see Health screen)
Grey	Disabled (5+ failures triggered auto-disable, or admin paused)

Active hours: don’t post at 3 am

Every heartbeat can declare an active-hours window. Outside it, the heartbeat is skipped silently (no LLM, no skill call, no log spam).

active_hours:
  start: "07:00"
  end:   "23:00"
  timezone: "user"   # or an IANA name like "Europe/Berlin"

"user" falls back to the tenant’s configured timezone. Use this for heartbeats that have human-facing side-effects (drafting a tweet, sending a DM) so they don’t fire when nobody’s awake.

Conversation modes

Heartbeats can run in three conversation modes (set per-heartbeat):

Mode	What it means	When to use
dedicated (default)	Heartbeats share their own conversation thread per agent, separate from the user-facing chat	Most cases — keeps context coherent without polluting user chat
isolated	Fresh session per tick, no prior history	High-frequency heartbeats where token cost > continuity
main	Heartbeats fire into the user-facing main chat	When you want the heartbeat to surface in the user’s UI

Failure handling

The platform tracks consecutive_failures per heartbeat. After 5 in a row it auto-disables the row (sets status=disabled). You see it in:

• The failing list on the Health screen (only while still active)
• The disabled column of the per-app rollup once disabled

Common causes:

• A skill the heartbeat depends on lost its OAuth token
• The pre-filter SQL references a column that was renamed
• The agent’s LLM provider throttled

Click the heartbeat → fix the underlying issue → re-enable on the agent detail page (or wait for the next manifest reactivation, which re-syncs everything).

Vision-loop vs heartbeats

Two different mental models, both supported simultaneously:

• A vision is a goal — “hit 500 X followers by Day 7” — that the agent pursues through the multi-phase ASSESS → DEBATE → PLAN → EXECUTE → REVIEW loop. One vision per agent. Strategic.
• Heartbeats are routines — “check inbox every 30 min” — bounded, deterministic, cheap. Many heartbeats per agent. Tactical.

A typical agent has both: the master CMO has a vision driving its strategic decisions and several heartbeats keeping it informed (KPI hourly, mentions every 30 min, etc.).

What’s next

• See Workspace Control for how to navigate through the agent detail page in the UI.
• For developers building agents into their app, the Heartbeats reference covers the manifest schema and pre-filter source types.