Skip to content

Test with an AI agent

How to set up your AI agent for a WCAG audit: the right agent, agent-browser, the start prompt, permissions and domains.

Last updated: November 20, 2026


You can test your website for WCAG together with your AI agent. The agent goes through the testing steps, opens the pages in a browser and records findings with screenshots directly in a sitebrunch audit.

Info
This feature is still at an early stage. Results are not always reliable yet, and it is only turned on for workspaces that test it. If you want to try it, write to support@sitebrunch.com.

If something does not work, the most common problems and their solutions are in Solve problems with the AI agent.

What your agent needs

  • Read and write: Your agent is connected to sitebrunch with “Read and write”.

  • A browser: Your agent can control a browser: open pages, press keys, run scripts and take screenshots. agent-browser works best, but Chrome DevTools MCP, Playwright MCP or the browser built into your agent work too.

  • Subagents: Your agent can start subagents, helper agents that take over single testing steps. Without them, one agent runs out of memory before the audit is done.

  • Subagents that start subagents: Every tester hands judging screenshots to a subagent of its own. Your agent checks before the start whether that works and otherwise tells you what to set.

Give this guide to your AI agent

Paste the prompt into your agent. It reads this article, checks what it still needs for an audit and tells you exactly what to do.

Read this sitebrunch guide in full: https://staging.frontend.sitebrunch.de/en/help-center/ai-agent/accessibility/test-with-an-ai-agent.md

Then check step by step whether you are ready for a WCAG audit with the sitebrunch MCP: the connection with read and write, agent-browser, subagents, subagents inside subagents and the permissions for the sitebrunch tools. For everything that is missing, tell me exactly what to do. Do not start the audit until I tell you to.

Which agent works

  1. Claude Code with Opus 5.5 (recommended): In the terminal or in the Claude desktop app under “Code”. Starts subagents on its own, including subagents inside subagents, runs agent-browser on your computer and reaches any website without extra permissions.

  2. Codex, also in the ChatGPT desktop app: Works well if your prompt asks for subagents explicitly and you allow Codex once to start subagents inside subagents (see below). agent-browser only runs there if you allow it to run outside the sandbox.

  3. ChatGPT in “Work” mode: Only starts subagents when you ask for them. ChatGPT then uses its own browser.

Not suitable are these two:

  • The normal ChatGPT chat: It cannot start subagents. Switch to “Work” or to Codex.

  • Claude in the chat (claude.ai or “Chat” in the desktop app): An audit there is clunky. You have to allow every domain of the website in the settings first and then start a new chat. Use Claude Code, which is in the desktop app too.

Tip
We recommend Claude Code with Opus 5.5. It gives the best results and uses the fewest tokens. You pick the model in Claude Code with /model.

Allow subagents inside subagents

The testers are subagents themselves. Whether a focus outline is visible or an alt text fits the image is decided for them by another subagent that looks at the screenshots. If a tester cannot start a subagent, it stops right away and reports “Cannot start subagents.” It never judges screenshots itself, so no barrier is missed.

  • Claude Code: Works without any setting. Only if your settings.json sets CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1, remove it or set it to 2. Then start a new session.

  • Codex: Add these lines to ~/.codex/config.toml and restart Codex:

[agents]
max_depth = 2

For other agents, your agent names the setting if it knows it.

Install agent-browser

agent-browser is a browser for AI agents. With it, up to 3 subagents test at the same time, so the audit finishes sooner. It runs without a visible window, so you can keep working. You need Node.js. Run this command once in your terminal:

npm install -g agent-browser && agent-browser install

If agent-browser is missing, your agent asks whether it may install it. Allow it, or run the command yourself. Some agents refuse installs on their own when they approve commands automatically. Your agent does not work around that, it asks you.

If you say no, it tests with another browser it has, for example Chrome DevTools MCP. That takes much longer, because the subagents then test one after another.

If agent-browser cannot download its own Chrome, it uses the Chrome already on your computer. This does not change the results.

Tip
If the audit runs in a visible browser window, for example with Chrome DevTools MCP, do not use the computer meanwhile. As soon as you click into another app, the window loses focus. The browser then stops drawing focus outlines, and the keyboard checks give wrong results.

In Codex and the ChatGPT desktop app, commands run in a sandbox. agent-browser only starts there if you let the command run outside the sandbox. Approve that when Codex asks. Otherwise Chrome crashes at start.

If your agent installs agent-browser itself inside a sandbox, it needs access to these domains: registry.npmjs.org, googlechromelabs.github.io and storage.googleapis.com.

Give permissions once

An audit calls the sitebrunch tools hundreds of times. Without permission, your agent asks every time. Set this up before you start:

  • Claude: Open “Customize”, “Connectors” and sitebrunch. Under “Tool permissions”, set the tools to “Always allow”. On Claude Team and Enterprise, an admin first has to turn on “Allow ‘Always allow’ for connector tools” in the organization settings.

  • ChatGPT and Codex: ChatGPT only remembers a permission for the current chat. Allow the sitebrunch tools for the whole chat the first time it asks.

While a permission question is open, the subagents wait.

Start the audit

Start a new chat and paste this prompt. Replace <project name> with the name of your project:

Run a WCAG accessibility audit with the sitebrunch MCP for the project <project name>.

1. Before you start, check whether agent-browser is installed. If it is missing, stop and ask me to install it. Give me this command to run once in my terminal (it needs Node.js): npm install -g agent-browser && agent-browser install. If I say no, test with the browser you have.
2. Select the project, start the "auditing" workflow with select_workflow and follow its instructions exactly.
3. Run the audit with subagents, as the instructions say: per pass one recipe subagent and one tester per page. With agent-browser, up to 3 testers run in parallel.
4. Work through all steps without stopping. Do not ask me for confirmation between steps and do not stop to report progress. Stop only if: the browser cannot load domains the pages need, the site needs a login, or all steps are done and you ask me whether to finish.

You decide with your agent which pages are tested. Enter them as a path, for example /contact, or as the full address on your website. Pages on subdomains work too. sitebrunch refuses pages of other websites.

The prompt first checks whether agent-browser is installed and otherwise tells you how to install it. It asks for subagents explicitly. ChatGPT and Codex only start them when you ask. And it tells the agent to work through all steps without pausing.

Tip
The testers fill in forms and send them to check error messages. This can create real requests, sign-ups or orders. Write in the prompt which forms your agent must not send.

When your agent asks you to allow domains

Before the first testing step, your agent checks whether its browser can load the pages with all images, fonts and styles. If a domain is blocked, it tells you the exact domains: the website itself, the domains for images and fonts, and the domain it uploads screenshots to. This is how you allow them:

  • Claude Code on your computer: If the sandbox asks about a domain, allow it.

  • Claude Code on the web: Open “Environment” and “Network access” and add the domains. Then start a new session.

  • Other agents: Your agent tells you the setting where you allow domains.

In this check it also tests whether it can upload screenshots to sitebrunch. That way you allow all domains in one go. A finding only counts as “with screenshot” once the image has really arrived at sitebrunch.

Sometimes only a single script is blocked, for example a tracking script from another domain. Your agent then asks you whether it matters for the test. If the script only collects statistics, it can carry on without it. If it adds visible elements, such as a cookie banner, a chat window or a feedback tool, allow the domain. Otherwise the testers check a page that lacks exactly these elements.

Tell your agent once you have allowed the domains. It then checks them again. If that does not work in the running chat, start a new one and write: “Continue the sitebrunch audit <audit ID>.”

How a test runs

  1. Your agent selects the project and starts the audit.

  2. The testing steps are grouped into passes. A pass combines steps that are tested with the same actions. One walk with the Tab key, for example, answers visible focus, focus order and keyboard traps.

  3. For each pass, a subagent writes a recipe, the exact testing method. Then one tester per page tests all steps of that pass.

  4. Some passes only apply if the page has a certain feature, for example video or audio, calls or tools for creating content. A subagent first checks whether it exists. If it does not, the steps count as not applicable.

  5. It records every finding in the audit with a description, the affected element and a screenshot, in your project’s language.

  6. When all passes are done, it shows you a summary and asks whether to finish the audit. A finished audit cannot be reopened. Until then you can already look at the findings in the dashboard.

The summary at the end

Your agent tells you what it tested well, what it did not test and which errors came up along the way. It also names steps that were tested less thoroughly and borderline cases a person should decide. Look at exactly these points before you finish the audit.

If a step seems uncertain, have it retested. Write for example: “Retest steps 1, 8 and 11.” The testers keep existing findings. If one thinks a finding is wrong, your agent tells you.

Review the findings yourself afterwards. You can edit or delete them in the dashboard like in an audit you created yourself. If something does not work, read Solve problems with the AI agent.

Continue an audit

If a chat breaks off, start a new one and write: “Continue the sitebrunch audit <audit ID>.” The audit ID is in the dashboard, in the address of the audit after /a11y-audit/. Your agent picks up at the next open pass.

Your agent does the rest: it finds the audit’s project from the audit ID itself.

A new chat does not know the reports of the old one. Steps that were already tested but not yet completed are therefore marked for your review. If you want to be sure, have them retested.