Skip to content

Agentweaver experience overview ​

Agentweaver has two product surfaces: the web UI for people who need a visual, real-time control room and the MCP server for AI clients. This overview explains how the surfaces work together.

Scope note: this is an orientation document for using Agentweaver. It describes what the user sees and does; implementation details live in the architecture deep dives.

The two surfaces ​

Agentweaver exposes one product through two front doors:

  • The web UI is for humans. It is visual, navigable, and real-time. A user signs in, chooses a project, watches boards and timelines update, opens files, reviews output, steers coordinators, and changes project settings.
  • The MCP server is for MCP clients such as Claude, Copilot, or other AI assistants. A client connects, authenticates, and invokes tools such as project_create, coordinator_start, run_watch, team_cast, and memory_search.

They are two front-ends over the same backend and data model. Projects, runs, coordinator orchestration, team rosters, memory, workflows, backlog items, sandbox policy, diagnostics, and workspace files are authoritative on the backend. The web UI renders those facts as pages, cards, graphs, timelines, and forms. The MCP server exposes the same facts and mutations as tools. Most actions a person performs in the web UI have a corresponding MCP tool an assistant can call.

The web UI and MCP server differ in interaction style, not in product intent:

SurfaceBest userInteraction styleWhat it is best at
Web UIHuman operators, reviewers, project ownersClick, inspect, compare, approve, steerSeeing state, understanding context, making judgment calls, watching live work
MCP serverAI assistants, automation agents, scripted clientsConnect, authenticate, call toolsCreating and updating work programmatically, chaining operations, asking an assistant to operate Agentweaver for you

Shared experience model ​

The core loop is the same from either surface:

  1. Choose or create a project. A project binds Agentweaver to a working directory or GitHub repository and records project-level settings.
  2. Define work. Capture a backlog task or start a coordinator goal.
  3. Run agents. A run executes through a workflow pipeline and emits events as it moves through agent work, RAI, review, merge, and scribe steps.
  4. Watch progress. The UI shows live timelines and graphs; MCP clients call status and watch tools.
  5. Review and decide. Humans approve or reject work, steer agents, merge memory decisions, or change settings.
  6. Capture learning. Team decisions, agent memory, and session context keep future work aligned.

Agentweaver treats the backend as the source of truth. The web UI loads snapshots for current state and consumes live run streams for what changes after the page opens. MCP tools call the same backend operations and return structured results the client can reason over.

For a live stream, the browser initiates the HTTP request; event payloads flow from API to browser. run_watch likewise consumes API events and reports them through MCP to the assistant. Neither stream makes the client authoritative for run state (apps/web/src/api/sse.ts:237, apps/Agentweaver.Mcp/Tools/RunTools.cs:229).

Web UI mental model ​

Overview ​

The signed-in Overview page has four user-visible regions sourced from API calls (apps/web/src/pages/OverviewPage.tsx:365-389):

  • Recent projects links recently active projects with operational counts and queue pressure.
  • AI usage & performance aggregates metrics for those recent projects, with a 7d/30d/90d selector. It is not an unqualified total for every project.
  • Activity feed groups recent activity by day and shows an empty state when no rows exist.
  • Needs attention surfaces health and work requiring attention rather than fabricating healthy activity.

Open Overview at /overview to inspect these live regions. The page polls and offers manual refresh; an empty or unavailable metric is not a screenshot of successful work.

The web UI is a signed-in, project-aware control room. It uses a persistent app shell for navigation, project switching, API health, the signed-in account, and starting work. Entra identity remains distinct from connected GitHub capabilities.

The app shell ​

The shell has three persistent areas:

  • Left navigation rail — global destinations always appear at the top; project-scoped sections appear when Agentweaver has a project context. The rail can collapse to icon-only mode.
  • Top bar — contains the project switcher and API reachability status.
  • Main content area — renders the selected page.

The project switcher lists existing projects, groups recent projects, and preserves the current page category when switching projects where possible. For example, switching projects from Settings lands on the target project's Settings page; switching from an orchestration detail lands on the target project's Orchestrations page.

Global pages do not require a project id. When a user leaves a project for a global page, the shell remembers the last active project so project-scoped navigation still has useful targets.

Agentweaver's web UI is organized into global destinations plus four project-scoped sections: WORK, SQUAD, OPERATIONS, and SYSTEM.

Global ​

DestinationRoute shapeWhat you do here
Overview/ and /overviewInspect Recent projects, AI usage & performance, Activity feed, and Needs attention.
Projects/projectsBrowse projects, create a blank project, create a project from GitHub, choose a blueprint, and open a project.
Sessions/sessionsStart or open Assistant conversations across projects.
Assistant/assistantContinue a personal conversation; optional project context does not make it a project work-focus session.
Account settings/settingsInspect authentication, AI access, GitHub connections, and MCP client setup.
Platform settings/platform-settingsPlatform Admin controls, including deployment AI source configuration.

WORK ​

DestinationRoute shapeWhat you do here
Dashboard/projects/:projectIdReview selected-range delivery metrics, active work, and the agent leaderboard.
Board/projects/:projectId/boardUse Backlog, Ready, Active, and Done lanes plus Human Review and Problems attention groups; start work and open run details.
Flow/projects/:projectId/flowSee what each agent is working on now, including active, queued, blocked, and done counts grouped by agent and orchestration.
Orchestrations/projects/:projectId/orchestrationsList coordinator runs for the project and open the topology view for a multi-agent goal.
Workspace/projects/:projectId/workspaceBrowse the project repository and active run worktrees read-only; inspect files and decompose a spec file into backlog tasks.

SQUAD ​

DestinationRoute shapeWhat you do here
Agents/projects/:projectId/teamManage the cast working on the project: inspect agents, view charters and capabilities, add members, retire members, re-role agents, and open the casting wizard.
Memories/projects/:projectId/memoriesReview Decisions, Agent memory, and project Session history; acceptance requires appropriate authority.
Skills/projects/:projectId/skillsBuild a per-project skill catalog, inspect provenance and status, and assign active skills to individual agents.

OPERATIONS ​

DestinationRoute shapeWhat you do here
Workflows/projects/:projectId/workflowsView reusable pipeline definitions, validate discovered workflows, sync from disk, generate a workflow, create a workflow, edit YAML, use the visual editor, and choose a project default.

SYSTEM ​

DestinationRoute shapeWhat you do here
Diagnostics/projects/:projectId/diagnosticsRun real diagnostics checks, switch between global and project scope, and inspect pass/warn/fail details with durations.
Heartbeat/projects/:projectId/heartbeatMonitor background automation status, coordinator heartbeat, checkpoint GC, recent ticks, errors, and service cadence.
Cluster/projects/:projectId/clusterInspect pod claims, cluster health, and live resource topology.
Observability/projects/:projectId/observabilityInspect project metrics and selected-range telemetry.
Observability > Agents/projects/:projectId/observability/agentsInspect the agent-level metrics breakdown.
Observability > Traces/projects/:projectId/observability/tracesPreview hierarchical transaction traces for recent coordinator runs.
Settings/projects/:projectId/settingsChange project configuration and policies; separate from Account and Platform settings.

Deep project destinations ​

Standalone workflow and execution pages are not part of the web UI. Run details appear in the coordinator orchestration page.

DestinationRoute shapeWhat you do here
Coordinator run/projects/:projectId/orchestrations/:runIdWatch a coordinator topology, confirm or revise the outcome spec, inspect work plan and child runs, steer agents, view assembly status, and review collective output.
Casting wizard/projects/:projectId/team/castPropose and confirm a project team using templates, goals, constraints, team size, and generated member charters.

Common web journey: project → board → orchestration → review ​

Most human work starts with a project and ends with review:

A typical path looks like this:

  1. The user opens Projects, creates or selects a project, and lands on Dashboard.
  2. The user opens Board to see backlog and run buckets.
  3. The user chooses Define Outcome for a reviewable outcome-spec gate, or Direct to start without that gate. Alternatively, the user promotes queued work to Ready for unattended pickup; that is not a reason to manually start the same goal again.
  4. Agentweaver opens the orchestration detail page. The user sees the coordinator graph, embedded child sessions, tool and shell approval cards, file artifacts, and status badges.
  5. If the run reaches human review, the user approves or rejects it. If the coordinator reaches a confirmation gate, the user confirms or revises the outcome spec before child work is dispatched.
  6. After completion, the user reviews artifacts, memory, decisions, and board state.

The UI is optimized for judgment: seeing state, reading output, understanding why a run is blocked, comparing files, approving work, and steering the coordinator at the right time.

MCP mental model ​

The MCP server turns Agentweaver into a tool catalog for AI assistants. Instead of clicking through pages, an MCP client connects to Agentweaver and calls tools grouped by domain.

Connect and authenticate ​

Agentweaver supports two MCP transport shapes:

  • Hosted HTTP mode exposes /mcp as a protected network resource. An MCP client discovers OAuth metadata, authenticates with Agentweaver's authorization flow, receives a bearer token for the MCP resource, and calls tools with that token.
  • Local stdio mode is for MCP hosts that spawn the server process locally and communicate over standard input/output. It is suited to local single-user setups and does not use the hosted HTTP bearer challenge path.

In hosted mode, the MCP server is a thin Resource Server. It validates access at the MCP boundary, dispatches the requested tool, and forwards the caller's bearer token to the Agentweaver API so backend authorization sees the real user. The API remains authoritative for projects, runs, memory, team, workflow, backlog, and operations.

Tool catalog by goal ​

The tool catalog is broad because it mirrors the product model. Use the generated MCP tool index and the connected server's tools/list instead of a manually maintained tool count. The table below is a goal map, not a full catalog.

Tool groupUser goal it servesRepresentative tools
BacklogCapture, organize, promote, archive, and decompose work on the project board.backlog_capture_task, backlog_get_board, backlog_move_to_ready, backlog_set_settings, backlog_decompose_spec
BlueprintStart from predefined or generated project blueprints that bundle roster, workflow, review, and sandbox choices.list_blueprints, validate_blueprint, blueprint_generate
CatalogDiscover reusable agent roles and casting scenarios.catalog_list_roles, catalog_list_scenarios
CoordinatorDrive multi-agent work from a plain-language goal through outcome spec, work plan, child runs, topology, and steering.coordinator_start, coordinator_outcome_spec_confirm, coordinator_work_plan_get, coordinator_children_get, coordinator_steer, orchestration_topology
DiagnosticsInspect system health and background heartbeat state.diagnostics_get, heartbeat_status
GitHub capabilityConnect or remove a caller's Repo App and an Owner-authorized project's Copilot App capabilities.github_repo_app_connect, github_repo_app_authorization_status, github_repo_app_disconnect, project_copilot_app_connect, project_copilot_app_authorization_status, project_copilot_app_disconnect, project_github_capability_status
MemoryCapture and govern decisions, inbox entries, agent memory, session context, and file import/export.decision_inbox_submit, decision_inbox_merge, decision_list, memory_record, memory_search, session_start, memory_export
ProjectList, create, inspect, configure, rename, delete projects, and list project runs.project_list, project_create, project_get, project_configure, project_list_runs
RunWatch, review, inspect artifacts, retry, and archive runs.run_status, run_watch, run_review, run_show_artifacts, run_get_file, run_retry
SandboxPolicyRead or change the sandbox policy for a repository.sandbox_policy_get, sandbox_policy_set
SkillsAcquire project skills and assign them to agents.skill_list, skill_import_preview, skill_import, skill_assign, skill_assignments_list
TeamCast a team, inspect roster, add or retire members, and fetch charters.team_get, team_cast, team_member_add, team_member_retire, team_member_get_charter
WorkflowList, inspect, sync, generate, and save reusable workflow definitions.workflows_list, workflow_get, workflows_sync, workflow_generate, workflow_save
WorkspaceBrowse project workspace refs, file trees, and file contents.list_project_workspace_refs, list_project_workspace, get_project_workspace_file

MCP flow: assistant-driven work ​

An assistant typically uses MCP in a loop like this:

The assistant can perform long chains quickly: create a project, apply a blueprint, cast a team, capture backlog, start a coordinator, poll topology, inspect artifacts, and submit memory. The human still owns judgment points: confirming outcome specs, approving risky actions, reviewing output, and deciding whether a team decision should become durable memory.

UI ↔ MCP mapping ​

The table below maps major user goals to where a person goes in the web UI and which MCP tools an assistant uses for the same work.

User goalWeb UI destinationMCP tool equivalents
Create a projectProjects → Create blank project or Create from GitHub; optionally choose a blueprint.project_create, plus list_blueprints, validate_blueprint, or blueprint_generate when using a blueprint.
Find or open a projectOverview for active projects or Projects gallery for all projects; project switcher for recent/all projects.project_list, project_get.
Configure a projectSettings → General for name and default model.project_configure, project_rename, project_delete.
Set sandbox behaviorSettings → Sandbox policy.sandbox_policy_get, sandbox_policy_set.
Inspect review gatesWorkflows for definitions and Coordinator run for active review; the current Settings rail has no Review policy tab.workflows_list, workflow_get, and workflow_save for workflow-level gates; run_review for execution-time review decisions. No dedicated review-policy settings tool is implied.
Start coordinator workBoard → Start task and open the coordinator run.coordinator_start.
Watch a runCoordinator run and the selected task's Agent session panel.run_status, run_watch.
Review or approve a runCoordinator run → human review and artifacts.run_review (approve or decline).
Inspect run artifactsOrchestration or selected-task artifacts and diff/content panels.run_show_artifacts, run_get_file.
Retry or archive a runBoard or run lists for active/terminal run management.run_retry, run_archive, backlog_archive_task.
Coordinate a multi-agent goalBoard → start orchestration, or floating start-orchestration action; then Orchestrations / coordinator detail.coordinator_start.
Confirm or revise coordinator intentCoordinator run → outcome spec panel.coordinator_outcome_spec_get, coordinator_outcome_spec_confirm, coordinator_outcome_spec_revise.
Understand coordinator topologyCoordinator run → Coordinator Graph, child runs, agent rail, assembly panels.coordinator_work_plan_get, coordinator_children_get, orchestration_topology, run_watch.
Steer active coordinator workCoordinator run → steer controls for recover, redirect, amend, and stop.coordinator_steer.
Manage team / cast agentsAgents and Casting wizard.team_get, team_cast, team_member_add, team_member_retire, team_member_get_charter, plus catalog_list_roles and catalog_list_scenarios.
Manage decisions and memoryMemories → Decisions and Agent memory tabs.decision_inbox_submit, decision_inbox_list, decision_inbox_merge, decision_inbox_reject, decision_create, decision_list, decision_update, squad_decide, memory_record, memory_list, memory_get, memory_search.
Manage session contextMemories → Session history for project work focus, distinct from global Assistant conversations.session_start, session_current, session_update.
Import/export memory filesMemories and workspace-backed team context.memory_export, memory_import.
Manage workflowsWorkflows page: list, sync, generate, create, edit YAML, visual editor, set default.workflows_list, workflow_get, workflows_sync, workflow_generate, workflow_save.
Manage backlogBoard kanban columns and Workspace spec decomposition.backlog_capture_task, backlog_edit_task, backlog_delete_task, backlog_get_board, backlog_move_to_ready, backlog_move_to_backlog, backlog_reorder_task, send_all_backlog_to_ready, backlog_get_workflow_stages, backlog_get_settings, backlog_set_settings, backlog_decompose_spec.
Browse workspace filesWorkspace page: select base branch or active run worktree, open file tree, inspect file content.list_project_workspace_refs, list_project_workspace, get_project_workspace_file.
Operate and diagnoseDiagnostics, Heartbeat, Cluster, and Observability.diagnostics_get, heartbeat_status; no dedicated Cluster or full Observability tool parity is implied.
Manage GitHub capabilityConnect the Repo App in a browser; Project Owners can also connect the project Copilot App.github_repo_app_connect, github_repo_app_authorization_status, github_repo_app_disconnect, project_copilot_app_connect, project_copilot_app_authorization_status, project_copilot_app_disconnect, project_github_capability_status.

Which surface should I use? ​

Use the web UI when the task benefits from visual context or human judgment:

  • You need to see the board and decide what matters next.
  • You are reviewing a run, approving work, rejecting output, or reading file changes.
  • You are steering a coordinator and want to understand topology, child status, and assembly state.
  • You are managing a team roster, inspecting charters, or comparing agent capabilities.
  • You are diagnosing system state and want pass/warn/fail cards, recent ticks, and live refresh.

Use the MCP server when the task benefits from assistant-driven execution or automation:

  • You want an AI assistant to create or configure projects.
  • You want to capture backlog, submit runs, or coordinate a goal from natural language.
  • You want a client to watch progress, summarize state, and ask you only when judgment is required.
  • You want to script repeatable operations across projects, runs, workflows, memory, or diagnostics.
  • You want an assistant to inspect workspace files and run artifacts without manually navigating the UI.

Use both for complex work. A common pattern is: ask an MCP client to start and monitor work, then open the web UI when a review, approval, topology question, file inspection, or operational diagnosis needs human attention.

Experience principles ​

One backend, two front-ends ​

Agentweaver avoids split-brain behavior by keeping durable state in the backend. The web UI does not invent project state, run state, topology, memory, or workflow definitions. The MCP server does not become a separate business service. Both surfaces ask the backend for facts and submit user-authorized mutations.

Human control at decision points ​

Agentweaver lets agents do work, but the experience keeps important decisions visible. Outcome specs are confirmable. Human review is explicit. Coordinator steering is a first-class control. Decision inbox entries can be merged or rejected. Sandbox and review policies are configurable project settings.

Live work is observable ​

Runs are eventful. The UI presents streams as timelines, graph state, topology, status badges, approval cards, file artifacts, and assembly panels. MCP clients use run_watch, run_status, and topology tools to observe the same work in a machine-readable way.

Project context stays stable ​

The shell keeps project navigation, switching, health, and identity visible across pages. Deep links are normal URLs for supported pages such as orchestration details. Project switching preserves category when possible. Global pages keep enough remembered project context to make navigation feel continuous.

Teams and memory shape future work ​

Agentweaver treats the squad as part of the product, not just a runtime detail. Agents have roles, charters, capabilities, and histories. Decisions and memory turn learning into durable context. This gives both the web UI and MCP clients a shared way to align future work.

Use this overview as the hub for the experience documentation set:

Diagram details and constraints
ElementContract
titleOne goal, one collective review
subtitleConfirm intent, dispatch bounded work, then integrate and review the whole result.
group-title0Plan and execute
group-title1Integrate, review, finish
Confirm intentConfirm intent
Confirm intentDraft the OutcomeSpec
Confirm intenthuman confirmation
Plan the workPlan the work
Plan the workPersist a WorkPlan DAG
Plan the worksubtasks + dependencies
Dispatch childrenDispatch children
Dispatch childrenRun the eligible frontier
Dispatch childrenper-child worktrees
Merge + ScribeMerge + Scribe
Merge + ScribeApproved integration path
Merge + ScribeMergeWorktree → Scribe
Collective reviewCollective review
Collective reviewOne human decision
Collective reviewapprove / revise / decline
Integrate + gatesIntegrate + gates
Integrate + gatesAssemble child branches
Integrate + gatesconfigured checks / review
e1confirm
e2dispatch
e3settled work
e4request review
e5approve
assurance-titleDO NOT CONFUSE ASSEMBLY WITH PUBLICATION
assurance-line1The collective workflow reaches MergeWorktree and Scribe; this graphic does not promise PR creation.
assurance-line2A blocked assembly can be recovered. Review approval does not itself mark the run complete.
Confirm intentInput
Confirm intentHuman goal
Confirm intentArtifact
Confirm intentOutcomeSpec
Confirm intentGate
Confirm intentConfirm or revise
Confirm intentScope
Confirm intentExplicit assumptions
Plan the workSelect
Plan the workWorkflow choice
Plan the workWorkPlan DAG
Plan the workOwners
Plan the workNamed subtasks
Plan the workStore
Plan the workPersist dependencies
Dispatch childrenReady
Dispatch childrenSatisfied dependencies
Dispatch childrenFiles
Dispatch childrenChild-owned worktree
Dispatch childrenObserve
Dispatch childrenChild status / results
Dispatch childrenFailure
Dispatch childrenBlocks dependents
Merge + ScribeMerge
Merge + ScribeReviewed integration
Merge + ScribeThen
Merge + ScribeCollective Scribe
Merge + ScribeRecord
Merge + ScribePromote decisions
Merge + ScribeDecline
Merge + ScribeSkips Scribe
Collective reviewApprove
Collective reviewProceed to merge
Collective reviewRevise
Collective reviewSteer / redispatch
Collective reviewNo Scribe path
Collective reviewBlocked
Collective reviewRecoverable state
Integrate + gatesChild branches
Integrate + gatesTarget
Integrate + gatesIntegration branch
Integrate + gatesGates
Integrate + gatesSelected checks
Integrate + gatesOutput
intentScope and assumptions are explicit; Revision reopens the intent gate
planOutcome-complete decomposition; Bounded work with named owners
dispatchObserve child status and results; Failure / RAI blocks dependents
finishDecline skips Scribe; No automatic PR claim here
reviewChanges can redispatch work; Blocked is recoverable, not terminal
integrateCollective—not per-child delivery; Merge failure may still run Scribe
notesDO NOT CONFUSE ASSEMBLY WITH PUBLICATION; The collective workflow reaches MergeWorktree and Scribe; this graphic does not promise PR creation.; A blocked assembly can be recovered. Review approval does not itself mark the run complete.
groupsPlan and execute; Integrate, review, finish
Diagram details and constraints
ElementContract
titleTwo front doors, one product
takeawayWeb and MCP share authorization and authoritative state; events flow back to clients.
group-title-0PEOPLE AND CLIENTS
group-title-1AUTHORITATIVE BACKEND
Human operatorHuman operator
Human operatorInspect and decide
Human operatorbrowser or assistant
Human operatorChoose the interface, not a different product.
Web UIWeb UI
Web UIProject and run views
Web UIREST + stream request
Web UIOpens the watch request; receives API event payloads.
MCP clientMCP client
MCP clientAssistant tool caller
MCP clienttool result + progress
MCP clientMakes explicit tool calls; surfaces decisions to people.
Product stateProduct state
Product stateProjects, teams, runs
Product stateknowledge + workspaces
Product stateAPI-authorized reads and mutations; no MCP bypass.
Agentweaver APIAgentweaver API
Agentweaver APIAuthorization boundary
Agentweaver APIrun snapshots + events
Agentweaver APIOwns resource checks and access to product state.
MCP serverMCP server
MCP serverAuthenticated adapter
MCP servervalidated broker bearer
MCP serverForwards the exact caller token to the API.
e0inspect
e1requests
e2SSE events
e3tool call
e4result
e5forward
e6API result
e7access
noteBrowser opens the connection; API sends event payloads. MCP results return through MCP.
n0Choose the interface, not a different product.
n1Opens the watch request; receives API event payloads.
n2Makes explicit tool calls; surfaces decisions to people.
n3API-authorized reads and mutations; no MCP bypass.
n4Owns resource checks and access to product state.
n5Forwards the exact caller token to the API.
groupsPEOPLE AND CLIENTS; AUTHORITATIVE BACKEND
Diagram details and constraints
ElementContract
titleAssistant-driven work
takeawayChoose one intake path, inspect the result, and preserve explicit human decisions.
group-title-0PREPARE AND CHOOSE
group-title-1OPERATE AND REVIEW
Human + assistantHuman + assistant
Human + assistantAgree on the work
Human + assistantMCP calls -> API
Human + assistantThe assistant explains actions; a person supplies judgment.
Project and teamProject and team
Project and teamInspect or create
Project and teampropose -> confirm cast
Project and teamNamed roles and charters belong to the project.
Choose intakeChoose intake
Choose intakeQueue OR start now
Choose intakedo not start twice
Choose intakeReady pickup is an alternative to an immediate start.
Human reviewHuman review
Human reviewRead before deciding
Human reviewrun_review: boolean
Human reviewMCP approve/decline is binary. Feedback uses other surfaces.
State and artifactsState and artifacts
State and artifactsWatch, list, read
State and artifactsAPI -> MCP -> client
State and artifactsProgress and results return through the MCP adapter.
CoordinatorCoordinator
CoordinatorRuns and child work
Coordinatorstatus / children / watch
CoordinatorQueued: claim then unattended. Direct: no outcome gate.
e0prepare
e1choose
e2start once
e3observe
e4inspect
noteDefine Outcome is the third start variant: draft, obtain authorized confirmation, then dispatch.
n0The assistant explains actions; a person supplies judgment.
n1Named roles and charters belong to the project.
n2Ready pickup is an alternative to an immediate start.
n3MCP approve/decline is binary. Feedback uses other surfaces.
n4Progress and results return through the MCP adapter.
n5Queued: claim then unattended. Direct: no outcome gate.
groupsPREPARE AND CHOOSE; OPERATE AND REVIEW