Operations experience

Operations is where Agentweaver users answer one practical question: is the system ready to keep agents moving safely? Diagnostics, Heartbeat, Flow, Cluster, and Observability provide inspection. Account, platform, and project settings have distinct configuration scopes. MCP exposes selected operations through focused tools.

Scope: this page covers operations surfaces that exist today; it does not describe unsupported cost metrics, hidden telemetry, or deployment settings that are not exposed in the product.

Related context: Overview, Projects, Workflows & backlog, MCP client experience, Configuration, Events & observability, Sandbox, and Infrastructure & deployment.

Mental model

Agentweaver operations is a control room, not a general admin console. A user usually comes here to:

1. confirm that the backend is healthy;
2. confirm that heartbeat is ticking and picking up Ready work;
3. see which agents are active, queued, blocked, or done;
4. inspect or change a repository sandbox policy;
5. separate project configuration from system health.

The backend remains the source of truth. The web UI renders snapshots, badges, cards, and empty states. MCP tools return the same operational facts as structured results an assistant can summarize or act on.

The important operating rule is: Agentweaver shows real state. Diagnostics can warn or fail. Heartbeat can be running, waiting_first_tick, or disabled. Flow can be empty. Sandbox policy can prevent shell execution even when the project itself is available.

Operations surfaces at a glance

Surface	Where the user goes	What it answers	MCP parity
Account settings	Account menu → Account settings	Authentication, personal AI access, GitHub connections, and MCP client setup	No single equivalent tool
Platform settings	Platform settings (/platform-settings)	Deployment model-provider configuration, subject to platform permissions	No dedicated operations tool
Project Settings	Project Settings → Sandbox policy	Which sandbox policy applies to this project's working directory?	sandbox_policy_get, partially sandbox_policy_set
Diagnostics	Project Diagnostics page	Is the system or project healthy enough to operate?	diagnostics_get for global diagnostics
Heartbeat	Project Heartbeat page	Is background automation enabled, ticking, and acting?	heartbeat_status
Flow	Project Flow page	What is each agent working on right now?	Indirect through board/run/coordinator tools
Cluster	Project Cluster page (SYSTEM section)	Are claims binding, are resources healthy, and are pods orphaned?	No dedicated MCP tool; REST: GET /api/diagnostics/cluster
Observability	Project Observability, Traces, and Agents	What usage, performance, and recorded trace data is available?	No dedicated MCP tool; traces REST: GET /api/metrics/runs/{runId}/traces

Use Diagnostics when something feels broken. Use Heartbeat when Ready work is not being claimed. Use Flow during active multi-agent work, project Settings for command policy, and Cluster when runs are slow to schedule or pods are accumulating.

Settings experience

Settings have three distinct scopes:

• Account settings for the signed-in user's authentication, personal AI access, repository access, and MCP clients;
• Platform settings for model providers and deployment-level provider configuration;
• project Settings for one project's repository, execution/provider choices, review and sandbox policy, and lifecycle actions.

For project management and MCP project_configure, see Projects. Account settings is not a repository-path sandbox editor, and it cannot grant or revoke Microsoft Entra platform roles.

Account and platform settings

Account settings shows Authentication, AI Access, GitHub connections, and MCP clients. Personal session-chat AI access is separate from project Copilot connections. Entra role assignments are displayed, not changed on this page.

Platform settings manages model-provider entries. It is separate from project provider selection and repository sandbox policy; access depends on the user's platform permissions.

Project Settings sandbox policy

Project Settings has an in-page rail. The operations-relevant section is Sandbox policy, described as Control how agent commands execute and what they may reach. It loads from the project's working directory, so the user does not type a path.

The section shows shell, sandbox, and outbound-network switches plus read-only allowed roots and blocked patterns. It saves with Save and reports success or an inline API error. Preview approval timeout and lifetime are configured here too; both default to 1440 minutes (24 hours).

Use project Settings for an active project's policy. MCP sandbox_policy_get can inspect a repository path, while sandbox_policy_set changes only shell enablement.

What Settings does not expose

Account settings is not a general deployment console. Database/workspace paths, CORS, Kubernetes routing, and Key Vault delivery remain runtime/infrastructure concerns. Platform provider controls are a separate surface; see Configuration and Infrastructure & deployment.

Diagnostics experience

Diagnostics answers: is Agentweaver healthy enough to operate right now? It is read-only and runs real checks over live state.

The page title is Diagnostics with subtitle System and project health checks. It provides:

• Global and This project tabs;
• Auto-refresh switch;
• Re-run button;
• Updated timestamp;
• summary cards;
• check cards with pass, warn, or fail badges and durations.

Global diagnostics show API version, Uptime, Total projects, Total runs, and Active runs. Project diagnostics show Project and Checks. The check section reads Checks (n) · duration ms. Each card shows name, status, detail, and elapsed milliseconds. If no rows are returned, the page says No checks reported.

When to use Diagnostics

Open Diagnostics when:

• the API is reachable but a page behaves unexpectedly;
• a project cannot be opened, synced, or run;
• GitHub-dependent actions warn or fail;
• board state does not reflect expected work;
• heartbeat needs broader context;
• an operator wants a before/after health check around deployment or configuration changes.

Global diagnostics are process-wide. Project diagnostics are workspace- and project-specific. The API can be healthy while one project workspace is unavailable.

MCP diagnostics

MCP exposes global diagnostics with diagnostics_get. The tool returns a real-time system snapshot: API version, process uptime, project and run counts, heartbeat state, and checkpoint GC state.

Use diagnostics_get when an assistant needs to answer “is Agentweaver healthy?”, “how long has the API been up?”, “how many runs are active?”, or “what does the backend report about heartbeat and checkpoint GC?” It is read-only.

Checkpoint GC

Checkpoint GC appears as operational state inside diagnostics. The Diagnostics page reports checkpoint GC health; it does not tune checkpoint cleanup.

Heartbeat experience

Heartbeat answers: is background automation ticking, and did it act? The coordinator heartbeat service runs on an interval and drives backlog pickup from Ready into active coordinator work.

Pickup is not just a timer-to-run arrow. The task must remain eligible, its project must be available, and the atomic claim must win before a coordinator run is reserved. A lost claim starts no duplicate run; an unavailable project is not treated as a successful pickup. Automation status and recent ticks explain whether this path ran; Flow separately projects the resulting work.

The page title is Heartbeat with subtitle Background automation status and recent ticks. It provides:

• Auto-refresh switch;
• Refresh button;
• service status badge;
• enabled flag and interval;
• last tick time;
• last error, when present;
• Automations cards;
• Recent activity table.

Service status

The status badge can be:

• running — enabled and has ticked;
• waiting_first_tick — enabled but no completed tick yet;
• disabled — background automation is off.

The row also shows Enabled or Disabled, interval Ns, and Last tick. If there is no tick time, it shows —.

waiting_first_tick is normal shortly after startup. If it persists beyond the interval, refresh the page and then check Diagnostics. disabled means Ready backlog pickup will not run through heartbeat.

Automations and recent activity

The Automations section shows the real automation catalog, including Coordinator Heartbeat and Checkpoint GC. Each card shows name, status, description, Cadence: every Ns, Last run, and last acted count when available.

The Recent activity table shows completed ticks:

• Automation (first column) — which background automation produced the tick record (e.g. Coordinator Heartbeat or Checkpoint GC)
• When
• Acted
• Errors
• Duration
• Error

If no ticks exist, the page says No ticks recorded yet. That is expected before the first tick, after process start, or when heartbeat is disabled.

MCP heartbeat

MCP exposes heartbeat with heartbeat_status. The tool returns enabled flag, interval, last tick time, and service state (running, waiting_first_tick, or disabled).

Use heartbeat_status when an assistant needs to answer whether backlog pickup is running, when the last tick occurred, or whether heartbeat is disabled versus waiting for its first tick. The tool is read-only.

Flow experience

Flow answers: what is each agent working on right now? It is the live agent activity view for a project.

The page title is Flow. The default subtitle is What each agent is working on right now. With an agent filter, it becomes Live work and terminal-run archive for {agent}. Flow auto-refreshes every five seconds and also provides Refresh.

Flow reads the project board's agent_queues projection and sorts agents by operational pressure: active work first, then queued work, then blocked work.

Agent cards

Each agent card shows:

• agent avatar and name;
• active, queued, blocked, and done badges;
• Idle when there is no active, queued, or blocked work;
• orchestration groups when the agent has work across coordinator runs;
• sample subtask titles;
• View orchestration links.

An orchestration group shows the title when present, otherwise a shortened orchestration id. It then shows that agent's counts inside the orchestration and links to the orchestration detail page.

Flow is not a full run timeline. It is the team-load view: who is busy, who is waiting, who is blocked, and which orchestration deserves attention.

Agent filter and archive

When opened with an agent filter, Flow shows an Agent filter badge, the agent name, and Clear filter. It also shows Previous work archive for terminal runs: completed, merged, assemble-ready, declined, failed, and merge-failed work. Archive links open the relevant run/orchestration context; there is no standalone Execution page. Entries show status, timestamp, and model id when available.

Empty states

Flow states are explicit:

• No active agents — no current agent queue projection; the page says to start an orchestration to see live activity.
• No active work for {agent} — that agent has no current in-flight subtasks; completed work remains in the archive.
• No terminal runs found for this agent. — the selected agent has no terminal archive entries.

An empty Flow page is not automatically a system failure. Check the board for Ready work, Heartbeat for pickup, and Diagnostics for backend health.

Sandbox policy experience

Sandbox policy answers: what may agent commands do for this repository? It is repository-scoped, available from project Settings and the narrower MCP tools, not Account settings.

At a user level, the policy controls:

• whether shell execution is available;
• whether commands run in a sandbox or directly on the host;
• whether outbound network is enabled when sandboxing is on;
• which repository roots are allowed;
• which destructive command patterns are blocked or require stronger handling.

The deeper model is layered: governance, filesystem containment, execution isolation, network boundaries, and bounded/redacted output. See Sandbox.

UI policy fields

UI label	User meaning
Shell execution	Enables or disables agent shell commands for the repository.
Sandbox enabled	Chooses sandboxed execution versus Off — no isolation layer direct host execution.
Outbound network	Enables or blocks network access for sandboxed commands; disabled when sandboxing is off.
Allowed repository roots	Shows recognized repository roots; the UI displays this list but does not edit it.
Blocked command patterns	Shows destructive command patterns; the UI displays this list but does not edit it.

The UI saves the full loaded policy so list fields are preserved even when the user only toggles a switch.

MCP sandbox policy tools

Tool	What it does
sandbox_policy_get	Gets the sandbox policy for a repository. The repository path is optional.
sandbox_policy_set	Sets shell access for a repository by repository_path and shell_enabled, then returns Sandbox policy updated successfully.

The MCP setter is narrower than the web UI. It changes shell enablement; it does not expose every policy field the UI can round-trip. Use the web UI when reviewing sandbox mode, network posture, allowed roots, and blocked patterns together.

Direct mode and network mode

When Sandbox enabled is off, commands run directly on the host with no isolation layer. Direct mode is not sandbox isolation and should be limited to trusted or disposable environments.

When sandboxing is on, Outbound network controls sandboxed command network access. In production, cluster network policy and sandbox infrastructure also enforce the lower-level boundary.

Web and MCP parity

• Web Diagnostics and MCP diagnostics_get report live diagnostics facts. The web page adds project scope, cards, durations, and auto-refresh.
• Web Heartbeat and MCP heartbeat_status report heartbeat state. The web page adds automation cards, recent tick history, error display, and auto-refresh.
• Web project Settings and MCP sandbox_policy_get/sandbox_policy_set touch repository sandbox policy. The web UI exposes the full displayed policy; the MCP setter changes shell enablement.
• Web Flow has no dedicated MCP tool. MCP clients inspect board, run, and orchestration state through backlog, run, and coordinator tools.

Humans get visual scanning and judgment points. Assistants get compact tools for reporting and narrow safe mutations.

Edge cases and how to read them

Heartbeat disabled

If Heartbeat shows disabled, background pickup is off. Ready tasks remain ready until work starts another way or heartbeat is enabled in runtime configuration. Diagnostics, Flow, and Settings remain usable.

Waiting for first tick

waiting_first_tick means heartbeat is enabled but has not completed a tick in this process lifetime. It is expected immediately after startup. If it persists beyond the interval, check Last error and then Diagnostics.

No ticks recorded yet

No ticks recorded yet. usually means first tick has not completed, the API process recently started, or heartbeat is disabled.

Empty diagnostics

No checks reported. means the selected diagnostics response contained no check rows. Treat it as a visible source gap, not a hidden success. Re-run, switch scope, and compare with MCP diagnostics_get if needed.

Diagnostics warn or fail

Warnings and failures are normal operational outputs. A missing GitHub CLI auth state can warn. An unreadable workspace or failed active workflow can fail at project scope. Read the check detail before changing settings.

No active agents in Flow

No active agents means there is no current agent queue projection. It can mean no active coordinator runs, heartbeat has not claimed Ready work yet, all work is complete, or the project has no current subtask projection.

Selected agent has no active work

No active work for {agent} means that agent has no current in-flight subtasks. Clear the filter to see other agents, or use the archive for terminal work.

Sandbox policy cannot load or save

Policy errors appear inline as API errors. Check the repository path, project working directory, caller authorization, and backend workspace access.

Network switch disabled

Outbound network is disabled when Sandbox enabled is off because network policy applies to sandboxed execution, not direct host execution.

Practical playbooks

Ready work is not starting

1. Confirm work is in Ready on the board.
2. Open Heartbeat and check status, interval, last tick, and recent activity.
3. If status is waiting_first_tick, wait one interval or select Refresh.
4. If status is disabled, heartbeat pickup is not running.
5. If ticks happen with zero acted count, review backlog settings and task eligibility in Workflows & backlog.
6. Open Diagnostics for storage, configuration, heartbeat, and project checks.

Agents are active but work feels stuck

1. Open Flow.
2. Look for blocked counts or one agent with a large queued load.
3. Select View orchestration from the relevant card.
4. Inspect topology, child runs, timeline, questions, approvals, RAI flags, failures, and review gates.
5. Use the agent filter and Previous work archive when the same agent repeatedly fails or declines work.

A command should not be allowed

1. Open project Settings → Sandbox policy.
2. Confirm Shell execution is correct.
3. Keep Sandbox enabled on unless the environment is explicitly trusted.
4. Set Outbound network to blocked when network is not needed.
5. Review Blocked command patterns.
6. Use sandbox_policy_get when an assistant needs to report policy before acting.

Assistant-driven operations check

A good MCP sequence is:

1. diagnostics_get for system health;
2. heartbeat_status for background automation;
3. sandbox_policy_get for the target repository when command execution matters;
4. summarize pass/warn/fail checks, heartbeat state, interval, last tick, and shell enablement;
5. call sandbox_policy_set only when the user specifically wants shell execution changed for that repository.

Limits and source of truth

Operations pages are snapshots and projections over backend state. They do not replace deployment configuration, cluster telemetry, source-control review, or lower-level sandbox enforcement. The backend API remains authoritative; the web UI renders it, and MCP tools forward structured operations to it.

Cluster page experience

The Cluster page is the SYSTEM-section operations view for Kubernetes cluster health. It is available under the Cluster nav item (Server24Regular icon) at /projects/:projectId/cluster.

The page provides:

• KPI cards — Orphaned pods, Pending capacity, Checks healthy, and Warm pool ready when pool data exists
• Resource topology — Runtime by default, with optional networking, workloads, storage, autoscaling, and availability layers. There are no CPU/memory quota bars or separate active-pod table.
• Component health table — 5 checks: Postgres, Azure Key Vault, agent-pod quota headroom, warm-pool, Kubernetes API server
• Sandbox claims and Warm pools — bound/pending claims and ready/desired pool capacity
• Orphaned agent pods table — pods with no matching active run (will be reaped on the next sweep)
• Pending-capacity runs table — historical PendingCapacity records, not the current Kubernetes scheduling queue. A zero count does not prove every live claim has bound.

Kubernetes owns scheduling. Namespace quota bounds pod/claim/PVC counts and storage, not CPU/memory; current claim state and sandbox.provisioning_pending events explain a live scheduling wait.

The page auto-refreshes every 30 seconds by default. When the API is not deployed on AKS (or the cluster diagnostics endpoint returns 404), the page falls back gracefully and shows a message indicating cluster diagnostics are unavailable.

Full user guide: see Cluster page guide for a walkthrough of each KPI and how to interpret quota warnings. API reference: see Cluster diagnostics reference for the full response schema.

See also

• Token usage monitoring — project and app-level AI Credit dashboards, part of the broader operations picture.

Diagram details and constraints

Element	Contract
title	Choose the right operations surface
takeaway	Inspection and configuration have different scopes; MCP parity is intentionally partial.
group-title-0	INSPECT CURRENT STATE
group-title-1	CONFIGURE WITH THE RIGHT AUTHORITY
Diagnostics	Diagnostics
Diagnostics	Health and checks
Diagnostics	diagnostics_get
Diagnostics	Inspect explicit failures and unknown timed-out checks.
Heartbeat + Flow	Heartbeat + Flow
Heartbeat + Flow	Pickup and orchestration
Heartbeat + Flow	heartbeat_status
Heartbeat + Flow	Automation reports pickup; Flow shows ongoing work.
Cluster + traces	Cluster + traces
Cluster + traces	Capacity and observability
Cluster + traces	REST-backed UI views
Cluster + traces	No dedicated Cluster or Observability MCP tools.
Account settings	Account settings
Account settings	Authentication / AI access
Account settings	GitHub / MCP clients
Account settings	Not a repository-path sandbox-policy editor.
Platform settings	Platform settings
Platform settings	Model provider controls
Platform settings	platform administrator
Platform settings	Global provider configuration requires admin authority.
Project settings	Project settings
Project settings	Repository / sandbox
Project settings	project-scoped policy
Project settings	Preview approval and lifetime; MCP setter is narrower.
note	All surfaces use authorized API operations. sandbox_policy_set changes repository shell_enabled only.
n0	Inspect explicit failures and unknown timed-out checks.
n1	Automation reports pickup; Flow shows ongoing work.
n2	No dedicated Cluster or Observability MCP tools.
n3	Not a repository-path sandbox-policy editor.
n4	Global provider configuration requires admin authority.
n5	Preview approval and lifetime; MCP setter is narrower.
groups	INSPECT CURRENT STATE; CONFIGURE WITH THE RIGHT AUTHORITY

Diagram details and constraints

Element	Contract
title	One won claim, one reserved run
takeaway	Ready pickup commits claim and reservation before activation; other outcomes do not launch.
group-title-0	SELECTION AND ATOMIC RESERVATION
group-title-1	POST-CLAIM OUTCOMES
Ranked Ready tasks	Ranked Ready tasks
Ranked Ready tasks	Heartbeat candidates
Ranked Ready tasks	eligible project + workspace
Ranked Ready tasks	Top-N limits candidates per tick, not total concurrency.
Atomic transaction	Atomic transaction
Atomic transaction	Claim + run + policy
Atomic transaction	task-scoped reservation
Atomic transaction	Commit all together; no orphan losing run.
Activate winner	Activate winner
Activate winner	Use reserved run ID
Activate winner	post-commit activation
Activate winner	Schedule unattended confirm attributed to CapturedBy.
Lost / unavailable	Lost / unavailable
Lost / unavailable	No launch by this pickup
Lost / unavailable	rollback / preserve rank
Lost / unavailable	A winner may own a lost claim; unavailable leaves Ready.
Claimed failed run	Claimed failed run
Claimed failed run	Visible failure reason
Claimed failed run	preflight / activation failure
Claimed failed run	Do not silently requeue. Terminalization may log failure.
Coordinator work	Coordinator work
Coordinator work	Unattended execution
Coordinator work	claim-time policy snapshot
Coordinator work	No second manual start for the same captured goal.
e0	attempt
e1	won
e2	not won
e3	activate
e4	failure
note	A won preflight-failure reservation also stays Claimed/Failed. Claim-once is not tool-execution-once.
n0	Top-N limits candidates per tick, not total concurrency.
n1	Commit all together; no orphan losing run.
n2	Schedule unattended confirm attributed to CapturedBy.
n3	A winner may own a lost claim; unavailable leaves Ready.
n4	Do not silently requeue. Terminalization may log failure.
n5	No second manual start for the same captured goal.
groups	SELECTION AND ATOMIC RESERVATION; POST-CLAIM OUTCOMES