> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Review Agents
> Build review agents for your product that review web pages, data, charts, and anything else you can surface via API or MCP, then create findings as comment annotations.
## What are Review Agents?
Build review agents for your product. Point an agent at a URL, and it reviews the content and posts findings as comment annotations.
Review agents can review anything you can surface:
* **Web pages and sites**: text, screenshots, HTML, CSS, links, accessibility tree, Lighthouse.
* **Your data**: pull any REST endpoint into the review with the `rest-api` strategy.
* **Charts, dashboards, and more**: anything you can expose via an API or MCP server.
You write a prompt and pick a few config options. The platform handles context gathering, LLM invocation, post-processing, deduplication, and annotation creation.
You can also put agent creation in your users' hands: ship the [built-in agents](#built-in-agents) as defaults, and let users create custom agents in plain English from your UI. The [prompt tools](/docs/api-reference/rest-apis/v2/agents/prompt/enhance) turn a one-line instruction into a production agent config.
## What you get
* **Built-in and custom agents.** Ready-made agents (spell-check, broken-links, PII, Lighthouse, accessibility, [and more](#built-in-agents)), or your own from a prompt.
* **Plain-English agent builder.** Let your users describe a review in simple English; prompt tools ([enhance](/docs/api-reference/rest-apis/v2/agents/prompt/enhance), [validate](/docs/api-reference/rest-apis/v2/agents/prompt/validate), [refine](/docs/api-reference/rest-apis/v2/agents/prompt/refine)) check it, expand it into a full agent config, and iterate on feedback. `userContextFields` render typed inputs in your setup UI.
* **Pluggable context gathering.** Stack strategies: page text, screenshots, HTML, CSS, links, accessibility tree, computed styles, robots.txt, sitemap, Lighthouse, live REST API data.
* **Live REST API context.** The `rest-api` strategy fetches your endpoints at execution time and injects the responses into the prompt. Secrets are encrypted at rest and redacted on read.
* **MCP tool use.** The `mcp-tools` strategy runs a multi-turn tool loop against your remote [MCP](https://modelcontextprotocol.io) servers. Works with Claude and Gemini.
* **Versioned configurations.** Every behavioral edit creates a new version; one-click restore rolls back.
* **Async execution.** `Run Execution` returns an `executionId` immediately; poll `Get Execution` until `status !== "running"`.
* **Cross-page execution.** Set `crossPageExecute: true` to crawl the seed URL and review up to `maxUrlsToProcess` pages.
* **Device emulation.** Run each execution as `"mobile"` or `"desktop"`.
* **Re-run deduplication.** Re-running an agent replaces the prior run's suggestions instead of piling up duplicates.
* **Token usage analytics.** Per-agent, per-model, per-month token usage via the Analytics endpoint.
* **Agent groups.** Bundle related agents (e.g. "Brand QA") and filter lists by group.
## Use cases
Verify brand colors, typography, and logo placement across your marketing pages. Re-run on every deploy.
Run spell-check, broken-links, and accessibility agents before a release. Findings land on the staging document.
Flag PII and profanity on user-generated pages. Pair with Approval Engine for human review.
Set `crossPageExecute: true` and the crawler discovers internal links, then reviews each page.
Pull live business data into the prompt with `rest-api`, e.g. validate on-page pricing against your billing API.
Trigger an agent from an Approval Engine workflow node and park the workflow on its findings.
Let your users create review agents in plain English from your UI. Ship built-in agents as defaults; prompt tools turn user instructions into custom ones.
Use `mcp-tools` to verify on-page code snippets live against your documentation MCP server.
## How it works
1. **Define the agent.** Call [Create Agent](/docs/api-reference/rest-apis/v2/agents/create) with a name, instructions, and config (context gathering, execution strategy, post-processing).
2. **Run an execution.** Call [Run Execution](/docs/api-reference/rest-apis/v2/agents/execution/run) with `agentId` and `url`. Returns an `executionId` immediately.
3. **Poll for results.** Call [Get Execution](/docs/api-reference/rest-apis/v2/agents/execution/get) until `status !== "running"`. Set `includeResults: true` for per-URL findings.
4. **Findings appear as annotations.** Each finding becomes a comment annotation on the document referenced by `organizationId` / `documentId` (on by default).
## Mental model
| Concept | Meaning |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent** | Reusable review configuration: identity (`name`, `description`, `enabled`) plus behavior (instructions, context gathering, execution, post-processing). Behavioral edits create a new version. |
| **Execution** | One run of an agent against a seed URL. Pins the agent `version` at dispatch, so in-flight runs ignore mid-run config changes. |
| **Finding** | One issue on one URL: severity, category, target text, suggestion, HTML selector, confidence. Guardrails deduplicate and sanitize findings before annotations are created. |
**Execution lifecycle:**
```
running → passed | failed | partial | error | skipped
```
## Pipeline phases
Each agent run executes sequential phases:
| Phase | What happens |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `validate` | Zod check on payload + input requirements + variable keys |
| `extract` | All configured context gathering strategies run |
| `execute` | LLM call (or registered service); results normalized to a finding array |
| `postProcess` | Guardrails → delete previous suggestions → pin resolution → annotation creation → analytics |
| `structureResponse` | Final response assembly with optional response adapter |
## Execution statuses
| Status | Meaning |
| --------- | --------------------------------------------------------------------------------------------------- |
| `running` | Execution is in progress |
| `passed` | Completed successfully: all URLs processed cleanly, **no findings** |
| `failed` | Completed with **findings**: all URLs processed cleanly |
| `partial` | Mixed outcome: at least one URL succeeded and at least one URL failed ("passed with some failures") |
| `error` | Every processed URL failed, or a fatal crawl/dispatch failure; nothing usable produced |
| `skipped` | Execution was skipped (e.g. a precondition was not met) |
**Terminal status precedence:** `error` > `partial` > `failed` > `passed`. A run that produced findings but had a single failing page surfaces as `partial` (not `error`). For `partial`/`error`, per-page failure detail is in `resultsSummary.urlsErrored` and `resultsSummary.erroredUrls`.
## Built-in agents
| Agent ID | Description |
| ----------------------- | -------------------------------------------- |
| `spell-check` | Spelling and typo detection |
| `grammar-check` | Grammar checking |
| `broken-links` | Broken link validation |
| `pii-detection` | PII (personal info) detection |
| `profanity-filter` | Profanity detection |
| `sensitive-data` | Sensitive data detection |
| `lighthouse` | Google Lighthouse performance/SEO/a11y audit |
| `accessibility-checker` | Accessibility (WCAG) audit |
| `og-image-checker` | Open Graph image validation |
| `lorem-ipsum` | Placeholder / lorem-ipsum text detection |
## Context gathering strategies
Stack one or more strategies in the order you want them to run.
| Strategy | What it returns |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `web-page-text` | Visible text extracted via Puppeteer |
| `web-page-screenshot` | Full-page screenshot as image (multimodal input) |
| `web-page-html` | Cleaned HTML content |
| `web-page-css` | Cleaned CSS content from stylesheets |
| `web-page-links` | All hyperlinks on the page, classified internal/external |
| `web-page-accessibility` | Accessibility issues (Pa11y / HTML\_CodeSniffer) |
| `computed-styles` | Browser-resolved computed CSS for specific selectors |
| `robots-txt` | Fetched `robots.txt` |
| `sitemap-data` | Discovered and parsed XML sitemaps |
| `lighthouse` | Google Lighthouse audit (performance / a11y / best-practices / SEO) |
| `rest-api` | Customer-configured REST endpoints fetched at runtime (SSRF-guarded, encrypted auth); injected via `{{restApiData}}` |
| `none` | No context gathering (for service-only or text-only agents) |
Per-strategy overrides are supplied under `contextGathering.strategyOptions[""]`. See [Create Agent](/docs/api-reference/rest-apis/v2/agents/create) for the `rest-api` endpoint configuration schema.
## Execution strategies
| Strategy | Purpose |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `ai` | LLM-driven analysis (default) |
| `service` | Delegate to a registered built-in service (`serviceId` required) |
| `service+ai` | Service context gathering + AI analysis (`serviceId` required) |
| `stagehand-agent` | Autonomous browser agent via Stagehand AI |
| `mcp-tools` | Model-driven tool loop against remote MCP server(s) (`instructions` + `execution.mcpServers` required) |
## Knowledge (Memory-RAG)
Agents can pull workspace knowledge from Velt Memory into the prompt via `execution.knowledge`:
| Field | Type | Range | Description |
| --------------- | ------- | ----- | -------------------------------------------------------------------------------------------------------- |
| `useMemory` | boolean | | When `true`, retrieves knowledge/patterns/activities from Memory and injects them as `{{memoryContext}}` |
| `maxChunks` | number | 1–20 | Max knowledge chunks to retrieve |
| `maxPatterns` | number | 1–20 | Max learned patterns to retrieve |
| `maxActivities` | number | 1–20 | Max recent activities to retrieve |
The `knowledge` block is strictly validated: only the four fields above are accepted. The legacy `sourceIds` field has been removed, and `maxChunks` is now capped at 20 (previously 50). Knowledge retrieval never fails an execution: if Memory is unavailable, the run continues in a degraded mode without knowledge context.
## Scope
| Field | Bound to |
| ---------------- | -------------------------------------------------- |
| `apiKey` | Workspace-wide (default; agents are per-workspace) |
| `organizationId` | Annotations created on the named organization |
| `documentId` | Annotations created on the named document |
`organizationId` and `documentId` are required on Run Execution and control where annotations land. The document must already exist before you run an agent against it.
## Get started
Create an agent, run it against a URL, and read the findings end-to-end.
All endpoints organized into Agents, Execution, Versioning, Prompt Tools, Analytics, and Groups.