Agent View Frontend

React components to support the development of the Agentic MATs initiative.

The UI is designed to work against the AI agent service — not only the local mock server. AgentMonitorKanban is self-contained: give it a jwt, optional headers, and a baseUrl (plus optional per-operation URL props), and it fetches agents and definitions, loads checklists and resources, creates agents, and streams chat via the bundled AI service SDK (AgentServiceClient) against /api/v1/agents/*. The demo ships with presets for mock, local (localhost:8001), and staging backends; see Wiring the UI to the AI service.

Setup

Requirements: Node.js and Yarn.

yarn install
make demo-with-mock

Open http://localhost:4174/. The demo starts in Backend mode and loads agents from the local mock agent service automatically.

To run the demo UI only (no backend — use Debug options to switch to Mock data, Sparse, or Empty):

make demo

Or run the mock server and demo in separate terminals:

# Terminal 1
make mock-server

# Terminal 2
make demo

If you change mock-server code, restart it so the demo picks up API changes.

Use Debug options in the toolbar to switch backends:

| Preset | Service URL | Notes | |---|---|---| | Mock server | /api/ai-agent-service | Local seed data via the demo proxy. Bearer token optional. | | Local AI service | http://localhost:8001 | Real AI agent service on your machine. Bearer token required. | | Staging AI service | https://ai-agent-service.qa.arbor.engineering | QA environment. Bearer token required. |

You can also paste any service origin into the Service URL field (the SDK appends /api/v1/agents/… automatically).

You can also configure the demo without opening the debug panel:

# Via URL query params (token is stripped from the address bar after load)
http://localhost:4174/?serviceUrl=http://localhost:3001&token=your-bearer-token

# Via environment variables
VITE_AGENT_SERVICE_URL=https://ai-agent-service.qa.arbor.engineering \
VITE_AGENT_SERVICE_TOKEN=your-bearer-token \
make demo

| Variable | Default | Purpose | |---|---|---| | MOCK_SERVER_PORT | 3001 | Port for the mock agent service | | VITE_AGENT_SERVICE_PROXY_TARGET | http://localhost:3001 | Where the demo proxies /api/ai-agent-service | | VITE_AGENT_SERVICE_URL | /api/ai-agent-service | Initial service URL for the demo (overridable in Debug options) | | VITE_AGENT_SERVICE_TOKEN | (empty) | Initial bearer token for the demo |

To hit QA instead of the local mock server:

VITE_AGENT_SERVICE_PROXY_TARGET=https://ai-agent-service.qa.arbor.engineering make demo

Scripts

| Command | What it does | |---|---| | yarn demo / make demo | Start the demo app with hot reload | | yarn demo:with-mock / make demo-with-mock | Start mock server + demo together | | yarn mock-server / make mock-server | Start the local AI agent service mock server | | yarn dev / make dev | Alias for demo | | yarn build / make build | Library build → dist/ | | yarn test / make test | Run Vitest test suite | | yarn test:watch / make test-watch | Vitest in watch mode | | yarn check-types / make typecheck | TypeScript check (no emit) | | yarn lint / make lint | ESLint check for TS/TSX | | yarn lint:fix | ESLint with auto-fix | | yarn style-lint / make style-lint | Stylelint check for SCSS | | make check | typecheck + lint + style-lint + test + build | | make clean | Remove dist and Vite cache |

Wiring the UI to the AI service

AgentMonitorKanban owns all AI service orchestration internally. Give it the credentials and endpoint URLs and it does the rest — listing agents/definitions, loading checklists and resources, creating agents, and streaming chat.

In the demo — open Debug options, pick Local AI service or Staging AI service, paste a bearer token, and click Reload board. The demo resolves the Service URL field into baseUrl; see demo/App.tsx (and the URL helpers in demo/backendApi.ts).

In your app — pass jwt, optional headers, and the endpoint URLs:

import { AgentMonitorKanban } from 'agent-view-frontend';
import 'agent-view-frontend/style.css';
import '@arbor-education/design-system.components/dist/index.css';

<AgentMonitorKanban
  jwt={jwt}
  headers={{ 'X-Arbor-Application': 'agent-view' }}
  // Required. Service origin — the SDK appends `/api/v1/<route>`.
  baseUrl="https://ai-agent-service.qa.arbor.engineering"
  // Optional per-operation overrides (full URLs). Parameterised routes
  // substitute the `:invocationId` placeholder, e.g.:
  // agentChecklistUrl="https://…/agents/:invocationId/checklist"
/>;

Each URL is a separate prop. The optional per-operation overrides (agentDefinitionsUrl, agentsUrl, agentUrl, agentChecklistUrl, agentResourcesUrl, agentChatUrl) each fall back to baseUrl + /api/v1 + the route when omitted. See the AI service SDK section for the underlying client, which you can also use directly.

NPM usage

Install the package and its peer dependencies:

yarn add agent-view-frontend @arbor-education/design-system.components react react-dom

Import the component and styles:

import { AgentMonitorKanban } from 'agent-view-frontend';
import 'agent-view-frontend/style.css';
import '@arbor-education/design-system.components/dist/index.css';

function Page() {
  return <AgentMonitorKanban baseUrl="/api/ai-agent-service" />;
}

AI service SDK

The package ships a framework-agnostic client for the AI agent service /api/v1/agents/* endpoints (works against the local mock server or the real AI service).

import {
  AgentServiceClient,
  createHttpChatConnectorFactory,
  mapApiAgent,
  mapApiChecklistResponse,
} from 'agent-view-frontend';

const client = new AgentServiceClient({
  baseUrl: '/api/ai-agent-service', // or 'http://localhost:3001'
  token: jwt,                       // Bearer token; "Bearer " prefix optional
});

// List / detail (mapped into the UI's Agent + checklist shapes)
const agents = (await client.listAgents()).map(mapApiAgent);
const detail = await client.getAgent(invocationId);
const checklist = mapApiChecklistResponse(invocationId, detail);

// Lifecycle
await client.createAgent('school_trip_agents');
await client.cancelAgent(agentId);
await client.archiveAgent(agentId);

// Streaming chat (SSE)
const connectorFor = createHttpChatConnectorFactory(client);
const connector = connectorFor(agents[0]);
const reply = await connector.sendMessage('What have you done so far?');

AgentServiceClient also accepts headers (merged into every request) and per-operation urls overrides — the same options AgentMonitorKanban forwards from its headers and urls props.

client.chat(agentId, request, { onEvent }) resolves with the final SSE event and invokes onEvent per frame. Non-2xx responses and event: error frames throw an AgentServiceError carrying status and the parsed detail.

The demo wires Mock, Local, and Staging backends through this SDK — see demo/backendApi.ts and Wiring the UI to the AI service.