DocsNew Run
MACP UI Console

Orchestrate, observe, and debug
multi-agent runs.

The Console is the operator surface for MACP. Launch scenarios, watch live runs over SSE, inspect the canonical event stream, and explore historical analytics — all against the Examples Service and Control Plane, or against a rich local demo dataset.

Try demo modeRead the docs

Orchestration launchpad

Browse scenario packs, fill a schema-driven launch form, compile with the Examples Service, and submit a whitelisted-safe RunDescriptor to the Control Plane.

Live run observability

SSE-backed execution graph, node inspector, signal rail, live decision panel, and policy governance — all updated as canonical events arrive.

Historical analysis

Run history, pairwise comparison, Prometheus metrics with percentile KPIs, circuit breaker timeline, and Jaeger trace deep-links when configured.

Architecture

The browser never calls upstream services directly. A Next.js route-handler proxy injects auth and forwards. The Control Plane observes the Runtime read-only; agents drive the session.

UI Console architectureThe browser calls a Next.js route-handler proxy that forwards to the Examples Service and Control Plane. The Control Plane observes the Runtime read-only; agents authenticate to the Runtime directly via the SDK.BrowserReact 19 UINext.js Route-Handler Proxy/api/proxy/{example,control-plane}Examples Servicecatalog · schema · compile:3000Control Planeobserver · state · SSE:3001gRPC observerRuntimeRust · gRPCAgentsmacp-sdkdirect-agent-authBrowser talks only to the proxy. Agents talk only to the runtime. CP never calls Send.

Under the observer-only Control Plane model (RFC-MACP-0004 §4), agents authenticate directly to the Runtime via macp-sdk-python / macp-sdk-typescript. The Control Plane reads envelopes off a read-only StreamSession and projects them for the UI. The HTTP bypass endpoints (/runs/:id/messages, /signal, /context) are removed and return 410 Gone.

Scenario packs

A pack is a folder of versioned scenarios. Each scenario compiles twin artifacts: a Control-Plane-safe run descriptor, and per-agent bootstrap files.

Scenario pack compilation pipelineA pack contains versioned scenarios. The Examples Service compiles user inputs into twin artifacts: a scenario-agnostic RunDescriptor for the Control Plane, and a bootstrap plus scenarioSpec for the spawned agents.Packpack.yamlScenario@1.0.0Launch Schemainputs · policyHintsCompilePOST /launch/compileRunDescriptorBootstrap + scenarioSpecControl Planeobserver-only · creates run recordAgentsspawned · per-agent JWT + gRPCRuntime sessioninitiator calls SessionStart · CP subscribes read-only · agents drive envelopes
  • Pack — a bundle of related scenarios (e.g. fraud, lending) with metadata in pack.yaml.
  • Scenario version — an immutable scenario.yaml + templates/*.yaml. Inputs are validated against a JSON Schema.
  • Launch Schema — the form the Console renders. Carries defaults, policyHints, participant bindings, and expected decision kinds.
  • Compile — merges schema defaults, template defaults, and user inputs; validates; and produces a pre-allocated sessionId (UUID v4).
  • Twin artifacts — a scenario-agnostic RunDescriptor goes to the Control Plane; a Bootstrap + scenarioSpec is handed to each spawned agent so it can open its gRPC channel and (for the initiator) call SessionStart.

Run flow

From clicking Launch to watching a live run — five steps, three services.

Run launch flowFive steps take an operator from a scenario page to a live run workbench: compile on the Examples Service, validate and submit to the Control Plane, open the SSE stream, and render the workbench.1CompileExamples Service/launch/compile2ValidateControl Plane/runs/validate3SubmitControl PlanePOST /runs4StreamControl Plane/runs/:id/stream5WorkbenchBrowser/runs/live/:id
  1. Compile — POST /launch/compile against the Examples Service.
  2. Validate — POST /runs/validate against the Control Plane (optional but default-on).
  3. Submit — POST /runs with the whitelisted-safe descriptor. Response includes runId, sessionId, traceId.
  4. Stream — the workbench opens GET /runs/:id/stream?includeSnapshot=true (SSE) and consumes snapshot, canonical_event, heartbeat frames.
  5. Workbench — the graph, node inspector, signal rail, and decision panel render from the projection and live event feed.

How the Console uses each service

Examples Service

  • Scenario catalog (`/packs`, `/scenarios`) — powers the catalog + detail pages.
  • Agent profiles (`/agents`) — powers the agent catalog.
  • Launch schema + compile — powers the Launch form and the one-shot bootstrap.

Control Plane

  • Run lifecycle (`/runs`, validate, cancel, clone, archive).
  • State projection + canonical events (per-run and cross-run).
  • SSE live stream — `/runs/:id/stream`.
  • Observability: metrics, traces, audit, readiness, circuit breaker.
  • Runtime manifest / modes / roots and the policy registry (pass-through).

Documentation

Deep-dives for both repos. UI Console docs ship with this app; Examples Service docs are synced from the upstream repo.

UI Console

Browse all →

Architecture, API integration, feature matrix, changelog, and backend repo notes for this app.

Examples Service

Browse all →

Scenario authoring, launch compilation, agent hosting, and the worker bootstrap contract.