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

# Create Agent

Use this API to create a new custom agent configuration. The engine stores the agent in Firestore and writes version 1 to the agent's versions subcollection. The schema uses `.passthrough()`, so any additional behavioral fields are forwarded to the service layer.

# Endpoint

`POST https://api.velt.dev/v2/agents/create`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**name** `string` *required*

Min 1 char. Agent display name.

**description** `string` *required*

Min 1 char. Human-readable description of what the agent does.

**rawInstructions** `string`

Original user-provided instructions (before enhancement).

**instructions** `string`

Processed/enhanced instructions used by the AI execution. Required whenever the execution strategy consumes a prompt — `"ai"` (the default), `"service+ai"`, `"stagehand-agent"`, and `"mcp-tools"`. Only pure `"service"` agents may omit it.

**enabled** `boolean` *required*

Whether the agent is active.

**phaseTimeoutMs** `number`

Per-phase timeout in milliseconds. Positive integer, no upper bound. Omit to use the platform default.

**metadata** `object`

Arbitrary client metadata. Use your own keys (e.g. `{ "team": "growth", "owner": "jane" }`).

**contextGathering** `object` *required*

Context gathering configuration.

| Field | Type | Required | Description |
| - | - | - | - |
| `strategies` | string\[] | yes | Min 1 strategy. See [context gathering strategies](#context-gathering-strategies). |
| `strategyOptions` | object | no | Per-strategy option overrides, keyed by strategy name ([see below](#context-gathering-strategy-options)). When `strategies` includes `"rest-api"`, `strategyOptions["rest-api"]` is required ([see below](#rest-api-strategy-options)). |
| `aiConfig` | object | no | AI provider/model override for the gather phase ([see below](#ai-config-provider--model)). |

**execution** `object` *required*

Execution configuration. Send `{}` to accept the defaults (the `"ai"` strategy).

| Field | Type | Required | Description |
| - | - | - | - |
| `executionStrategy` | string | no | `"ai"` (default), `"service"`, `"service+ai"`, `"stagehand-agent"`, or `"mcp-tools"`. |
| `serviceId` | string | no | Required when `executionStrategy` is `"service"` or `"service+ai"`. Values: `"broken-links"`, `"crawler"`, `"screenshot"`, `"accessibility-checker"`, `"og-image-checker"`. |
| `aiConfig` | object | no | AI provider/model override for the execute phase ([see below](#ai-config-provider--model)). |
| `mcpServers` | object\[] | no | Required (≥1) when `executionStrategy` is `"mcp-tools"`. Remote MCP servers the model may call during the tool loop ([see below](#mcp-servers-mcp-tools-strategy)). |
| `responseDescriptions` | object | no | Per-field descriptions guiding AI response shaping ([see below](#response-descriptions)). |
| `strategyOptions` | object | no | Per-strategy option overrides. See [execution strategy options](#execution-strategy-options). |
| `knowledge` | object | no | Memory-RAG knowledge integration ([see below](#knowledge-memory-rag)). |

**response** `object`

Response formatting configuration.

| Field | Type | Required | Description |
| - | - | - | - |
| `useAiFormatting` | boolean | no | Whether to use AI for response formatting. |
| `formattingPrompt` | string | no | Custom prompt for AI formatting. |
| `responseAdapter` | string | no | Adapter name: `"broken-links-response"`, `"crawler-response"`, `"screenshot-response"`, `"accessibility-checker-response"`, `"og-image-checker-response"`. |
| `aiConfig` | object | no | Accepted and stored, but not consumed. See the note below. |

> [!NOTE]
>
> AI response formatting is not implemented yet. `useAiFormatting`, `formattingPrompt`, and `response.aiConfig` are accepted and stored, but nothing reads them at runtime, so setting them has no effect on the agent's output.

**postProcess** `object`

Post-processing pipeline configuration. All stages default to **enabled** when omitted or when `enabled` is not explicitly `false`.

| Field | Type | Required | Description |
| - | - | - | - |
| `guardrails` | object | no | `{ enabled?: boolean }`: finding quality pipeline — deduplicates findings (identical source URL + target text + occurrence + issue type) and sanitizes HTML/XSS from all text fields. |
| `deletePreviousSuggestions` | object | no | `{ enabled?: boolean }`: per-URL delete-and-recreate that clears the prior run's suggestions for the URL before writing the new ones. This is the active dedup mechanism. |
| `annotations` | object | no | `{ enabled?: boolean, strategy?: string }`: strategy is `"findings"`, `"word-level"`, `"page-level"`, or `"none"`. |
| `analytics` | object | no | `{ enabled?: boolean }`: analytics event tracking. |
| `matchAndMerge` | object | no | **Deprecated / ignored.** `{ enabled?: boolean }`: replaced by `deletePreviousSuggestions`. Still accepted for backward compatibility but has no effect. |
| `customProcessors` | string\[] | no | Custom post-processor names. |
| `findingEnrichment` | object | no | `{ commentFormat?: "plain" \| "legacy" }`: the layout of the comment each finding posts. Default for custom agents: `"legacy"`. See [Comment format](#comment-format). |

Unknown keys inside `postProcess` are rejected. Pin resolution (anchoring visual findings to element coordinates) always runs as part of the pipeline and is not configurable via this field.

**input** `object`

Input declaration configuration.

| Field | Type | Required | Description |
| - | - | - | - |
| `variableKeys` | string\[] | no | Variable names the agent expects in `payload.variables`. |
| `userContextFields` | object\[] | no | User-context field definitions (`{ id, title, type, required?, example?, defaultValue? }`). |
| `inputRequirements` | object | no | `{ requires?: string[], requiresOneOf?: string[] }`. |

Each `userContextFields[]` entry: `id` (min 1), `title` (min 1), `type` (`"string"` / `"number"` / `"boolean"`), optional `required` (boolean), optional `example` (string; sample value surfaced in setup UIs), optional `defaultValue` (string / number / boolean).

At run time, a field that is missing, `null`, or an empty string takes its `defaultValue` and then satisfies `required`.

An `id` cannot be one of the reserved keys every agent honors: the run-scope keys `focusIssueTypes`, `sourceAnnotationId`, `sourcePageUrl`, and `sourceElementXpath`, or the run-control keys `forceFullRun` and `changeDetection` (see [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md)). The request returns `INVALID_ARGUMENT` with `This userContextFields id is reserved for run scope or run control (focusIssueTypes, sourceAnnotationId, sourcePageUrl, sourceElementXpath, forceFullRun, changeDetection); give the field another id`. The key names are case-sensitive.

> [!NOTE]
>
> `input.supportedVariables` is **response-only**. It lists the template variables the agent's prompt can reference (e.g. `{{restApiData}}`, `{{memoryContext}}`) and is server-computed from `contextGathering.strategies` and `input.variableKeys`. On create, anything you send in this field is discarded. On a [version update](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md) it is recomputed only when those inputs change.

**scope** `object`

Scope and targeting configuration.

| Field | Type | Required | Description |
| - | - | - | - |
| `pageScope` | string\[] | no | URL glob patterns the agent runs on. |
| `pageScopeExclude` | string\[] | no | URL glob patterns to exclude. |
| `contentTypes` | string\[] | no | Content types the agent handles. |
| `crossPage` | object | no | Cross-page execution config. See below. |

`crossPage` is optional, but when present these three fields are **required**; omitting any of them fails validation.

| Field | Type | Required | Description |
| - | - | - | - |
| `enabled` | boolean | yes | Whether cross-page evaluation is on. |
| `targetProperty` | string | yes | The property being compared across pages. |
| `pageDiscovery` | string | yes | `"auto"` (crawl to discover pages) or `"manual"` (use `pages[]`). |
| `pages` | string\[] | no | Explicit page list. Pair with `pageDiscovery: "manual"`. |
| `sourceOfTruthKnowledgeSourceId` | string | no | Knowledge source to treat as the reference for the comparison. |

**setup** `object`

Tooling metadata for the setup assistant and checklist-to-agent converter. Not consumed by the agent pipeline at runtime.

| Field | Type | Required | Description |
| - | - | - | - |
| `setupSamples` | object\[] | no | Sample content plus the findings the agent should produce on it. |
| `checklistOrigin` | object | no | Provenance for an agent generated from a checklist. |

Each `setupSamples[]` entry:

| Field | Type | Required | Description |
| - | - | - | - |
| `content` | string | yes | The sample content the agent is evaluated against. |
| `source` | string | yes | `"synthetic"` or `"user-provided"`. |
| `findings` | object\[] | yes | Expected findings, each `{ message (required), elementSelector?, isCorrect? }`. |
| `pmVerdict` | string | no | Reviewer verdict: `"correct"` or `"incorrect"`. |
| `pmNotes` | string | no | Free-text reviewer notes. |

`checklistOrigin`:

| Field | Type | Required | Description |
| - | - | - | - |
| `checklistId` | string | yes | Source checklist ID. |
| `checklistVersion` | number | yes | Source checklist version. Integer ≥ 0. |
| `sectionRefs` | string\[] | yes | Checklist sections this agent covers. |
| `memoryRuleIds` | string\[] | yes | Knowledge rules this agent was derived from. |
| `deduplicatedFrom` | number | no | Count of source rules collapsed into this agent. Integer ≥ 0. |

#### Context gathering strategies

| 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, 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 ([see below](#rest-api-strategy-options)) |
| `none` | No context gathering (for service-only or text-only agents) |

#### Context gathering strategy options

Per-strategy overrides are supplied under `contextGathering.strategyOptions["<strategy>"]`. All are optional unless noted.

| Strategy | Option | Type | Description |
| - | - | - | - |
| `web-page-text` | `deviceType` | string | `"mobile"` / `"desktop"` (default `"desktop"`). |
| | `excludeIframes` | boolean | Exclude iframe content. Default `false`. |
| `web-page-screenshot` | `scrollBeforeCapture` | boolean | Scroll the full page before capture. |
| | `maxPageHeightPx` | number | Cap the captured page height. |
| | `waitUntil` | string | Puppeteer wait condition. |
| | `deviceType` | string | `"mobile"` / `"desktop"`. |
| `web-page-html` | `includeHead` | boolean | Include `<head>`. Default `true`. |
| | `includeBody` | boolean | Include `<body>`. Default `true`. |
| | `excludeIframes` | boolean | Default `false`. |
| | `waitUntil` | string | Puppeteer wait condition. |
| `web-page-css` | `includeInlineStyles` | boolean | Include inline `<style>` content. |
| `computed-styles` | `selectors` | string\[] | **Required**: CSS selectors to inspect. |
| | `properties` | string\[] | Override the curated default property list. |
| `sitemap-data` | `maxEntries` | number | Max sitemap entries. Default `500`. |
| `lighthouse` | `categories` | string\[] | Lighthouse categories to run. |
| | `formFactor` | string | `"mobile"` / `"desktop"`. |
| `rest-api` | *(see below)* | object | **Required** when `rest-api` is selected: [`rest-api` strategy options](#rest-api-strategy-options). |

#### `rest-api` strategy options

Required when `strategies` includes `"rest-api"`. Each configured endpoint is fetched at execution time and the resolved URL + description + JSON-stringified response is injected into the prompt via the `{{restApiData}}` template variable.

| Field | Type | Required | Description |
| - | - | - | - |
| `endpoints` | `RestApiEndpoint[]` | yes | 1–10 endpoints to fetch. |
| `maxResponseBytes` | number | no | Per-endpoint response-body cap. Default `1000000`, hard-capped `5000000`. |

**`RestApiEndpoint` fields:**

| Field | Type | Required | Description |
| - | - | - | - |
| `description` | string | yes | What this endpoint is about; surfaced in the prompt alongside the URL + response. |
| `url` | string | yes | Endpoint URL. Supports `{{variable}}` templating. SSRF-validated at fetch time (no internal/loopback/link-local hosts). |
| `method` | `"GET"`\|`"POST"`\|`"PUT"`\|`"PATCH"`\|`"DELETE"` | no | Default `"GET"`. |
| `id` | string | no | Stable endpoint identifier. |
| `name` | string | no | Human label. |
| `headers` | object | no | Non-secret headers (templated). |
| `query` | object | no | Query params (templated). |
| `body` | object \| string | no | Request body for write methods (templated). |
| `auth` | object | no | Discriminated union (`none`\|`bearer`\|`basic`\|`header`). Secret fields are encrypted at rest and redacted on read. |
| `cacheTtlSeconds` | number | no | In-process per-instance cache TTL. Default `0` (always fresh). Max `86400`. |
| `timeoutMs` | number | no | Per-request timeout. Default `10000`, hard-capped `30000`. |
| `responsePath` | string | no | Dot-path to extract a sub-field of the JSON response. |

**`auth` shapes:**

```JSON theme={null}
{ "type": "none" }
{ "type": "bearer", "token": "<secret>" }
{ "type": "basic", "username": "user", "password": "<secret>" }
{ "type": "header", "headers": { "X-Api-Key": "<secret>" } }
```

> [!NOTE]
>
> **Auth secret handling (redaction-on-read):** `token`, `password`, and `header` values are encrypted before the Firestore write and are never returned to clients. On read (Get / List Agents), encrypted secret fields are replaced with `"__redacted__"`. To rotate a secret, send the new plaintext value on update; to keep an existing secret, omit the field.

#### MCP servers (`mcp-tools` strategy)

When `execution.executionStrategy` is `"mcp-tools"`, the agent runs a model-driven tool loop: at execution time the engine connects to each remote [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server declared in `execution.mcpServers`, lists its tools, exposes them to the model, and runs a multi-turn call→tool→call loop until the model emits a final structured response. For example, a docs code-verification agent can check on-page snippets live against your documentation MCP server instead of a pre-ingested corpus.

> [!NOTE]
>
> The `"mcp-tools"` strategy is **provider-agnostic** (works on both Claude and Gemini) and **requires** a non-empty top-level `instructions` field **and** at least one entry in `execution.mcpServers`. Omitting either fails validation.

`execution.mcpServers` is an array of **1–5** server objects. Each server object is strictly validated (unknown keys rejected):

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | yes | Min 1 char. Stable identifier for the server (used in logs + findings). |
| `url` | string | yes | Remote MCP server URL. Must start with `http(s)://` or contain a `{{template}}` that resolves to one. SSRF-validated at connect time (no internal/loopback/link-local hosts; redirects re-validated, max 3 hops). |
| `name` | string | no | Human-readable label. |
| `description` | string | no | What this server provides (e.g. `"Velt docs MCP"`). |
| `transport` | string | no | Transport type. Only `"http"` is supported (Streamable HTTP with SSE fallback). Defaults to `"http"`. |
| `auth` | object | no | Auth config. Discriminated union (`none` \| `bearer` \| `basic` \| `header`); same shape as the `rest-api` strategy. Secret fields are encrypted at rest and redacted on read. |
| `allowedTools` | string\[] | no | Allowlist of tool names. When set, only these tools are exposed/callable. Up to 64 tools per server are exposed. |
| `timeoutMs` | number | no | Per-request timeout (ms) for connect/listTools/callTool. Default `30000`, hard-capped `120000`. |

**`auth` shapes** (identical to the `rest-api` strategy):

```JSON theme={null}
{ "type": "none" }
{ "type": "bearer", "token": "<secret>" }
{ "type": "basic", "username": "user", "password": "<secret>" }
{ "type": "header", "headers": { "X-Api-Key": "<secret>" } }
```

> [!NOTE]
>
> **Auth secret handling (redaction-on-read):** MCP `token`, `password`, and `header` values are encrypted before the Firestore write (using an MCP-specific encryption salt) and are never returned to clients. On read (Get / List Agents, List Versions), encrypted secret fields are replaced with `"__redacted__"`. To rotate a secret, send the new plaintext value on a [version update](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md); to keep an existing secret, omit the field.

#### AI config (provider / model)

`execution.aiConfig`, `contextGathering.aiConfig`, and `response.aiConfig` all accept the same strictly-validated object. Unknown keys are rejected.

| Field | Type | Description |
| - | - | - |
| `provider` | string | LLM provider: `"gemini"`, `"claude"`, or `"openai"`. Defaults to the platform default, Claude on Velt's hosted platform, when omitted. Persisted. |
| `model` | string | Accepted for backward compatibility and then discarded. Not persisted, and not validated against any allowlist. |
| `responseMimeType` | string | Accepted for backward compatibility and then discarded. Not persisted. |
| `maxToolTurns` | number | Tool-loop turn budget for the `mcp-tools` strategy. Integer `1..16`; out-of-range values are rejected at config time. Default: `8`. Persisted on `execution.aiConfig` only. |

> [!WARNING]
>
> Only `provider` survives a write here (plus `maxToolTurns` on `execution.aiConfig`). The effective model is resolved on every execution rather than frozen onto the agent, so pinning `model` at create time does nothing and returns `200` without complaint.
>
> To pin a model, send `aiConfig` on the request instead: see [Run Execution](https://velt.dev/docs/api-reference/rest-apis/v2/agents/execution/run.md). That one **is** validated against a model allowlist and returns `INVALID_ARGUMENT` for anything off it.

#### Execution strategy options

`execution.strategyOptions["<strategy>"]` carries per-strategy runtime overrides. The `stagehand-agent` strategy opens the page in a browser, and the agent's model drives it with browser tools in a loop. It accepts:

| Option | Type | Default | Description |
| - | - | - | - |
| `maxSteps` | number | `16` | Most tool-calling turns. A larger value is lowered to 16. |
| `systemPrompt` | string | | Text placed before the prompt the model receives. |
| `useStructuredOutput` | boolean | `true` | Return structured output. |
| `waitUntil` | string | `"networkidle2"` | `"domcontentloaded"` / `"load"` / `"networkidle2"`. |
| `navigationTimeout` | number | `30000` | Navigation timeout in ms. |
| `executeTimeout` | number | `540000` | Time limit in ms for the whole run: opening the browser, loading the first page, and the tool loop. Keep it below the agent's phase timeout. |
| `perStepTimeout` | number | `90000` | Time limit in ms for one step, a model turn plus its tool call. Past it, the model is asked for its final answer, which is kept. |
| `toolTimeout` | number | `30000` | Time limit in ms for one browser action or page read. |
| `excludeTools` | string\[] | | Browser tools to withhold from the model: any of `act`, `observe`, `act_on_element`, `snapshot`, `extract`, `goto`, `read_page`, `scroll`, `go_back`, `wait`. |

`mode` and `model` are accepted but ignored: the loop runs on the provider and model resolved for each execution, as for every AI strategy (see [AI config](#ai-config-provider--model)). A value of the wrong type is ignored, and the default applies.

> [!NOTE]
>
> When using `stagehand-agent`, set `contextGathering.strategies: ["none"]`; the agent handles navigation, interaction, and extraction itself. A run whose first page does not load fails with `The page could not be opened: <url> (<reason>).`

#### Knowledge (Memory-RAG)

`execution.knowledge` pulls workspace knowledge from Velt Memory into the prompt. Strictly validated. Only these four fields are accepted:

| Field | Type | Range | Description |
| - | - | - | - |
| `useMemory` | boolean | | When `true`, retrieves knowledge/patterns/activities 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. |

> [!WARNING]
>
> The legacy `sourceIds` field has been **removed** and `maxChunks` is now capped at **20** (previously 50). Sending `sourceIds` or any other extra key inside `knowledge` returns a `400 INVALID_ARGUMENT`.

#### Comment format

`postProcess.findingEnrichment.commentFormat` sets how each finding's comment text is laid out when the agent posts it as a comment annotation. Built-in agents use `"plain"`. Custom agents use `"legacy"` unless you set `"plain"`. Any other value returns `INVALID_ARGUMENT`.

| Format | `commentText` | `commentHtml` |
| - | - | - |
| `"legacy"` | `{title}: {description}`. When there is a suggestion, followed by a space, an em dash (U+2014), a space, and `Suggestion: {suggestion}`. | `<b>{title}</b><br/>{description}<br/><br/><b>Suggestion:</b> {suggestion}`. Values are not HTML-escaped, but link tags in them are removed and their text kept. |
| `"plain"` | `{title}`, a line break, `{description}`, a blank line, and `{suggestion}`, with no label. Empty parts are left out. | `<b>{title}</b><br/>{description}<br/><br/>{suggestion}`, with every value HTML-escaped. |

For a finding titled "CTA uses non-brand color", the two formats produce:

```json Plain theme={null}
{
  "commentText": "CTA uses non-brand color\nThe 'Buy now' button uses #FF5722 instead of #1A73E8\n\nChange background-color to #1A73E8",
  "commentHtml": "<b>CTA uses non-brand color</b><br/>The 'Buy now' button uses #FF5722 instead of #1A73E8<br/><br/>Change background-color to #1A73E8"
}
```

```json Legacy theme={null}
{
  "commentText": "CTA uses non-brand color: The 'Buy now' button uses #FF5722 instead of #1A73E8 \u2014 Suggestion: Change background-color to #1A73E8",
  "commentHtml": "<b>CTA uses non-brand color</b><br/>The 'Buy now' button uses #FF5722 instead of #1A73E8<br/><br/><b>Suggestion:</b> Change background-color to #1A73E8"
}
```

**Links in comments.** Comment HTML links only to addresses the agent's own code added, such as the Mobile Inspector's screenshot link, which opens in a new tab. A link written by a model, for example in a custom agent's title, description, or suggestion, appears as plain text, never as a link, in either format.

The setting applies to new runs. To change it on an existing agent, send `postProcess.findingEnrichment` to [Update Agent Version](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md).

#### Response Descriptions

All fields are optional strings that instruct the AI on how to populate each finding field:

| Field | Description |
| - | - |
| `summary` | Summary text of the overall analysis. |
| `title` | Short title of the finding. |
| `description` | Detailed description of the finding. |
| `severity` | Severity level. Values: `critical`, `high`, `medium`, `low`, `info`. |
| `targetText` | The exact text on the page this finding refers to. |
| `suggestion` | Suggested fix or recommendation. |
| `isPageLevel` | `"true"` for visual/layout findings; `"false"` when targetText is real DOM text. |
| `issueType` | Issue classification tag (short, lowercase, hyphenated). |
| `confidence` | Confidence score from 0 to 100. |
| `htmlSelector` | CSS selector of the DOM element. |
| `findingType` | Finding type classification. |

## **Example Requests**

#### 1. Minimal agent

```JSON theme={null}
{
  "data": {
    "name": "Simple Content Checker",
    "description": "Checks for broken images and missing alt text",
    "enabled": true,
    "instructions": "Check for broken images and missing alt text on the page.",
    "contextGathering": {
      "strategies": ["web-page-html"]
    },
    "execution": {}
  }
}
```

#### 2. Full custom agent with cross-page execution and Memory-RAG

```JSON theme={null}
{
  "data": {
    "name": "Brand Consistency Checker",
    "description": "Validates brand colors, logos, and typography across pages",
    "rawInstructions": "Check that all headings use the brand font 'Inter'. Verify the primary color #1A73E8 is used for CTAs.",
    "instructions": "Check that all headings use the brand font 'Inter'. Verify the primary color #1A73E8 is used for CTAs.",
    "enabled": true,
    "metadata": { "team": "growth", "owner": "jane" },
    "contextGathering": {
      "strategies": ["web-page-screenshot", "web-page-text", "web-page-html"],
      "strategyOptions": {
        "web-page-screenshot": { "scrollBeforeCapture": true }
      }
    },
    "execution": {
      "executionStrategy": "ai",
      "responseDescriptions": {
        "title": "Short name for the brand inconsistency",
        "severity": "One of: critical, high, medium, low",
        "suggestion": "Specific CSS or design fix",
        "issueType": "One of: brand-color, brand-font, brand-logo"
      },
      "knowledge": {
        "useMemory": true,
        "maxChunks": 10,
        "maxPatterns": 5,
        "maxActivities": 5
      }
    },
    "postProcess": {
      "guardrails": { "enabled": true },
      "deletePreviousSuggestions": { "enabled": true },
      "annotations": { "enabled": true, "strategy": "findings" },
      "analytics": { "enabled": true }
    },
    "input": {
      "inputRequirements": { "requires": ["url"] },
      "userContextFields": [
        { "id": "brand_color", "title": "Primary brand color?", "type": "string", "required": true },
        { "id": "brand_font", "title": "Heading font family?", "type": "string" }
      ]
    },
    "scope": {
      "pageScope": ["https://example.com/*"],
      "pageScopeExclude": ["https://example.com/admin/*"],
      "crossPage": {
        "enabled": true,
        "targetProperty": "brandConsistency",
        "pageDiscovery": "auto"
      }
    }
  }
}
```

#### 3. Agent with live REST API context

```JSON theme={null}
{
  "data": {
    "name": "Pricing Parity Checker",
    "description": "Compares on-page prices with the billing API",
    "enabled": true,
    "instructions": "Compare the price shown on the page with the price returned by the billing API and flag any mismatch.",
    "execution": {},
    "contextGathering": {
      "strategies": ["web-page-text", "rest-api"],
      "strategyOptions": {
        "rest-api": {
          "endpoints": [
            {
              "name": "Plan pricing",
              "description": "Canonical plan prices from the billing service",
              "url": "https://api.example.com/plans/{{variables.planId}}",
              "method": "GET",
              "headers": { "Accept": "application/json" },
              "auth": { "type": "bearer", "token": "sk_live_xxx" },
              "cacheTtlSeconds": 60,
              "responsePath": "data.plan"
            }
          ]
        }
      }
    },
    "input": { "variableKeys": ["planId"] }
  }
}
```

#### 4. Agent that verifies content against an MCP server (`mcp-tools`)

```JSON theme={null}
{
  "data": {
    "name": "Docs Code Verifier",
    "description": "Verifies on-page code snippets against the docs MCP",
    "enabled": true,
    "instructions": "For every code snippet on the page, use the documentation MCP tools to find the matching feature and verify the snippet is correct and up to date. Flag any snippet that does not match the docs.",
    "contextGathering": {
      "strategies": ["web-page-html"]
    },
    "execution": {
      "executionStrategy": "mcp-tools",
      "mcpServers": [
        {
          "id": "velt-docs",
          "name": "Velt Docs MCP",
          "description": "Live Velt documentation MCP server",
          "url": "https://velt.dev/docs/mcp",
          "transport": "http",
          "auth": { "type": "none" }
        }
      ]
    }
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `data.agentId` | string | Firestore document ID of the new agent |

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

**Errors:** `INVALID_ARGUMENT` (Zod validation failure, e.g. missing `name`, `description`, `enabled`, `contextGathering.strategies`, or `execution`; an unknown key inside `knowledge` or `postProcess`; an invalid `userContextFields.type`; a `userContextFields` id that is a reserved run-scope or run-control key; missing `instructions` for an AI/`stagehand-agent`/`mcp-tools` strategy; or missing/invalid `execution.mcpServers` when `executionStrategy` is `"mcp-tools"`) / `RESOURCE_EXHAUSTED` (workspace already has the maximum number of custom agents).

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}
```


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