Atoll Heartbeat: how AI agents stay oriented across sessions

An agent starts each run with the context its harness provides. That context can miss the latest assignment, a blocked issue, or a KPI that has fallen behind. Atoll heartbeat gives the agent a current briefing before it chooses work.

The REST endpoint is GET /api/orgs/{orgId}/heartbeat. The CLI wraps the same computed briefing with atoll heartbeat --json. Access controls filter project-bound data for the caller. Owners and admins can request full organization context; members and guests see the strategy and work that their access permits.

Compact output for the first read

REST and private CLI or MCP reads return a compact response by default. It contains direct attention items, grouped actionable signals, a recommended action when Atoll can determine one, counts, delta data, and page metadata. The response omits the full goals, KPI, initiative, assigned-issue, and board-context collections.

The public plugin MCP keeps its legacy full heartbeat shape. Private MCP follows the compact contract described here.

Atoll bounds each default compact response to 16 KiB and 25 signal groups. If the response has another page, read the exact page.next_cursor until page.has_more is false. Only the terminal page supplies page.ack_cursor for a later acknowledgement.

This excerpt uses example values to explain selected fields. It omits required fields; do not use it as a complete API response.

{
  "attention_items": [],
  "signals": [
    {
      "key": "signal:kpi_off_pace:kpi:kpi-uuid",
      "kind": "signal",
      "severity": "warning",
      "action_reason": "KPI \"paying_customers\" is off pace",
      "root_entity": { "id": "kpi-uuid", "type": "kpi", "title": "paying_customers" },
      "evidence": ["Review the initiative expected to move this KPI"]
    }
  ],
  "recommended_action": {
    "action_type": "investigate",
    "title": "Review the off-pace KPI"
  },
  "counts": { "actionable_groups": 1, "critical": 0, "warning": 1 },
  "delta": { "new_count": 1, "suppressed_expected_waits": 0 },
  "page": { "has_more": false, "ack_cursor": "<opaque-terminal-cursor>" }
}

Read the heartbeat API reference for the complete response schema.

Signals describe current work

Atoll computes signals from the strategy and execution data. The current signal types include:

• kpi_off_pace and kpi_stale identify a metric that needs review.
• issue_stale, issue_blocked, and milestone_overdue identify execution conditions.
• initiative_stalled and the three initiative-target signals connect initiative health to its commitments.
• webhook_failing reports a failing webhook integration.

Each signal has a severity of info, warning, or critical. Compact output groups related signals and sorts the groups by severity and age. It can also suppress an expected dependency wait when the work has a readable release condition and no active anomaly.

The agent loop

A useful loop starts with the heartbeat read. The agent handles direct attention items, acknowledges each handled item, reads the highest remaining signal, and checks the linked strategy and execution records. It can then update an issue, create approved work, or escalate a blocker. A caller with organization owner or admin Strategy write access can also refresh a KPI. The agent stops after the current action and lets its scheduler decide when to run again.

atoll heartbeat --json
atoll issue list --open --json
atoll issue update ATOLL-42 --status in_progress --comment-body "Starting the linked work."

Use atoll heartbeat --full --json when the agent needs the legacy full context, including goal detail, assigned work, and project context. Full requests cannot combine with compact paging, a since cursor, or a page cursor.

Why the shape matters

A bounded response gives a recurring agent run a predictable first read. The agent can act on a grouped blocker without assembling a large collection of unrelated records. When it needs detail, the group can include a suggested read, and the agent can request the relevant issue, dependency chain, or full heartbeat view.

The server computes the same signal definitions for each caller, then applies the caller's access and heartbeat policy. Authorized humans can configure included sections, signal categories, projects, initiatives, and task columns for an agent without granting new project access.

The Atoll docs contain the endpoint, cursor, acknowledgement, and CLI details. Start with a compact read, follow its page contract, and request full context only when the next decision requires it.