Docs

Examples

Three worked sessions with a coding agent connected to Sypnia: fixing a problem end to end, finding why a page is slow, and seeing what one customer saw.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. 1. Fix what is failing
  2. 2. Find out why a page is slow
  3. 3. See what one customer saw

Engine Cloud Three sessions, written out. Each shows what you type, which tool the agent calls, what comes back, and what the agent does with it. The data is the shop from the rest of these docs. Results are shortened here; the full ones are in the tools reference.

Your client shows a call under the server’s name. This page writes sypnia.problems({ … }); yours may show sypnia:problems or mcp__sypnia__problems.

1. Fix what is failing

The session from the Sypnia home page, in full.

You

Text
what is failing in production?

Agent calls sypnia.problems({ status: "open" })

JSON
{
  "problems": [
    {
      "slug": "pay-button-does-nothing",
      "status": "open",
      "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
      "confidence": "high",
      "where": { "file": "src/checkout/checkout.tsx", "line": 142, "function": "confirmPayment" },
      "people": 3,
      "first_seen": "2026-03-12T09:12:04Z",
      "first_release": "4f2a91c"
    }
  ],
  "counts": { "open": 1, "resolved": 4, "ignored": 1 }
}

Agent

1 open problem since yesterday’s deploy: 3 people tried to pay and could not. The checkout sends the payment without an amount. I have the trace and the session. Want me to fix it?

You

Text
yes, and add a test

Agent calls sypnia.problem({ id: "pay-button-does-nothing" })

JSON
{
  "analysis": {
    "cause": {
      "text": "Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total, so the payment goes out without an amount and the API answers 400.",
      "evidence": [
        { "kind": "release_change", "ref": "4f2a91c:src/cart/cart.ts", "text": "The release renames `total` to `totalCents` in the Cart type." },
        { "kind": "stack_frame", "ref": "src/checkout/checkout.tsx:142", "text": "confirmPayment() still passes `cart.total` to createPayment()." }
      ]
    },
    "what_to_do": "Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.",
    "confidence": "high"
  },
  "stack": {
    "frames": [
      {
        "function": "confirmPayment", "file": "src/checkout/checkout.tsx", "line": 142,
        "source": { "start_line": 140, "lines": [
          "async function confirmPayment(cart: Cart) {",
          "  setPaying(true);",
          "  const payment = await createPayment({ amount: cart.total, currency: cart.currency });"
        ] }
      }
    ]
  },
  "release": { "version": "4f2a91c", "changes": { "commits": [{ "sha": "4f2a91c", "message": "Rename cart.total to cart.totalCents" }] } }
}

The agent opens src/checkout/checkout.tsx, sees that line 142 still reads cart.total, and confirms in src/cart/cart.ts that the field is now totalCents. It writes a test that fails when the amount is missing, then edits the file:

src/checkout/checkout.tsx
 async function confirmPayment(cart: Cart) {
   setPaying(true);
-  const payment = await createPayment({ amount: cart.total, currency: cart.currency });
-  router.push(`/orders/${payment.orderId}`);
+  try {
+    const payment = await createPayment({ amount: cart.totalCents, currency: cart.currency });
+    router.push(`/orders/${payment.orderId}`);
+  } catch (error) {
+    setError('We could not take the payment. Nothing was charged. Please try again.');
+  } finally {
+    setPaying(false);
+  }
 }

Agent

Fixed: confirmPayment() now reads cart.totalCents, and the customer sees a message when a payment is rejected. I added checkout.test.tsx with a test that fails when the amount is missing; it passes now, with the other 41 tests. I have not committed anything.

You review, merge and deploy. Then:

You

Text
it's deployed as 5b3c8d2, mark it resolved

Agent calls sypnia.resolve_problem({ id: "pay-button-does-nothing", release: "5b3c8d2", note: "confirmPayment reads cart.totalCents. Pull request 128." })

JSON
{
  "slug": "pay-button-does-nothing",
  "status": "resolved",
  "resolved_at": "2026-03-12T16:30:12Z",
  "resolved_by": "mcp:Cursor",
  "resolved_in_release": "5b3c8d2"
}

Agent

Marked as resolved in release 5b3c8d2. If it happens again in that release or a later one, Sypnia reopens it and alerts you.

2. Find out why a page is slow

You

Text
the daily summary says search got slower. why?

Agent calls sypnia.performance({ route: "/search", since: "24h" })

JSON
{
  "route": "/search",
  "page": { "views": 1840, "lcp_p75_ms": 3100, "previous_lcp_p75_ms": 1900, "inp_p75_ms": 180, "cls_p75": 0.04, "poor_share": 0.21 },
  "elements": {
    "lcp": [
      { "selector": "main ul.results > li:nth-child(1) img", "kind": "image", "samples": 1310, "p75_ms": 3200, "poor_share": 0.24 }
    ]
  },
  "suggestions": [{ "id": "sug_3h7j1k5l9p2o", "title": "The search page's first product image loads slowly" }]
}

Agent

The search page now takes 3.1 seconds to show its main content for three of four visits; it was 1.9. The slow element is the first product image in the results (main ul.results > li:nth-child(1) img), in 1,310 of 1,612 measured loads. Interaction and layout are fine. Let me look at how that image is rendered.

The agent finds the results component, sees that yesterday’s release replaced the thumbnail URL with the full-size image, and proposes to serve the thumbnail again and to load the first image with high priority.

Nothing here is a problem: no one saw an error. The agent got from «slower» to an element and a line of code with one call.

3. See what one customer saw

A customer wrote to support: «I tried to pay three times and nothing happened».

You

Text
ada@example.com says she couldn't pay this morning. what happened?

Agent calls sypnia.search({ q: "ada@example.com" })

JSON
{
  "people": [
    {
      "id": "u_1042", "name": "Ada Park", "email": "ada@example.com",
      "last_seen": "2026-03-12T10:31:58Z",
      "latest_sessions": [{ "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0", "started_at": "2026-03-12T10:31:16Z", "trouble": true }]
    }
  ]
}

Agent calls sypnia.session({ id: "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0" })

JSON
{
  "events": [
    { "offset_ms": 12412, "type": "page_view", "text": "Opened /checkout (from /cart)" },
    { "offset_ms": 27090, "type": "click", "text": "Clicked button «Pay $64.00» in «Your order»" },
    { "offset_ms": 29310, "type": "rage_click", "text": "Clicked button «Pay $64.00» 4 more times" },
    { "offset_ms": 31000, "type": "request", "text": "POST /api/checkout answered 400 amount_required after 3,870 ms" },
    { "offset_ms": 31004, "type": "error", "text": "ApiError: POST /api/checkout failed with 400 (amount_required)", "problem": "pay-button-does-nothing" },
    { "offset_ms": 42230, "type": "page_leave", "text": "Left /checkout after 30 s" }
  ]
}

Agent

Ada opened the checkout at 10:31, clicked «Pay $64.00», then four more times when nothing happened. The payment was rejected because it was sent without an amount, and the page showed her nothing. She left 11 seconds later. She was not charged. This is the known problem «pay-button-does-nothing», which hit 3 people today. The replay of her session is at https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0.

The search by e-mail works because the shop sends names and e-mails with identify(). A project that sends only ids is searched by id. The timeline has what she clicked, by the label of the button, and never anything she typed. The agent gives you the link to the replay; it cannot watch it.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close