> ## 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.

# Setup

> Build a review agent end to end: create, run, poll, and inspect findings.

This guide walks through the steps to get a review agent running and surfacing findings as comment annotations. Each step links to the full API reference for request and response details.

## Step 1: (Optional) Refine your prompt

If you have a one-line QA instruction and you're not sure it's specific enough to ship, run it through the prompt tools first.

**Check completeness:** [Enhance Prompt](https://velt.dev/docs/api-reference/rest-apis/v2/agents/prompt/enhance.md) returns either "your prompt is sufficient" or a specific clarification request (with suggested options for the user to pick from).

**Expand into a structured task:** [Validate Prompt](https://velt.dev/docs/api-reference/rest-apis/v2/agents/prompt/validate.md) takes a simple instruction and expands it into a comprehensive QA task with an analysis prompt, response descriptions, demo examples, and tool requirements.

**Iterate on demo failures:** [Refine Prompt](https://velt.dev/docs/api-reference/rest-apis/v2/agents/prompt/refine.md) takes an existing analysis prompt and a list of demo failures (with feedback) and produces a refined prompt.

**Resolve optimal config:** [Resolve Config](https://velt.dev/docs/api-reference/rest-apis/v2/agents/config/resolve.md) takes raw + processed instructions and recommends extraction strategies + execution strategy.

These tools are optional. Skip straight to Step 2 if you already know what your agent should do.

## Step 2: Create the agent

Call [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md) with a name, instructions, and a configuration block.

The minimum viable agent is `name` + `description` + `enabled` + `instructions` + `contextGathering.strategies` + `execution` (send `{}` for the defaults):

```JSON theme={null}
{
  "data": {
    "name": "Brand Color Checker",
    "description": "Verifies CTAs use the primary brand color",
    "enabled": true,
    "instructions": "Verify all CTAs use the primary brand color #1A73E8.",
    "contextGathering": {
      "strategies": ["web-page-text", "web-page-screenshot"]
    },
    "execution": {}
  }
}
```

The engine creates the agent's main document and writes version 1 to its versions subcollection. The response returns `{ agentId }`.

For a complete walkthrough of every config block (`execution`, `response`, `postProcess`, `input`, `scope`, `setup`, `metadata`), see the [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md) reference.

> [!NOTE]
>
> Built-in agents (`spell-check`, `broken-links`, etc.) are pre-registered for every workspace. You don't need to create them; skip straight to Step 3 with one of the [built-in agent IDs](https://velt.dev/docs/ai/agents/overview.md#built-in-agents).

## Step 3: Run an execution

Call [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md) with `agentId`, `url`, `organizationId`, and `documentId`. All four are required: the document must already exist, and findings land on it as comment annotations.

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "url": "https://example.com/pricing",
    "organizationId": "org_001",
    "documentId": "doc_001",
    "deviceType": "desktop",
    "ranBy": {
      "userId": "user_123",
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}
```

The response returns immediately with `{ executionId }`. The engine creates an execution document, dispatches a Cloud Task, and starts processing asynchronously.

* **Cross-page execution:** Set `crossPageExecute: true` and the engine crawls the seed URL and processes up to `maxUrlsToProcess` pages (default 50).
* **Page lists:** Send `urls` (max 500 absolute URLs or site-relative paths on the same host as `url`) and the engine reviews exactly those pages with no crawl. Use it when pages differ only by a query string and a crawl cannot find them. See [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md) for the normalization rules.
* **Several agents:** Send `agentIds` (up to 10) instead of `agentId`. Each agent gets its own execution, and the response lists one `executionId` per agent, plus any agent that could not start. It works on one page, or with `urls` or `crossPageExecute` on several, where each agent's execution covers every page. See [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md#9-several-agents-on-one-page) and [several pages](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md#11-several-agents-on-several-pages).
* **Focused rechecks:** Set `userContext.focusIssueTypes` to report only the listed [issue types](https://velt.dev/docs/ai/agents/overview.md#issue-types). The run replaces only the agent's earlier pending suggestions of those types. See [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md#10-recheck-some-issue-types).
* **Per-run options:** Switch a built-in agent's checks off, or tune its thresholds, through `userContext`. See [Per-run options](https://velt.dev/docs/ai/agents/overview.md#per-run-options).
* **Device emulation:** Set `deviceType: "mobile"` or `"desktop"` (default `"desktop"`) to control the viewport/user-agent used for context gathering and pin resolution.
* **Workflow trigger:** Set `trigger: "workflow"` and pass `workflowExecutionId` when running an agent as part of a Review Workflow Builder workflow node.
* **Annotation visibility:** Set `annotationVisibility` to choose who sees the comment annotations the execution creates. With `"public"`, anyone with access to the document sees the finding pins; the default, `"private"`, shows them to members and admins of the organization only. See [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md) for both values.

## Step 4: Poll for results

Call [Get Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/get.md) with the `executionId` returned from Step 3. Poll until `execution.status !== "running"`. If you started several agents with `agentIds`, poll each `executionId` from `data.executions`.

```JSON theme={null}
{
  "data": {
    "executionId": "exec_1711900000000_abc123def456"
  }
}
```

Terminal statuses:

| Status | Meaning |
| - | - |
| `passed` | Completed successfully: all URLs clean, no findings |
| `failed` | Completed with findings: all URLs processed cleanly |
| `partial` | Some URLs succeeded and some failed (see `resultsSummary.erroredUrls`) |
| `error` | Every URL failed, or a fatal error (see `execution.error.code` and `retryable`) |
| `skipped` | Execution was skipped (precondition unmet) |

When the execution completes, `resultsSummary` contains aggregate counts:

```JSON theme={null}
{
  "totalFindings": 7,
  "totalAnnotationsCreated": 7,
  "urlsProcessed": 12,
  "urlsWithFindings": 5
}
```

Re-runs use a per-URL **delete-and-recreate** model (`postProcess.deletePreviousSuggestions`, enabled by default): before writing a URL's new findings, the engine clears that URL's still-pending suggestions from the previous run, so annotations never pile up as duplicates. Suggestions a reviewer has already accepted, rejected, or resolved are left untouched. A focused recheck (`userContext.focusIssueTypes`) clears only the pending suggestions of the issue types it rechecks.

## Step 5: Fetch per-URL findings

Set `includeResults: true` on Get Execution to fetch the full findings array per URL:

```JSON theme={null}
{
  "data": {
    "executionId": "exec_1711900000000_abc123def456",
    "includeResults": true
  }
}
```

The response includes a `results` array alongside `execution`. Each entry has the URL, the agent's output for it under `agentResult` (its findings are in `agentResult.findings`), and the URL's finding count:

```JSON theme={null}
{
  "results": [
    {
      "url": "https://example.com/pricing",
      "urlHash": "a1b2c3d4e5f6",
      "agentResult": {
        "status": "completed",
        "issueCount": 1,
        "findingsCount": 1,
        "findings": [
          {
            "id": "finding-1",
            "title": "CTA uses non-brand color",
            "description": "The 'Buy now' button uses #FF5722 instead of #1A73E8",
            "severity": "high",
            "category": "color",
            "targetText": "Buy now",
            "suggestion": "Change background-color to #1A73E8",
            "htmlSelector": "a.cta-primary",
            "isPageLevel": false,
            "issueType": "brand-color",
            "confidence": 95,
            "evidence": {
              "selector": "a.cta-primary",
              "text": "Buy now"
            }
          }
        ],
        "error": null
      },
      "findingCount": 1,
      "processedAt": 1711900050000
    }
  ]
}
```

Annotation counts are reported for the whole run only, in `resultsSummary.totalAnnotationsCreated`. See [Get Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/get.md) for every field, including `evidence`.

Findings are also written to the document as comment annotations (when `postProcess.annotations.enabled` is true, the default). Authors of these annotations are flagged with the system agent user.

## Listing and counting executions

* **List executions** for an agent or document with pagination: [List Executions](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/list.md).
* **Count executions** (e.g. a live "N running" counter) with [Count Executions](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/count.md).

## Iterating on the agent

Behavioral edits create a new version. Identity edits do not.

* **Edit identity (`name`, `description`, `enabled`):** [Update Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/update.md). No new version; the root doc is updated in place.
* **Edit behavior (`instructions`, `contextGathering`, `execution`, `postProcess`, `input`, `scope`, `setup`):** [Update Agent Version](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md). Creates version `N+1` and bumps the agent's `version` pointer. In-flight executions stay pinned to whatever version they started on.
* **List versions:** [List Versions](https://velt.dev/docs/api-reference/rest-apis/v2/agents/versions/list.md). Each version contains the full behavioral snapshot.
* **Roll back the most recent change:** [Restore Version](https://velt.dev/docs/api-reference/rest-apis/v2/agents/versions/restore.md). Single-step undo; call repeatedly to walk backward. Cannot go below version 1.

## Organizing agents

Use [Agent Groups](https://velt.dev/docs/api-reference/rest-apis/v2/agents/groups/create.md) to bundle related agents together (e.g. "Brand QA"). Agents stay independent documents; groups just store an `agentIds` array. An agent can belong to multiple groups; deleting an agent removes it from every group automatically.

When listing agents with [Get Agent(s)](https://velt.dev/docs/api-reference/rest-apis/v2/agents/get.md), pass `groupId` to filter to a single group's members.

## Track usage

[Get Agent Analytics](https://velt.dev/docs/api-reference/rest-apis/v2/agents/analytics/get.md) returns per-agent, per-model, per-month token consumption plus execution counts. Filter by `agentId`, `year`, `month`, or `model`.

## Next steps

> [card] [API Reference](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md)
>
> All endpoints organized into Agents, Execution, Versioning, Prompt Tools, Analytics, and Groups, with full request and response schemas.

> [card] [Overview](https://velt.dev/docs/ai/agents/overview.md)
>
> What agents are, the pipeline phases, built-in vs custom agents, and the full enum vocabulary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.