pagent

Capture a new hypothesis (a test idea or brief) for either a registered page or an existing trigger. Use a trigger when the test needs CSS, URL, JSON-LD, list, or JavaScript targeting; otherwise provide the page. New hypotheses have no priority by default. Only use update_hypothesis to assign one if the user explicitly asks for a priority or asks you to prioritize the ideas. Capture one concrete, single-change idea per call. Clarify vague ideas first, and split independent changes into separate hypotheses. Provide exactly one of page or triggerId, and the hypothesis text. Exact page targeting is the default; never substitute a covering wildcard without confirmation. A trigger must be active and have an example URL. A hypothesis carries no audience: pick the audience when the test is built with create_test_from_hypothesis. Visitor conditions such as utm_* parameters, referrer, device, or country belong in an audience, not in a trigger or in the text: an idea for one visitor group, or with content per group (a hero per ad campaign), is one hypothesis per group, each written as the change those visitors see and never as a check like "only when utm_campaign=sport". This captures an editable idea; it does not create or launch a test. Write the text with the hypothesis template when you can support each part: "Based on [evidence] we think [theory]. We believe we can [outcome] by changing [change] for [visitors]. We know this is supported if they [new behaviour] and we see [effect on metrics]." Name visitors in words; eligibility stays in the audience.

capture_hypothesis

Rank several tests against each other by one stated measure. Use this to answer "which of my tests is winning" or "compare these tests". Provide the tests and the measure to rank by. Each test is given by its id or by its number as shown in the dashboard (e.g. 7). - uplift: relative lift of the variation over control. - probability: chance the variation beats control. Only Bayesian tests have it; frequentist tests (statisticsEngine FREQUENTIST) get a null value here and are listed after the ranked tests, so rank them by uplift instead or say they use p-values. - conversion_rate: the variation's observed conversion rate. Tests are returned ranked best-first by that measure. A number naming more than one test is reported under ambiguous rather than guessed at; ask which was meant and pass that test's id. Tests without results yet are listed last with a null value and hasResults=false; say they cannot be compared yet rather than ranking them. A null value with hasResults=true means the measure does not exist for that test's engine. Always state which measure you ranked by.

compare_tests

Mark a ready website onboarded. Safe to retry with the same idempotency key.

complete_website_onboarding

Replace the website's selected persona set and start goal/strategy generation after analysis is ready.

configure_website_onboarding

Continue building a test that was waiting for the owner's input, once every blocker is fixed, answered, or dismissed. Open suggestions do not hold it back. pagent picks up its draft where it stopped, with the owner's answers and optional instructions, and the test is ready or asks again when done. Confirm with the user first: this starts a new build.

continue_test_build

Create an audience: a named set of targeting rules that tests and explorers can be scoped to. Use this for requests like "test this on mobile visitors from paid search" or "target France and Germany". Rules are a list joined by `match` (and/or). An entry is either a condition or a nested group { match, conditions }, and groups nest as deep as needed, so pairwise logic is one audience: for "(google AND cpc) OR (bing AND cpc)" send match: or with one and-group per pair, each holding a utm_source condition and a utm_medium condition. To match any of several values of one field, use the member_of operator with a comma-separated value and valueKind csv, e.g. country member_of "FR,DE". Do not split a request into several audiences when one tree expresses it. Creating an audience does not put it on a page. Use set_page_audiences for that, or allPages: true to apply it everywhere.

create_audience

Create a click conversion goal: a click on the element matched by a CSS selector counts as a conversion. Provide the selector, a name, and where the goal counts: either a page URL (scopes it to that exact path) or a pagePattern (exact path, glob like '/products/**', or '**' for every page). The goal is created at workspace level; call attach_test_goal to make a test measure it. Use get_goals first to avoid duplicates (an existing goal with the same selector and scope is returned instead of duplicated). When a name is given, suggest appending ', [data-pagent-track="<name>"]' to the selector so equivalent new or rebuilt controls in variations can count toward the same goal. Escape the name as a CSS attribute string. One DOM element carries one goal id: a selector overlapping an existing goal's element does not count for a second goal, even if the selector text differs (for example div.btn-cart versus an existing add-to-cart goal). Widen the existing goal with update_click_goal instead of creating an overlapping goal. Goals created here are workspace goals: tracked on every matching page from the moment they are published, whether or not a test measures them yet, and only archived by a person. Rules the user should hear: click goals are not retroactive (they count from publication), and a goal only yields a comparable rate when the element exists in control as well as in the variation. A glob or '**' scope is right for elements that live on other pages than the test's page (add-to-cart on product pages measured by a home-page test); the SDK then counts the click wherever the element exists and does not report the goal as missing on pages without it. For elements a variation injects itself, tell the user it is engagement diagnostics, not a rate. For clicks that also push a dataLayer event, prefer define_event + create_event_goal, which is retroactive.

create_click_goal

Create an event conversion goal over an event label the site emits (a dataLayer / GTM event, a window CustomEvent, or a pagent.emit call). Event goals are computed at query time, so they count retroactively over everything already recorded and work in both test arms. Provide the label; use get_events first to see which labels exist and how often they fire. If the label is not observed yet, create its definition with define_event so the SDK starts observing it. The goal is created at workspace level; call attach_test_goal to make a test measure it.

create_event_goal

Keep two or more tests apart: create an exclusion so a visitor only ever sees one of them. Use it when tests change the same page, aim at the same goal, or share many visitors, and never as a default: every member gets a share of the visitors and takes correspondingly longer to finish. Defaults are an equal split per visitor; name, description, scope and mode are optional. Tests already in an exclusion cannot be added; use add_test_to_exclusion_group to join an existing one instead. A running test can be a member only if it is already in the exclusion; it is never moved.

create_exclusion_group

Create a follow-up hypothesis linked to an existing hypothesis, recording whether it follows up on, pivots from, or narrows the source idea. Anchor it with fromHypothesisId, or with fromTestId when a finished test prompted the idea. A test must be finished before it can anchor a follow-up. Following up from an archived or retired hypothesis is allowed. The new hypothesis inherits the source's page or trigger targeting unless page is provided. This does not create a test.

create_follow_up_hypothesis

Create a brand or content guideline the AI must follow when generating variations, e.g. "Never mention discounts", "Always write CTAs in sentence case", "Use only lifestyle imagery". Phrase the content as a clear instruction. Pick the role for the step the rule constrains (wording rules → COPYWRITER, imagery → GRAPHICS_DESIGNER, layout → ARCHITECT). Guidelines apply to all future variation generation; use read_product_area with area "guidelines" first to check for an overlapping existing rule.

create_guideline

Create an empty reusable trigger list. Add exact values or regexes with add_list_entries. Names must be unique within the workspace.

create_list

Register a Page through the same authenticated service used by the dashboard. Omit targeting for exact matching of the literal page path. Use targeting.kind="glob" only when the user explicitly requests a multi-page wildcard such as /products/*. Wildcard Pages require a matching exampleUrl and explicit user confirmation through wildcardConfirmed=true. Never add a leading wildcard to an exact path. The deprecated isGlob, exampleUrl, and wildcardConfirmed fields remain accepted for compatibility. Activate newly created Pages with activate_page before Pagent analyses them.

create_page

Create a page-view conversion goal: a visit to a specific page counts as a conversion. Provide a short name (tag) and the page path. Use get_goals first to avoid duplicating an existing goal. For rule- or property-based goals, direct the user to the goals UI.

create_page_view_goal

Create a persona: a described audience segment the agent optimises for. Use this when the user wants to add a new persona and has given its details. Provide a name plus the demographic, behaviours, psychographic, goals, challenges, and industry. Set selected to make it active immediately. Ask for any missing detail rather than inventing it.

create_persona

Deprecated: prefer an event goal (get_events, define_event when the label is not observed yet, then create_event_goal); use this only when the user explicitly asks for a programmatic goal or the site already sends direct conversions. Existing programmatic goals keep working. Creates a programmatic conversion goal: a direct conversion the site sends through the pagent SDK (window._pgnt.push({ kind: "conversion", ... })) counts. Provide the exact event tag. Use get_goals first to avoid duplicating an existing goal; if a goal with the same tag already exists, this returns it instead of creating a duplicate. Property-filtered goals (matching on event properties) stay in the goals UI.

create_programmatic_goal

Turn a completed test into a pull request on the customer's connected GitHub repository. pagent implements the test's variation in the source code inside an isolated environment, runs the repository's recorded checks, and opens a pull request for the team to review. Nothing is merged automatically and the website does not change until the team merges. Recommend this only for a test that won. Any stopped test qualifies though: implementing a variation that did not win is the user's decision, so do it when they ask, and say plainly that the test did not win; never suggest it yourself for such a test. A repository must be connected and prepared under Integrations, GitHub, and one open pull request per test is allowed. The result reports where it stands; use get_pull_request to follow progress. When the website has several prepared repositories, pass repository (owner/name) to choose. When the test has several variations, pass variation to choose; without it the best-performing variation is implemented.

create_pull_request

Create a new optimisation strategy. Provide a name and a description of the approach. The new strategy is not activated automatically; use select_strategy to make it active.

create_strategy

Turn a specific hypothesis into a test. This starts the build and returns immediately while the variation copy and relevant images are generated in the background. The test is not made live: it remains a building or idle draft until the user takes another action. After this returns, tell the user the test is building, offer private review as an optional next step, and do not poll for results. Never call prepare_review unless the user explicitly asks for it or accepts the offer. To prevent duplicate work, this returns the existing test when the hypothesis already has one that is still open; a hypothesis whose tests have all finished can be built again. The capture page comes from the hypothesis's trigger or page example URL; when neither provides one, supply url. The audience belongs to the test, not the hypothesis: pass audience to target one, omit it for all visitors. When the hypothesis is for a visitor group (a campaign, channel, device, or country), pass that group's audience; pagent then shows the variation only to those visitors, so the variation itself needs no eligibility check.

create_test_from_hypothesis

Create a CSS, URL, JSON-LD, mixed, or JS trigger with at least one example URL. Non-JS triggers use one flat AND/OR rule. Use list_lists before referencing a list id. This creates targeting only; it does not create a hypothesis or test.

create_trigger

Create a pagent website and start its analysis workflow. Poll get_website_onboarding_status before configuring later steps.

create_website

Define an event the pagent SDK should observe on the customer's site, so it is recorded under a label that event goals can use. Supports GTM-style dataLayer pushes ('data_layer': the object's event value, e.g. dataLayer.push({event: "conversation-started"})), window CustomEvents ('window_event'), and trigger matches ('trigger': the SDK records the event once per page start on which the trigger from triggerId matches, so a trigger like "cart has items" or "checkout page" becomes a goal without any site code). Confirm the exact event name and where it fires with the user before defining a listener source; the site's own code must already emit the event (an event fired only inside GTM, inside a cross-origin iframe, or as a bare gtag()/fbq() call cannot be observed). Observation starts once the definition is published and, for dataLayer, includes pushes that happened before the SDK loaded on that page. Labels the site already emits show up in get_events as OBSERVED; defining one promotes it. Then create_event_goal on the label.

define_event

Delete an audience. This also discards any draft tests scoped to it and archives its explorers, and removes it from every page it targets. It is refused while tests are running or being built on it, so stop those first.

delete_audience

Delete a keyword and unlink it from any pages. Use get_keywords to find the id.

delete_keyword

Delete a trigger list. This is refused while any active trigger condition references it.

delete_list

Permanently delete a persona and remove it from any audiences that reference it. This cannot be undone. Use get_personas to find the id.

delete_persona

Delete a strategy. The active strategy cannot be deleted, select a different one first. Use get_strategies to find the id.

delete_strategy

Delete an unused trigger. This is refused if any test references it; archive referenced triggers instead.

delete_trigger

Stop a test from measuring one of its conversion goals. The goal itself is kept for other tests (a click goal used by no other test is archived and can be restored from the Tracking page). Refuses to remove a test's primary goal: tell the user to attach another goal as primary first.

detach_test_goal

Dismiss one of pagent's suggestions to keep tests apart. The pair is remembered and never suggested again, so only dismiss when the user has decided the tests may run alongside each other.

dismiss_exclusion_suggestion

Check how completely a hypothesis is written, using Booking.com's five pillars: prior evidence, the change, the audience, the expected visitor response, and the metrics. Returns a band (weak, acceptable, excellent) and which pillars are present or missing. It judges how clearly the idea is written, not whether it is a good idea, and it never blocks capturing or testing. The pillars are read from the hypothesis text (and its notes), written with the template: "Based on [evidence] we think [theory]. We believe we can [outcome] by changing [change] for [visitors]. We know this is supported if they [new behaviour] and we see [effect on metrics]." Pass hypothesisId to check a saved hypothesis, or pass the draft text to check an idea before capturing it. With both, the draft text replaces the saved one, so you can check whether an edit would close a gap before making it. Use it before offering ideas you generated from data, and when the user asks how strong or complete a hypothesis is. Report the missing pillars as questions for the user; do not invent evidence or metrics to fill them. When it returns unavailable, say the evaluation can't run at the moment.

evaluate_hypothesis

Evolve a completed test into its follow-up: the platform picks the next step for that page and audience (the next queued test, the next ready hypothesis, or a new variation built on what was learned) and creates or starts it. Use this when the user wants to iterate on a finished test ("what's next for this page", "build on the winner"). Scope: this iterates on the ONE test you name, and only on its own page and audience. It does not combine, merge, or stack winners from several tests, and there is no capability that does. If the user asks to combine winning variations from multiple tests, say that is not something this platform can do rather than offering evolve as a substitute. Only a stopped (completed) test can be evolved. The evolved (original) test keeps its status; the follow-up arrives as newTestId with its own newTestStatus. Refer to the follow-up when describing what was created or started.

evolve_test

Explain how testing works in Pagent, grounded in this workspace. Use this when the user asks how something works rather than for data: "do I need to stop my current test to start a new one", "what is a hypothesis", "what happens in review", or "what do the test states mean". Pick the topic: - lifecycle: what the test states mean and how a test moves between them. - conflict: the one-running-test-per-page-and-audience rule and the stop-vs-queue choice. Pass page (and cohort) to ground it in what is actually running there now. - brief: what a hypothesis (brief) is and when it can still be edited. - review: how proposed changes go through review and never go live without approval. Returns guidance text plus any relevant current-state facts to weave into the answer. It never invents data.

explain_lifecycle

Kick off AI generation of conversion goals from a plain-language description of what the business wants visitors to do. This runs once per workspace in the background; if goal generation has already run, define goals directly with create_page_view_goal instead.

generate_goals

Kick off AI generation of personas from the crawled site. This runs in the background and only applies while a workspace is still being set up; on an onboarded workspace, add personas manually with create_persona instead.

generate_personas

Kick off AI generation of strategies from the crawled site. Optionally pass suggestions to steer them. This runs in the background and only applies while a workspace is still being set up; on an onboarded workspace, add strategies manually with create_strategy instead.

generate_strategies

Read the workspace's traffic, conversion and revenue analytics over time, and segment it. Use this for questions about the site's numbers rather than one test's statistics (use get_test_results for a test's uplift and significance). Every answer has a unit, and the unit depends on the measurement you ask for. "count" counts events: page views, conversions, sessions. "unique" counts distinct visitors per time bucket, which is what the Cockpit dashboard shows by default. "aggregate" with property "revenue" reads money. Cite the unit the response gives back, never just "views". A "unique" series cannot be added up. Its total comes back as null with additive: false, because a visitor active on three days is counted in three buckets. Quote the mean per bucket or the per-bucket numbers instead of inventing a total. For a conversion rate, ask for both metrics with measurement "count" and divide the totals. Segment with filters. Within one filter the values are ORed, and separate filters are ANDed, so two filters on the same dimension would ask for an impossible intersection and are rejected. Name tests, arms, audiences, pages and goals the way a person does, not by id: a test by its dashboard number, an arm as "control" or a letter, the rest by name, path or tag. For referrer, city, country, browser, language and the five UTMs, call get_analytics_filters to see which values the site actually has. "mobile" takes "true" or "false". Two things to say out loud when they apply. If coverage.collectsOutsideTests is false, these numbers only cover pages with a running test, and the workspace can widen that in Settings then Setup, "Keep collecting analytics when no test is running". On a "unique" series, visitors who did not consent are deduplicated by IP and browser within a rotating daily window rather than by a cookie, so people sharing a connection merge together and the same person recurs across days. Pick the range from the user's words and today's date: "last week" = 1w, "this month" = 1m, a quarter = custom start and end dates. The first and last bucket of a preset range are partial. A "page" filter selects sessions on that page by URL path, whether or not a test was running there; a page with a pattern such as /products/** covers every path it matches. If a metric comes back in errors, say what it says instead of guessing.

get_analytics

List the values a segmentation dimension actually has in this workspace, so get_analytics filters on something real instead of a guess. Returns each value with how many sessions carried it, busiest first. Covers the dimensions whose values only exist in the traffic itself: referrer, city, country, browser, language, and the five UTMs. The other dimensions need no lookup. Name a test by its dashboard number, an arm as "control" or a letter, an audience by name, a page by path and a goal by its tag, and get_analytics resolves them; "mobile" is just "true" or "false". Values are scoped to a time range, because a campaign that ran in March has no values in May. Use the same range you plan to query. Only the busiest hundred come back, so truncated: true means the tail is missing, not that the list is wrong.

get_analytics_filters

Read how to query this website's analytics with run_analytics_sql: the pagent.* views and every column with its type and meaning, the rules every query must follow, how to count page views, visitors, conversions and revenue the way the dashboard does, worked examples, and this website's test, arm, goal and page ids. Call it once before your first run_analytics_sql in a conversation, and again only if a query fails with an unknown name. The views carry ids, not names, so look up the ids you need here instead of guessing them.

get_analytics_sql_guide

Look up one audience (cohort) by name and return its description, targeting rules, personas, and how many tests and explorers use it. Use this for questions like "tell me about my Mobile audience" or when you need a cohort's details before acting on it. Provide the audience name (case-insensitive); omit it for the default audience (all visitors). If no audience matches, this returns found: false.

get_audience