Skip to content
Foundation Docs

Run & schedule agents

Sync Agents are designed to be set and forget. Once you add an agent to a lens, Foundation keeps the tree in sync using Jira events — you should rarely need to trigger a run yourself.

This page explains when agents run automatically and how to force a run when you want one.

Automatic execution

Section titled “Automatic execution”

Sync Agents re-run automatically through three layers:

  1. On lens open — if the lens has stale data for any project it draws from, Foundation runs agents before showing the tree.
  2. On Jira events — when an issue is created, updated, or deleted in a project your lens tracks, the relevant agents run and the change shows up in seconds.
  3. Safety net — a periodic count check catches edge cases where a direct event wasn’t fired.

Field edits on an issue already in the lens are instant. Structural changes — new issues entering or leaving a JQL result set — appear within 3 to 10 seconds.

Manual run

Section titled “Manual run”

A manual run is available as a fallback, useful when you’ve just tweaked a query and want to see the result immediately.

  1. Open the lens and open the Inspector panel.
  2. In the Sync Agents section, click Run Sync Agents.
  3. A progress indicator appears in the header. The job runs in the background — you can keep working.
  4. When the run finishes, the lens reloads.

Long runs execute as Forge async events with a 15-minute timeout. Job status polls every 3 seconds and shows up as a toast or inline status in the Sync Agents section.

Refresh issue data

Section titled “Refresh issue data”

“Run Sync Agents” rebuilds the tree. If you only want to pull fresh field values for issues already in the lens (after a manual Jira change, for instance), use the Refresh data button in the same section. It re-fetches cached issue data without re-running the agent pipeline.

What can pause automatic execution

Section titled “What can pause automatic execution”
  • The lens has hit the 10,000-item cap.
  • A run exceeded the async event timeout (15 minutes).
  • Your Jira API rate-limit budget for the site is exhausted.

When any of these happen, Foundation shows a warning in the Sync Agents section with a suggested fix. Re-running manually after the condition clears will resume normal operation.

Section titled “Related”