Skip to main content

Documentation Index

Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Learn more about Agentic Checks in the Agentic Checks overview.
Use Agentic Checks to monitor user journeys from a natural-language prompt. The agent discovers the target, creates a reusable check script, and can self-heal when the saved script starts failing.
Before creating Agentic Checks, ensure you have:
  • An initialized Checkly CLI project
  • Access to Agentic Checks on your Checkly account
  • Available Agentic Check active capacity if the check is active
  • Any required test credentials saved as Checkly environment variables
For additional setup information, see CLI overview.
import { AgenticCheck, Frequency } from 'checkly/constructs'

new AgenticCheck('homepage-health', {
  name: 'Homepage Health Check',
  prompt: 'Navigate to https://example.com and verify the page loads correctly.',
  activated: true,
  frequency: Frequency.EVERY_1H,
})

​
Configuration

The Agentic Check configuration consists of Agentic-specific options and a subset of inherited general check options.
ParameterTypeRequiredDefaultDescription
promptstringYes-Monitoring goal the agent should verify. Maximum 10,000 characters.
frequencyAgenticCheckFrequencyNoFrequency.EVERY_30MHow often the check should run. Agentic Checks support the same frequency values as other checks, down to 5 minutes.
agentRuntimeobjectNo{ skills: [], exposeEnvironmentVariables: [] }Runtime access the agent is allowed to use during execution.
The Agentic Check construct intentionally does not expose privateLocations, runParallel, retryStrategy, shouldFail, doubleCheck, or triggerIncident. These options are not currently honored for Agentic Checks.

​
prompt

The monitoring goal the agent should verify. Write the prompt in terms of user-visible behavior and expected outcomes. See Prompt best practices for guidance on scope, strictness, and nondeterministic flows. A reliable Agentic Check prompt usually states:
  • Goal: The user journey or system behavior to monitor.
  • What you are given: The start URL, test account context, and any required environment variables.
  • Success looks like: The exact outcome that should pass.
  • Failure looks like: The states that should fail the check.
  • Strictness: Whether the agent should assert exact values or evaluate the outcome more flexibly.
new AgenticCheck('checkout-flow', {
  name: 'Checkout Flow',
  prompt: `
    Go to https://shop.example.com.
    Sign in with the test account.
    Add one item to the cart and verify the checkout review page loads.
  `,
})
Use stricter prompts when the output should be predictable: 
new AgenticCheck('login-flow', {
  name: 'Login Flow',
  prompt: `
    ## Goal
    Sign in to https://app.example.com/login and confirm the dashboard loads.

    ## What you are given
    Use {{TEST_USER_EMAIL}} and {{TEST_USER_PASSWORD}} from the environment.

    ## Success looks like
    The authenticated dashboard is visible, the account name appears, and the final URL is inside app.example.com.

    ## Failure looks like
    The login form rejects valid credentials, the page stays on the login screen, an MFA prompt blocks the flow, or the dashboard shows a 4xx/5xx error.
  `,
  agentRuntime: {
    exposeEnvironmentVariables: ['TEST_USER_EMAIL', 'TEST_USER_PASSWORD'],
  },
})
Use outcome-based prompts when the application is intentionally nondeterministic: 
new AgenticCheck('support-assistant-flow', {
  name: 'Support Assistant Flow',
  prompt: `
    ## Goal
    Verify that the support assistant can help a user understand how to update billing details.

    ## What you are given
    Start at https://app.example.com/support and ask: "How do I update my billing details?"

    ## Success looks like
    The assistant gives a relevant answer, asks for missing context if needed, and guides the user toward a billing-settings or support handoff path.

    ## Failure looks like
    The assistant does not respond, answers an unrelated question, loops without progress, or gives instructions that cannot lead to completion.
  `,
})
Keep prompts focused on one flow. If you want to monitor navigation, login, and record creation, create separate Agentic Checks for each flow.

​
frequency

How often the Agentic Check should run. Use one of the supported Frequency constants or the equivalent number of minutes. 
import { AgenticCheck, Frequency } from 'checkly/constructs'

new AgenticCheck('hourly-agentic-check', {
  name: 'Hourly Agentic Check',
  prompt: 'Verify the homepage and pricing page load correctly.',
  frequency: Frequency.EVERY_1H,
})
Supported values: 5, 10, 15, 30, 60, 120, 180, 360, 720, and 1440.

​
locations

Public Checkly locations where the Agentic Check should run. Accounts can select up to three locations by default. Enterprise accounts can contact sales for unlimited locations. 
new AgenticCheck('regional-login-flow', {
  name: 'Regional Login Flow',
  prompt: 'Verify that a user can sign in and reach the dashboard.',
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
})

​
agentRuntime

Controls what the agent can access while executing the check.
ParameterTypeRequiredDefaultDescription
skillsstring[]No[]Extra skill packages to load into the agent runtime.
exposeEnvironmentVariables(string | object)[]No[]Environment variables the agent is allowed to read.
exposeEnvironmentVariables accepts either a string variable name or an object with name and optional description. 
new AgenticCheck('authenticated-api-check', {
  name: 'Authenticated API Check',
  prompt: 'Verify that the authenticated API health endpoint returns a healthy response.',
  agentRuntime: {
    skills: ['addyosmani/web-quality-skills'],
    exposeEnvironmentVariables: [
      'API_KEY',
      { name: 'TEST_USER_PASSWORD', description: 'Login password for the test account' },
    ],
  },
})
Variables not listed in agentRuntime.exposeEnvironmentVariables are not exposed to the agent runtime, even if they exist in your Checkly account.

​
Billing behavior

Agentic Checks use active-capacity billing. Active checks consume capacity; inactive checks do not. Use activated: false to keep an Agentic Check as a deployed draft without consuming active capacity. 
new AgenticCheck('draft-agentic-check', {
  name: 'Draft Agentic Check',
  prompt: 'Verify the account settings page loads for a signed-in user.',
  activated: false,
})
If an active Agentic Check would exceed your available capacity, deployment fails with a billing entitlement error. Deactivate an existing Agentic Check or purchase additional Agentic Check capacity before deploying.