> ## Documentation Index
> Fetch the complete documentation index at: https://velt-raghul-agent-docs.mintlify.site/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

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Min 1 char. Agent display name.
    </ParamField>

    <ParamField body="description" type="string">
      Human-readable description of what the agent does.
    </ParamField>

    <ParamField body="rawInstructions" type="string">
      Original user-provided instructions (before enhancement).
    </ParamField>

    <ParamField body="instructions" type="string">
      Processed/enhanced instructions used by the AI execution.
    </ParamField>

    <ParamField body="enabled" type="boolean">
      Whether the agent is active. Defaults to `true`.
    </ParamField>

    <ParamField body="metadata" type="object">
      Arbitrary metadata (e.g. `{ "type": "qa", "category": "brand" }`).
    </ParamField>

    <ParamField body="contextGathering" type="object">
      Context gathering configuration.

      | Field             | Type      | Required | Description                                                                                              |
      | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- |
      | `strategies`      | string\[] | no       | Min 1 if provided. See [context gathering strategies](/ai/agents/overview#context-gathering-strategies). |
      | `strategyOptions` | object    | no       | Per-strategy option overrides, keyed by strategy name.                                                   |
    </ParamField>

    <ParamField body="execution" type="object">
      Execution configuration.

      | Field                  | Type   | Required | Description                                                                                                                |
      | ---------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
      | `executionStrategy`    | string | no       | `"ai"` (default), `"service"`, `"service+ai"`, or `"stagehand-agent"`.                                                     |
      | `serviceId`            | string | no       | Required when `executionStrategy` is `"service"` or `"service+ai"`. Values: `"broken-links"`, `"crawler"`, `"screenshot"`. |
      | `responseDescriptions` | object | no       | Per-field descriptions guiding AI response shaping ([see below](#response-descriptions)).                                  |
      | `strategyOptions`      | object | no       | Per-strategy option overrides.                                                                                             |
      | `knowledge`            | object | no       | Knowledge integration: `{ sourceIds?: string[], useMemory?: boolean, maxChunks?: number }`. `maxChunks` range 1-50.        |
    </ParamField>

    <ParamField body="response" type="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"`. |
    </ParamField>

    <ParamField body="postProcess" type="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 }` — confidence-based filtering. Findings below 50% are suppressed.                       |
      | `matchAndMerge`    | object    | no       | `{ enabled?: boolean }` — deduplication against previous execution findings.                                   |
      | `pinResolution`    | object    | no       | `{ enabled?: boolean }` — anchor pin resolution for visual annotations.                                        |
      | `annotations`      | object    | no       | `{ enabled?: boolean, strategy?: string }` — strategy: `"findings"`, `"word-level"`, `"page-level"`, `"none"`. |
      | `analytics`        | object    | no       | `{ enabled?: boolean }` — analytics event tracking.                                                            |
      | `customProcessors` | string\[] | no       | Custom post-processor names.                                                                                   |
    </ParamField>

    <ParamField body="input" type="object">
      Input declaration configuration.

      | Field               | Type      | Required | Description                                                                       |
      | ------------------- | --------- | -------- | --------------------------------------------------------------------------------- |
      | `variableKeys`      | string\[] | no       | Variable names the agent expects in the payload.                                  |
      | `userContextFields` | object\[] | no       | User-context field definitions (`{ id, title, type, required?, 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 `defaultValue`.
    </ParamField>

    <ParamField body="scope" type="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 (`enabled`, `targetProperty`, `pageDiscovery`, optional `pages[]`, `sourceOfTruthKnowledgeSourceId`). |
    </ParamField>

    <ParamField body="setup" type="object">
      Tooling metadata for the setup assistant and checklist-to-agent converter. Not consumed by the agent pipeline at runtime.

      Fields: `setupSamples[]`, `checklistOrigin`.
    </ParamField>
  </Expandable>
</ParamField>

#### 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. |
| `htmlSelector` | CSS selector of the DOM element.                                             |
| `issueType`    | Issue type for match-and-merge keying (short, lowercase, hyphenated).        |
| `confidence`   | Confidence score from 0 to 100.                                              |
| `findingType`  | Finding type classification.                                                 |

## **Example Requests**

#### 1. Minimal agent

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

#### 2. Full custom agent with cross-page execution

```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": { "type": "qa", "category": "brand" },
    "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": {
        "sourceIds": ["ks_brand_guidelines_v2"],
        "useMemory": true,
        "maxChunks": 10
      }
    },
    "postProcess": {
      "guardrails": { "enabled": true },
      "matchAndMerge": { "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",
        "sourceOfTruthKnowledgeSourceId": "ks_brand_guidelines_v2"
      }
    }
  }
}
```

# 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`, missing `apiKey`, invalid `userContextFields.type`) / `RESOURCE_EXHAUSTED` (workspace already has the maximum number of custom agents).

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