Mastra Quickstart

This runs the example from a clone of the monorepo. The backend is not Python: it is the Node service in deployments/ag-ui-mastra, listening on port 5332. The Angular dev server is on port 4332.

Prerequisites

Node.js 20 or newer and an OpenAI API key. No Python toolchain is involved in this example.

Two terminals, and the Node service starts by hand

serve-example.ts auto-starts Python backends only. For Mastra it starts the Angular side, and you start the Node service yourself.

Install workspace dependencies

git clone https://github.com/cacheplane/angular-agent-framework.git
cd angular-agent-framework
npm ci

Install and start the Node AG-UI service

The service has its own dependency tree.

cd deployments/ag-ui-mastra
npm ci
AG_UI_INTERNAL_TOKEN=dev-local-token \
  OPENAI_API_KEY=sk-... \
  PORT=5332 node server.mjs

Variable	Required	Purpose
`AG_UI_INTERNAL_TOKEN`	Yes	Every route except `/ok` requires a matching `X-Internal-Token` header. The service refuses to boot without this.
`OPENAI_API_KEY`	Yes	Resolved by Mastra's model router. `OPENAI_BASE_URL` is honored, which is how the fixture harness replays recorded calls.
`PORT`	Yes, here	Defaults to `8321`. The example's dev proxy targets `5332`, so set it.
`AG_UI_MASTRA_DB_PATH`	No	LibSQL file path. Defaults to `data/mastra.db` beside the service. It must be persistent, because suspended-run snapshots live there.

Do not source the repository root .env

Export only the variables you need. A stray AG_UI_INTERNAL_TOKEN that disagrees with the dev proxy surfaces as a 401 that reads like an OpenAI authentication failure.

Start the Angular app in a second terminal

npx tsx apps/cockpit/scripts/serve-example.ts --capability=rt-mastra

Or run the target directly:

npx nx run cockpit-runtimes-mastra-angular:serve:cockpit --port 4332

The example's proxy.conf.mjs rewrites /agent to http://localhost:5332/agent/mastra and injects X-Internal-Token: dev-local-token. Override that header value with the AG_UI_INTERNAL_TOKEN environment variable if you started the service with a different token.

Open the app

Visit http://localhost:4332. The service exposes an unauthenticated health check at http://localhost:5332/ok; the run endpoint is http://localhost:5332/agent/mastra.

Exercise every surface

"Start a packing list with a tent and two sleeping bags." — writes the list into working memory, which reaches the frontend as shared state.
"What are the trail conditions at Point Reyes?" — calls check_conditions.
"Reserve the Sky Camp site for two nights." — calls reserve_campsite, which suspends the run and renders an approval card.
Approve or decline the card — the run resumes from the persisted snapshot and the agent confirms the outcome.

Running the service's own tests

cd deployments/ag-ui-mastra
npm test

These assert the Server-Sent Events grammar of every surface against the captured 2026-08-31 transcripts, and drive the interrupt-to-resume round trip through the real @ag-ui/client — the same client the Angular adapter wraps. The model is a scripted mock, so no network and no key are required.

Next steps

How It Connects — the wire conventions this example relies on.
Overview — what the integration does and does not support.