Admin Panel

The admin panel gives you monitoring, cost analytics, compliance dashboards, budget controls, and an interactive playground for testing agents and workflows. This guide walks through each section and the API endpoints it uses.

Starting the admin panel

Start the FastAPI backend on port 8000:

just dev-all
# or with Docker:
just compose-up  # starts postgres + redis + backend + admin

Start the Next.js frontend on port 3008:

pnpm --filter @sagewai/admin dev

Open http://localhost:3008.

Architecture

The panel has three layers:

Data stores are in-memory by default. In production, swap to the PostgreSQL-backed implementations by setting SAGEWAI_DATABASE_URL.

Dashboard

URL: /

Six KPI cards give you a snapshot of your agent infrastructure:

• Registered Agents — total agents in the registry
• Total Runs — completed and running agent invocations
• Active Sessions — currently open multi-turn conversations
• Total Tokens — aggregate token usage across all models
• Total Cost — cumulative LLM spend in USD
• Risk Events — PII detections, hallucination flags, and content filter triggers

Below the cards:

• Cost Trend Chart — line chart of cost over time; useful for spotting spend spikes
• Model Usage Chart — pie chart of token distribution by model

API endpoints: GET /admin/agents, GET /admin/runs, GET /admin/sessions, GET /api/v1/analytics/costs, GET /api/v1/analytics/usage, GET /api/v1/analytics/risks

Agent Management

Agent Registry

URL: /agents

Lists all registered agents with these columns:

Agent Detail

URL: /agents/{name}

Shows configuration (model, status, max iterations, total runs), capability tags, available MCP tools, and a preview of the system prompt.

Runtime config updates

Update an agent's configuration without restarting:

curl -X PATCH http://localhost:8000/admin/agents/my-agent/config \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "temperature": 0.5, "max_iterations": 15}'

Updatable fields: model, system_prompt, temperature, max_tokens, max_iterations.

Run History

URL: /runs

Browse all agent invocations. Filter by agent name (text) or status (All / Completed / Running / Failed). Each row shows: Run ID, Agent, Status, Token count, Start timestamp.

Run detail

URL: /runs/{id}

Shows the full run: input, output, each iteration step with type and duration, and each tool call with arguments, result preview, and duration.

Run controls

Pause, resume, or cancel active runs:

Live Sessions

URL: /sessions

Lists all active multi-turn sessions with session ID, agent name, status, message count, and start time. Sessions are created by AdminState.start_session() and removed when end_session() is called.

Observability

Cost Analytics

URL: /analytics/costs

• Budget Alert Banner — appears when an agent is approaching its spend limit
• Stat Cards: Total Cost, API Calls, Models Used, Active Agents
• Cost by Model — horizontal bar chart across providers
• Breakdown Tables — cost by model and by agent, with token counts and request counts

API: GET /api/v1/analytics/costs, GET /api/v1/analytics/models, GET /api/v1/analytics/agents

Model Comparison

URL: /analytics/models

Side-by-side comparison of models in use: request count, total tokens, total cost, cost per 1K tokens. Use this to find which model gives the best cost-to-quality ratio for your workloads.

Execution Monitor

URL: /monitor

Real-time monitoring via Server-Sent Events (SSE). Connect or disconnect the stream, filter by agent, select a run from the sidebar, and watch the event timeline. Event types: run_started, text_message_start, text_message_content, tool_call_start, tool_call_end, state_snapshot, run_finished, run_error.

Compliance

PII Compliance Dashboard

URL: /compliance/pii

Tracks PII detection and redaction across all agents:

• Stat Cards: PII Detections, Hallucination Flags, Content Filtered, Total Events
• PII Events Chart — detection frequency over time, with separate lines for PII, hallucination, and content filter
• Entity Breakdown — distribution of detected entity types (EMAIL, PHONE, SSN, CREDIT_CARD, IBAN, IP_ADDRESS, PASSPORT)
• Redaction Actions Table — counts by action taken (Protected / Warned / Blocked)
• Export Audit Report — downloads a compliance report

API: GET /api/v1/analytics/risks

PII detection is powered by PIIGuard. See the PII Protection guide for setup.

Operations

Budget Manager

URL: /operations/budget

Set per-agent daily and monthly spend limits. Each limit has:

• Agent Name
• Max Daily USD and Max Monthly USD
• Action: Warn (log and continue), Throttle (switch to cheaper model), Stop (halt execution)
• Fallback Model Chain — ordered list of models to use when the budget is exceeded

Budget actions

Example: setting up a budget with fallback

1. Go to /operations/budget and click + New Limit.
2. Set agent: my-agent, daily limit: $5.00, monthly: $100.00.
3. Set action: Throttle.
4. Add fallback chain: gpt-4o-mini → gemini-2.0-flash → llama-3.1-8b-instant.
5. Save.

When my-agent exceeds $5/day it switches from its primary model to gpt-4o-mini, then gemini-2.0-flash, then llama-3.1-8b-instant.

Budget API endpoints:

See the Cost Management guide for SDK-level integration.

Tools

Playground

URL: /playground

Test agents interactively without writing code. The left panel lets you set agent name, model, strategy, system prompt, and temperature. The right panel streams the agent's response token-by-token via SSE and shows tool calls inline as they execute.

Available strategies: react, lats, tot, self_correct, planning, routing.

API: POST /playground/agent (create), POST /playground/run (SSE stream).

Strategy Lab

URL: /strategy-lab

Run the same prompt through multiple strategies side by side:

1. Select a model.
2. Optionally set a system prompt.
3. Check the strategies you want to compare.
4. Enter your test prompt and click Run Comparison.

Each result card shows: output, duration (ms), tokens, cost, reasoning steps, and tool call count. A summary bar marks the fastest and cheapest strategy.

API: POST /strategies/compare (SSE stream)

Workflow Builder

URL: /workflows

Visual editor for YAML workflows. The left panel has a template selector, a syntax-highlighted YAML editor, and inline validation. The right panel shows the pipeline graph, a test input, and a live execution log. Templates cover sequential pipelines, parallel fan-out, and loop-until-done patterns.

API: POST /workflows/validate, GET /workflows/templates, POST /workflows/run (SSE stream)

Fleet Management

Workers

URL: /fleet/workers

Lists all registered workers with status badges (online, offline, draining), pool and label filters, model capabilities, approval status, and enterprise badges (IP allowlist, dual approval, WebSocket).

Worker Detail

URL: /fleet/workers/{id}

Three tabs:

• Overview — metadata, pool, labels, model capabilities, probe status (Ollama + OpenAI-compatible), connection history
• Tasks — execution history with status and duration
• Anomalies — alert cards for rate-limit violations, excessive failures, heartbeat timeouts, and model mismatches; auto-revoke triggers on two or more anomaly types

Enrollment Keys

URL: /fleet/enrollment

Create and revoke enrollment keys. Workers use these keys to register via sagewai fleet register or via Docker worker images that read the key from an environment variable.

Audit Log

URL: /fleet/audit

Chronological log of all fleet events. Filter by event type (13 types including registration, approval, dispatch, heartbeat, and anomaly detection), by severity (info / warning / error), or by time range.

Fleet API endpoints: GET /api/v1/fleet/workers, GET /api/v1/fleet/workers/{id}, POST /api/v1/fleet/enrollment-keys, GET /api/v1/fleet/audit

Context Engine

Context Overview

URL: /context

Document counts, chunk counts, and storage metrics split by scope (org-level vs project-level), plus recent ingestion jobs with status indicators.

Documents

URL: /context/documents

• Upload — drag-and-drop or file picker with per-file progress and tag input
• Directory indexing — index a directory via folder picker or by entering a server path
• Search — debounced text search across titles and metadata
• Sort and paginate — sort by name, source, scope, chunk count, or date
• Batch delete — multi-select and delete
• Auto-poll — status updates while ingestion is in progress

Document Detail

URL: /context/documents/{id}

Source type, scope, tags, ingestion timestamp, file size, all extracted chunks with token counts, and language detection results.

Search

URL: /context/search

Choose a retrieval strategy (vector / BM25 / graph / combined RRF), set scope (org-level, project-level, or both), optionally filter by tags, and inspect ranked results with relevance scores and chunk previews.

Lifecycle

URL: /context/lifecycle

Set thresholds for compress, archive, and discard actions based on document age or access frequency. Manually trigger lifecycle operations and resolve conflicting facts detected during re-ingestion.

Directives

URL: /context/directives

Reference for the directive engine syntax: all supported directives (@context, @memory, @agent:name(), @wf:name(), /tool, #meta), dynamic parameters (@datetime, @date, @time, @user, @project), and template syntax ({{ }}).

Context API endpoints: GET /api/v1/context/documents, POST /api/v1/context/documents, DELETE /api/v1/context/documents, POST /api/v1/context/search, GET /api/v1/context/lifecycle

Memory

Vector Store

URL: /memory/vector

Browse Milvus collections, run similarity searches, and inspect collection stats (storage size, index type, segment info).

Knowledge Graph

URL: /memory/graph

Browse entities in the NebulaGraph store, view properties and relations, navigate to neighbors, and inspect edge properties including temporal facts (valid_from, superseded_at).

Graph API endpoints: GET /api/v1/graph/entities, GET /api/v1/graph/entities/{id}/neighbors, GET /api/v1/graph/entities/{id}/relations

Intelligence

Intelligence Dashboard

URL: /intelligence/dashboard

Status of each intelligence component (embedder, language detector, entity extractor, relation extractor, fact extractor, summarizer, transcriber, vision describer), consolidation metrics (semantic dedup count, decay scores, contradiction detection), and the active provider for each component.

LLM Spend

URL: /intelligence/spend

Total cost across all models with trend indicator, per-model breakdown (requests, tokens, cost), a time-range selector, and visibility-based polling that pauses when the tab is hidden.

API: GET /api/v1/analytics/costs, GET /api/v1/analytics/models

Projects and Workspaces

Project Management

URL: /settings/projects

Create and switch projects, each with its own scoped isolation for all data stores. A default project is created on first startup; it cannot be deleted. Multi-project support is a premium feature.

Project Settings

Per-project options:

• LLM proxy virtual key — scoped API key for spend tracking and rate limiting
• Budget config — daily and monthly limits with warn/throttle/stop actions
• Notification overrides — per-project channel config that overrides global SMTP/Slack/SSE settings

Project API endpoints: GET /api/v1/projects, POST /api/v1/projects, PUT /api/v1/projects/{id}

Infrastructure Settings

Infrastructure

URL: /settings/infrastructure

Configure the LLM Proxy (URL and API key), Milvus URI for vector storage, and NebulaGraph host and port. Changes take effect on the next agent invocation without a restart.

Notifications

URL: /settings/notifications

Enable or disable SMTP email, Slack webhook, and in-app SSE channels independently. Per-project overrides are set in the project settings above.

Connectors

URL: /settings/services

18 built-in connectors with health badges (healthy, degraded, disconnected). Each connector has an Overview tab (description, last health check), a Configuration tab (masked credentials, OAuth settings, endpoint URLs), and a Tools tab listing the MCP tools it exposes. Health badges update automatically.

Connector API endpoints: GET /api/v1/connectors, GET /api/v1/connectors/{id}, GET /api/v1/connectors/{id}/health

Eval

Datasets

URL: /eval/datasets

Upload evaluation datasets in JSON format with input/expected-output pairs. The list shows name, sample count, and creation date.

Run Eval

URL: /eval/run

Select a model and one or more datasets, then start the evaluation and watch progress in real time.

Reports

URL: /eval/reports

All completed eval runs with model, dataset, score, and timestamp. Click into a report for per-sample results: input, expected output, actual output, and judge scores.

API: POST /api/v1/eval/run, GET /api/v1/eval/reports

API Reference Summary

For request/response schemas, see the REST API Reference.