Walkthrough: an AI agent sets up UI capture and reads flows and journeys
This walkthrough follows an AI agent through UI capture from start to finish, through the Keploy MCP server: it finds the tools, creates an app, mints an ingest key, adds the capture SDK to the React sample shop, checks that visits arrive, and reads the flows, the journey plan and its shares of sessions. Then it cleans up.
Each step shows the tool call as the agent's MCP client sends it to invoke_tool, its answer, and what the agent does next. Every answer is from a real run with six visits to the shop, shortened and without its meta (but for the test runs' pagination), with IDs replaced and the server written as api.keploy.io. To connect your own agent first, follow the AI agent quickstart.
UI Testing is in beta. Recording visits and reading them as flows and journeys works today. Replaying journeys as Playwright tests is in beta too, and its runner is not in a release build yet, so the agent here reads journeys and test runs and does not run tests. See What an agent cannot do yet.
What the agent does
- Finds the UI capture tools.
- Creates an app.
- Mints an ingest key.
- Adds the capture SDK to the shop.
- Checks that capture is waiting for visits.
- Records visits and ends each one.
- Waits for the flows.
- Reads the flows.
- Reads the journey plan.
- Counts the share of sessions a set of journeys stands for.
- Reads the test runs.
- Cleans up.
1. Find the tools
The server runs in tool-search mode: its tools/list holds only search_tools, get_tool_schema, invoke_tool and four sign-in and setup tools. Its instructions, in the answer to the MCP initialize request, have a UI CAPTURE section that names the UI capture tools in the order an agent uses them. So the agent fetches all their schemas in one call:
{
"names": [
"createApp",
"listApps",
"getApp",
"deleteApp",
"uiCaptureSetup",
"listUIIngestKeys",
"revokeUIIngestKey",
"uiCaptureStatus",
"listUIFlows",
"getUIFlow",
"uiFlowGraph",
"uiJourneys",
"uiJourneyImpact",
"listUITestRuns",
"getUITestRun"
]
}
The answer has each tool's description and input schema. Every UI capture tool takes appId; MCP tools lists the rest of their inputs. From here on, the agent runs each tool with invoke_tool, with the tool's name and arguments.
2. Create the app
The agent creates an app for the shop. An app for UI capture needs only a name, and the name cannot be changed later.
{
"name": "createApp",
"arguments": {
"name": "docs-demo-agent"
}
}
{
"data": {
"createdAt": 1795159503,
"id": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"name": "docs-demo-agent"
},
"status_code": 201
}
A tool's answer is the REST API's answer, with the HTTP status added as status_code. The app's id is the appId every other tool takes.
3. Mint an ingest key
{
"name": "uiCaptureSetup",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"name": "storefront web",
"ttlDays": 30
}
}
{
"data": {
"apiKey": "kep_YOUR_INGEST_KEY",
"endpoint": "https://api.keploy.io/ui/v1/ingest",
"key": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"createdAt": 1795159503,
"expiresAt": 1797751503,
"id": "ec6ebf01-0250-49c5-b71c-554cfec6f0af",
"keyPrefix": "kep_YOUR_ING",
"name": "storefront web",
"status": "active"
},
"next": [
"apiKey is shown only in this response: store it now (it is safe to ship in the page; it can only post recordings into this app)",
"install the SDK and call KeployCapture.init once at app start-up, in the browser bundle",
"browse the app, then GET /client/v1/apps/af1ec8ee-c43a-4c9c-826b-4223f506fb19/ui/capture-status (MCP: uiCaptureStatus) to see sessions arrive",
"a session becomes flows 30 minutes after its last activity (to end one at once, as a test or CI recording does, POST https://api.keploy.io/ui/v1/sessions/{sdkSessionId}/complete with this key in X-API-Key); read them with GET /client/v1/apps/af1ec8ee-c43a-4c9c-826b-4223f506fb19/ui/flows (MCP: listUIFlows)",
"once sessions are processed, GET /client/v1/apps/af1ec8ee-c43a-4c9c-826b-4223f506fb19/ui/journeys (MCP: uiJourneys) is the journey plan a UI test run replays; GET /client/v1/apps/af1ec8ee-c43a-4c9c-826b-4223f506fb19/ui/test-runs (MCP: listUITestRuns, getUITestRun) reads the runs"
],
"sdk": {
"init": "import { KeployCapture } from \"@keploy/capture-sdk\";\n\nawait KeployCapture.init({\n endpoint: \"https://api.keploy.io/ui/v1/ingest\",\n apiKey: \"kep_YOUR_INGEST_KEY\",\n});\n",
"install": "npm install @keploy/capture-sdk",
"package": "@keploy/capture-sdk"
}
},
"status_code": 201
}
apiKey appears only in this answer, so the agent keeps it now. It is safe to ship in the shop's JavaScript: it can only post recordings into this one app. ttlDays is optional; without it the key does not expire. Each call mints a new key.
4. Add the SDK
The answer's sdk.install and sdk.init are what the agent adds to a frontend: install @keploy/capture-sdk, and call KeployCapture.init once, in a module the app imports before it makes any request. The sample shop already does both: src/main.tsx imports src/keploy.ts first, and src/keploy.ts calls init with the endpoint and key from .env. So the agent only writes .env:
VITE_KEPLOY_INGEST_ENDPOINT=https://api.keploy.io/ui/v1/ingest
VITE_KEPLOY_INGEST_KEY=kep_YOUR_INGEST_KEY
Then it builds the shop and serves the build: npm run build && npm run preview.
The init snippet sets only endpoint and apiKey, so the SDK runs with its default privacyMode: "balanced", which masks everything visitors type. The shop writes the default out. For a public site, the agent would set "strict", which masks all visible text too.
5. Check that capture is waiting for visits
{
"name": "uiCaptureStatus",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19"
}
}
{
"data": {
"explanation": "no session from the capture SDK has reached this app",
"idleAfterSeconds": 1800,
"state": "NO_SESSIONS",
"totalFlows": 0,
"totalSessions": 0
},
"status_code": 200
}
NO_SESSIONS until someone uses the app. The answer's next lists what to check if nothing arrives.
6. Record visits
Here six visits were made in a headless Chromium, along three paths through the shop. A person using the shop by hand records the same way.
| Visits | Pages | What each does on the way |
|---|---|---|
| 1, 2 | / → /products → /cart → /checkout | Searches for kettle, adds it to the cart, places an order |
| 3, 4, 5 | / → /about | |
| 6 | / → /products | Searches for kettle |
While the first visit was still open, uiCaptureStatus said it was recording:
{
"data": {
"explanation": "sessions are arriving; a visit becomes flows 30 minutes after its last activity",
"idleAfterSeconds": 1800,
"lastBatchAt": 1795159548,
"next": [
"keep using the app, or wait 30 minutes after the last activity, then check again",
"to end a visit at once (a test or CI recording), POST https://api.keploy.io/ui/v1/sessions/{sdkSessionId}/complete with the app's ingest key in X-API-Key (the SDK's own session id for the visit); its flows follow within a minute or two"
],
"recentSessions": [
{
"batches": 5,
"eventCount": 70,
"id": "a1e271a4-c6e8-456a-ab38-83f4bf64db4f",
"lastBatchAt": 1795159548,
"sdkSessionId": "01056d9a-f9b9-48ef-baf7-15d8804cd7ab",
"sdkVersion": "3.1.0",
"startedAt": 1795159526,
"status": "RECORDING"
}
],
"sessionsByStatus": {
"RECORDING": 1
},
"state": "RECORDING",
"totalFlows": 0,
"totalSessions": 1
},
"status_code": 200
}
A visit becomes flows idleAfterSeconds, 30 minutes, after its last activity. To have its flows at once, the agent ends each visit: it closes the visit's tab, then completes the session with the ingest key. sdkSessionId is the browser's own id for the visit: uiCaptureStatus lists it under recentSessions, as above, and it is what KeployCapture.getSessionId() returns, which the shop prints in the browser console:
curl -X POST "https://api.keploy.io/ui/v1/sessions/<sdkSessionId>/complete" \
-H "X-API-Key: kep_YOUR_INGEST_KEY"
{
"ok": true,
"sessionId": "01056d9a-f9b9-48ef-baf7-15d8804cd7ab",
"status": "COMPLETED"
}
A tab left open on a completed session is refused at its next batch, which is why the agent closes it first.
7. Wait for the flows
The agent calls uiCaptureStatus once a minute. Flows are extracted every minute, so polling faster gains nothing.
{
"data": {
"explanation": "flows have been extracted from recorded sessions",
"next": [
"read them with GET /client/v1/apps/af1ec8ee-c43a-4c9c-826b-4223f506fb19/ui/flows (MCP: listUIFlows)",
"each flow lists its steps and the network calls it made"
],
"recentSessions": [
{
"batches": 3,
"completedAt": 1795159633,
"eventCount": 26,
"id": "db452012-c693-4938-a672-c15f44c59b1a",
"lastBatchAt": 1795159632,
"sdkSessionId": "a1a5cfc9-a48a-483f-8139-26e7ad540e8b",
"sdkVersion": "3.1.0",
"startedAt": 1795159625,
"status": "PROCESSED"
}
],
"sessionsByStatus": {
"PROCESSED": 6
},
"state": "FLOWS_READY",
"totalFlows": 16,
"totalSessions": 6
},
"status_code": 200
}
FLOWS_READY as soon as one flow exists, even while other visits are still being processed: a minute before this answer, it already said FLOWS_READY, with 4 sessions PROCESSED and 2 still COMPLETED. To know that every visit is in, the agent checks sessionsByStatus.
8. Read the flows
{
"name": "listUIFlows",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"limit": 50
}
}
{
"data": [
{
"clusterId": "661be522-1276-4612-9e7e-181dfd1ad3ff",
"createdAt": 1795159660,
"description": "2 steps, 1 API calls, 6.1s",
"id": "d07317d4-e2b5-4ba6-b1db-767966e4e474",
"name": "Click on /",
"networkCalls": 1,
"sessionId": "2a58f279-cc49-48cf-85ab-e7cfd9199a33",
"status": "CLUSTERED",
"steps": 2
},
{
"clusterId": "4949ebdb-3873-4f10-9d79-c2027ee534a8",
"createdAt": 1795159660,
"description": "1 steps, 1 API calls, 0.0s",
"id": "9888b9ee-f61d-4ca3-b13f-f0524c31d4ed",
"name": "Navigate on /about",
"networkCalls": 1,
"sessionId": "2a58f279-cc49-48cf-85ab-e7cfd9199a33",
"status": "CLUSTERED",
"steps": 1
}
],
"status_code": 200
}
The six visits made 16 flows, one for each page each visit opened. A flow's name is a verb and the page it happened on, or Verb: /a → /b for a flow that ends on another page: Fill when something was typed, else Click when something was clicked, else Navigate. The agent reads one flow's steps and calls with getUIFlow:
{
"name": "getUIFlow",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"flowId": "248a8854-06ac-4189-936b-e7eb2bd55326"
}
}
{
"data": {
"clusterId": "16ba6a5d-a195-4ebb-9457-7f697bfc55c7",
"createdAt": 1795159660,
"description": "3 steps, 2 API calls, 6.1s",
"id": "248a8854-06ac-4189-936b-e7eb2bd55326",
"name": "Fill on /products",
"networkCallList": [
{
"method": "GET",
"responseStatus": 200,
"timestamp": 1795159625571,
"url": "http://localhost:4173/api/products"
},
{
"method": "GET",
"responseStatus": 200,
"timestamp": 1795159631678,
"url": "http://localhost:4173/api/products"
}
],
"networkCalls": 2,
"outcome": {
"elements": [],
"viewport": {
"height": 720,
"width": 1280
}
},
"sessionId": "db452012-c693-4938-a672-c15f44c59b1a",
"status": "CLUSTERED",
"stepList": [
{
"action": "navigate",
"hasValue": true,
"index": 0,
"pageUrl": "http://localhost:4173/products",
"selector": "",
"timestamp": 1795159625548
},
{
"action": "input",
"hasValue": true,
"index": 1,
"pageUrl": "http://localhost:4173/products",
"selector": "[data-testid=\"search-input\"]",
"timestamp": 1795159631613
},
{
"action": "click",
"index": 2,
"pageUrl": "http://localhost:4173/products",
"selector": "[data-testid=\"search-button\"]",
"timestamp": 1795159631661
}
],
"steps": 3
},
"status_code": 200
}
This is visit 6 on the Products page. A step says that a value was typed (hasValue), never what. The first call is the page loading its products; the second is the search, GET /api/products?q=kettle, which comes back without its query. What an agent sees lists what is left out. Step and call timestamps are in milliseconds.
9. Read the journey plan
{
"name": "uiJourneys",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19"
}
}
{
"data": {
"coveragePermille": 1000,
"coverageTargetPermille": 800,
"freshness": {
"computedAt": 1795159694,
"recomputesAfterSessions": 1,
"recomputesAt": 1795246094,
"refreshableAt": 1795159754,
"sessionsCovered": 6,
"sessionsProcessedSince": 0
},
"journeys": [
{
"flowIds": [
"d07317d4-e2b5-4ba6-b1db-767966e4e474",
"9888b9ee-f61d-4ca3-b13f-f0524c31d4ed"
],
"id": "2990cf35868e23549307ad2120fe5d58",
"lastSeenAt": 1795159612,
"pages": ["/", "/about"],
"pinned": false,
"representativeSessionId": "2a58f279-cc49-48cf-85ab-e7cfd9199a33",
"sdkVersion": "3.1.0",
"selected": true,
"sessionPercentage": 50,
"sessions": 3
},
{
"flowIds": [
"f059842e-220d-415d-9195-b909f17f6536",
"c220bcd5-4596-4270-ab4a-accfa4e7a403",
"453613fc-e400-4461-b184-2321dd2d2559",
"2635dfaf-b651-4b5d-ab3f-5fb7484f73c3"
],
"id": "778bfd7ec36f1c03bfffa0362a47fe4f",
"lastSeenAt": 1795159556,
"pages": ["/", "/products", "/cart", "/checkout"],
"pinned": false,
"representativeSessionId": "55c7ea31-dba1-4d49-acbe-56cf700295e3",
"sdkVersion": "3.1.0",
"selected": true,
"sessionPercentage": 33.333333333333336,
"sessions": 2
}
],
"maxJourneys": 20,
"planId": "a89602ff-c783-4f8e-bc34-47a151adea19",
"ranked": [
{
"id": "084e889e39bcbdc4ebbe152a5c81d4ab",
"pages": ["/", "/products"],
"selected": false,
"sessionPercentage": 50,
"sessions": 3
},
{
"id": "2990cf35868e23549307ad2120fe5d58",
"pages": ["/", "/about"],
"selected": true,
"sessionPercentage": 50,
"sessions": 3
},
{
"id": "778bfd7ec36f1c03bfffa0362a47fe4f",
"pages": ["/", "/products", "/cart", "/checkout"],
"selected": true,
"sessionPercentage": 33.333333333333336,
"sessions": 2
}
],
"totalSessions": 6,
"windowDays": 30
},
"status_code": 200
}
journeysare the journeys Keploy selected to replay as tests:/→/about, taken by 3 of the 6 sessions, and/→/products→/cart→/checkout, taken by 2. Together they cover all the moves the sessions made between pages (coveragePermille1000), past the 800 Keploy aims for. Each one'sflowIdsare the recording a test of it replays.rankedare the most taken journeys./→/productswas taken by 3 sessions but is not selected: the longer journey that continues it was, and its test replays those pages too.freshnesssays how current the plan is.recomputesAfterSessions: 1means the next processed session makes a read compute a new plan.refresh: truecomputes one fromrefreshableAt, a minute aftercomputedAt, and needstestgen:run.
10. Count the share of sessions
uiJourneyImpact counts the sessions that took at least one of a set of the plan's journeys, as the share of sessions a failure in those journeys would stand for. journeyIds is one string, the IDs joined with commas:
{
"name": "uiJourneyImpact",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"planId": "a89602ff-c783-4f8e-bc34-47a151adea19",
"journeyIds": "2990cf35868e23549307ad2120fe5d58,778bfd7ec36f1c03bfffa0362a47fe4f"
}
}
{
"data": {
"affectedSessionPercentage": 83.33333333333333,
"affectedSessions": 5,
"journeyIds": [
"2990cf35868e23549307ad2120fe5d58",
"778bfd7ec36f1c03bfffa0362a47fe4f"
],
"planId": "a89602ff-c783-4f8e-bc34-47a151adea19",
"totalSessions": 6
},
"status_code": 200
}
5 of the 6 sessions, 83.3%: a union, never a sum. Each ID must be one of the plan's journeys. A journey that is only in ranked is refused:
{
"name": "uiJourneyImpact",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"planId": "a89602ff-c783-4f8e-bc34-47a151adea19",
"journeyIds": "084e889e39bcbdc4ebbe152a5c81d4ab"
}
}
{
"error": {
"code": "INVALID_PARAMETER",
"message": "invalid UI journey: journey is not in the plan: 084e889e39bcbdc4ebbe152a5c81d4ab"
},
"status_code": 400
}
11. Read the test runs
{
"name": "listUITestRuns",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19"
}
}
{
"data": [],
"meta": {
"pagination": {
"has_next_page": false,
"has_previous_page": false,
"next_cursor": null,
"previous_cursor": null,
"total_count": 0,
"unreadable_count": 0
},
"timestamp": "2026-11-20T07:28:17Z"
},
"status_code": 200
}
The app has no runs. No tool creates a run: a run today comes only from a flow page's Generate Test in the dashboard, and it stays PENDING, because the runner that replays journeys as Playwright tests is not in a release build yet.
12. Clean up
The agent revokes the ingest key, which it lists with listUIIngestKeys when it does not have the keyId:
{
"name": "revokeUIIngestKey",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19",
"keyId": "ec6ebf01-0250-49c5-b71c-554cfec6f0af"
}
}
{
"data": {
"id": "ec6ebf01-0250-49c5-b71c-554cfec6f0af",
"revoked": true
},
"status_code": 200
}
Pages that still use the key are refused within about 30 seconds. Then it deletes the app, which needs a key with the admin scope. An OAuth sign-in cannot delete apps.
{
"name": "deleteApp",
"arguments": {
"appId": "af1ec8ee-c43a-4c9c-826b-4223f506fb19"
}
}
{
"data": {
"deleted": true
},
"status_code": 200
}
Waits
- A visit becomes flows 30 minutes after its last activity, or a minute or two after
POST /ui/v1/sessions/<sdkSessionId>/complete. - Poll
uiCaptureStatusat most once a minute. No state lasts forever: a visit that cannot be processed is retried for about two hours, then counted as failed. - The journey plan: a read computes a new one once enough sessions have been processed since the last.
refresh: trueforces one at most once a minute. A429RATE_LIMITEDanswer touiJourneysmeans the server's queue of plan computations is full, or the plan was not ready in time: its message says to retry in 10 seconds. - A
PENDINGtest run is not claimed by any runner: do not poll for it.
Waiting and polling has the details.
What an agent cannot do yet
- Generate or run tests: no tool or REST route creates, claims or completes a UI test run, and the runner,
keploy ui run, is not in a release build yet. - Pin a journey into the plan, or accept a change.
- Run UI tests in CI: no service-account role runs them. A CI job can check capture status and read the plan with a key bound to the
UI_READERrole, on a paid plan.