bugAgent Tools (SDK)

Capture the last 60 seconds of user activity, run WCAG accessibility evaluations, and automate browser testing with Playwright — all before filing a report.

A lightweight JavaScript SDK records clicks, navigation, console errors, console warnings, network failures, DOM mutations, and URL history in a rolling buffer. When a user reports an issue, the SDK captures a page screenshot, a DOM replay snapshot, and optionally a screen + voice recording or annotated screenshot markup — then sends everything to the AI Assistant, which analyzes the recording and auto-drafts a structured report — whether it's a bug, feature request, enhancement, or any other supported type.

Quick Start

Add one script tag to your website and the SDK is live. No build tools, no configuration files, no npm install required.

<script
  src="https://app.bugagent.com/sdk/bugagent-sdk.js"
  data-key="ba_live_your_key_here"
  data-position="bottom-right">
</script>

How It Works

Installation

Script Tag (Recommended)

The fastest way to get started. No build tools required. Add the script tag to any HTML page.

<script
  src="https://app.bugagent.com/sdk/bugagent-sdk.js"
  data-key="ba_live_your_key_here"
  data-position="bottom-right">
</script>

The SDK initializes automatically when the script loads. It begins capturing events immediately.

Self-Hosted

If you prefer to host the SDK yourself, download bugagent-sdk.js and serve it from your own domain:

curl -o public/bugagent-sdk.js https://app.bugagent.com/sdk/bugagent-sdk.js

Then reference it with the data-api attribute pointing to bugAgent:

<script src="/bugagent-sdk.js" data-key="ba_live_..." data-api="https://app.bugagent.com"></script>

Configuration

Configure the SDK using data-* attributes on the script tag:

Full Example

<script
  src="https://app.bugagent.com/sdk/bugagent-sdk.js"
  data-key="ba_live_your_key_here"
  data-position="bottom-left"
  data-color="#3B82F6"
  data-api="https://app.bugagent.com">
</script>

API Key

The SDK authenticates using your bugAgent API key. To get your key:

What Gets Captured

The SDK captures lightweight event data, DOM mutations, and a page screenshot automatically. Optionally, users can record their screen and voice via the FAB toolbar. Each event is a small JSON object with a type, timestamp, and relevant metadata.

AI Analysis

When a session is submitted, the AI Assistant immediately analyzes the event stream and produces a structured analysis:

• Suggested Title — A concise bug title derived from the errors and user actions observed
• Description — A detailed description of what went wrong, based on console errors, failed requests, and user behavior
• Reproduction Steps — Numbered steps generated from the click and navigation events
• Bug Type — Suggested classification (UI, Performance, Crash, Network, Logic, etc.)
• Severity — Suggested severity based on the impact and nature of the errors
• Key Findings — Highlighted observations like "500 error on checkout API" or "JavaScript crash in payment form"

The analysis is stored alongside the session and displayed on the bug report detail page. It is also injected into the the AI Assistant chat as context, so the AI can discuss the session with the user and refine the bug report before submission.

Dashboard View

When a session replay is attached to a bug report, developers see a dedicated section on the report detail page:

• Page Screenshot — A visual snapshot of the browser page at the moment of capture, attached as a media item. If the user annotated the screenshot using the markup tool, the annotated version (with circles, arrows, and drawings composited over the base image) is shown instead
• Session Metadata — Page URL, title, viewport size, capture timestamp
• User Journey — Chronological list of pages visited in the 60 seconds before the bug was reported (collapsible)
• User Activity — A readable log of user actions — clicks, navigation, errors, and warnings with timestamps (collapsible)
• Screen Recording — If the user recorded their screen, an embedded video player shows the WebM recording
• DOM Replay Badge — Shows the number of DOM mutations captured for visual replay
• Console Errors & Warnings — All console.error() and console.warn() calls, plus uncaught exceptions
• Failed Network Requests — HTTP requests that returned 4xx/5xx status codes or failed entirely
• Stack Trace / Console Log — The last 50 console notifications (log, info, warn, error, exceptions) with full stack traces, in a searchable, collapsible section
• Network Waterfall — Failed (4xx/5xx) and slow (>1s) API requests showing method, URL, status code, and duration, in a searchable, collapsible section
• Performance Metrics — Page load time, first contentful paint, DOM ready time, FPS, memory usage, DOM node count, and long tasks captured at the time of report
• WCAG Analysis Results — Accessibility violations grouped by severity (critical, serious, moderate, minor) with element selectors, WCAG criteria, and remediation links
• Playwright Automation Runs — Test execution results with pass/fail status, step-by-step logs, and screenshots from failed assertions
• AI Analysis — Key findings from the automated analysis (collapsible)

the AI Assistant Integration

bugAgent Tools (SDK) integrates directly with the AI Assistant. When a session is captured:

This means the user never has to write a bug report from scratch. The AI does the work based on what actually happened in the browser.

Markup / Annotation

The SDK floating action button (FAB) includes a built-in annotation tool that lets users draw directly on a screenshot before submitting a bug report. This helps testers and users visually highlight exactly what went wrong.

How It Works

Additional Controls

• Undo — Removes the last annotation drawn. Can be pressed repeatedly to undo multiple strokes.
• Reset — Clears any previously saved markup from the FAB toolbar, restoring the original auto-captured screenshot.
• Cancel / ESC — Exits annotation mode without saving any changes.
• Done — Composites all annotations over the base screenshot and saves the result.

Rewind

The Rewind tool replays the last 5 meaningful user actions directly in the browser. Unlike a video replay, Rewind actually re-executes clicks, form inputs, scroll positions, and page navigations in real time — helping testers recall exactly what they just did before encountering a bug.

How It Works

Supported Actions

• Clicks — Re-executes element.click() on the original target, found by CSS selector or coordinate fallback.
• Text Input — Clears the field and retypes the value character by character with a realistic 40ms delay, dispatching input and change events.
• Checkboxes & Radios — Toggles the checked state and dispatches a change event.
• Select Menus — Sets the selected value and dispatches a change event.
• Scroll — Smoothly scrolls the page to the recorded position using window.scrollTo().
• Navigation — Navigates to the recorded URL and resumes remaining actions on the new page.

Controls

• ESC key — Aborts the replay immediately and cleans up the overlay.
• Stop button — Visible in the progress bar, stops the replay at the current step.

WCAG Accessibility Analysis

The WCAG Analysis tool runs a comprehensive accessibility scan on the current page using axe-core by Deque — the industry-standard engine used by Google Lighthouse and Chrome DevTools. It covers 80+ WCAG 2.0/2.1 Level A and AA rules with zero false positives.

How It Works

What Gets Checked

• Color Contrast — Text contrast ratios against WCAG AA thresholds (4.5:1 normal, 3:1 large text).
• Image Alt Text — Missing or empty alt attributes on images (WCAG 1.1.1).
• Form Labels — Inputs, selects, and textareas without associated labels or aria-label (WCAG 1.3.1).
• Link & Button Names — Interactive elements without accessible names (WCAG 2.4.4).
• ARIA Validation — Invalid roles, missing required attributes, and ARIA misuse.
• Heading Structure — Skipped heading levels, missing landmarks.
• Keyboard Navigation — Focus management, tab order, and keyboard traps.
• Document Structure — Missing lang attribute, page title, and landmark regions.

Report Output

Each violation in the bug report includes:

• Impact level — Critical, serious, moderate, or minor.
• Rule ID — The axe-core rule identifier (e.g., color-contrast, image-alt).
• WCAG criteria — The specific WCAG success criterion violated.
• Element selector — CSS selector targeting the affected element.
• HTML snippet — The offending markup for quick identification.
• Remediation link — Direct link to Deque's documentation on how to fix the issue.

Privacy & Security

The SDK is designed to capture the minimum data needed to understand what happened, without exposing sensitive information.

API Reference

For advanced integrations, you can interact with the SDK API directly. See the full API Reference for details.

Submit Session

POST /api/sessions/capture
Content-Type: application/json

{
  "apiKey": "ba_live_your_key_here",
  "events": [...],
  "snapshot": {
    "url": "https://app.example.com/checkout",
    "title": "Checkout - My App",
    "userAgent": "Mozilla/5.0...",
    "viewportWidth": 1440,
    "viewportHeight": 900
  },
  "consoleErrors": [...],
  "networkLog": [...]
}

Response

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "dashboard_url": "/dashboard/reports?session=550e8400...",
  "status": "analyzing"
}

Endpoints

Plans & Limits

bugAgent Tools (SDK) is available on Pro, Team, and Enterprise plans.

Support

Need help with bugAgent Tools? We're here.