Create Agent

POST /v2/agents/create

Create Agent

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/create \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "name": "<string>",
    "description": "<string>",
    "rawInstructions": "<string>",
    "instructions": "<string>",
    "enabled": true,
    "metadata": {},
    "contextGathering": {},
    "execution": {},
    "response": {},
    "postProcess": {},
    "input": {},
    "scope": {},
    "setup": {}
  }
}
'

import requests

url = "https://api.velt.dev/v2/agents/create"

payload = { "data": {
        "name": "<string>",
        "description": "<string>",
        "rawInstructions": "<string>",
        "instructions": "<string>",
        "enabled": True,
        "metadata": {},
        "contextGathering": {},
        "execution": {},
        "response": {},
        "postProcess": {},
        "input": {},
        "scope": {},
        "setup": {}
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      name: '<string>',
      description: '<string>',
      rawInstructions: '<string>',
      instructions: '<string>',
      enabled: true,
      metadata: {},
      contextGathering: {},
      execution: {},
      response: {},
      postProcess: {},
      input: {},
      scope: {},
      setup: {}
    }
  })
};

fetch('https://api.velt.dev/v2/agents/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/agents/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'name' => '<string>',
        'description' => '<string>',
        'rawInstructions' => '<string>',
        'instructions' => '<string>',
        'enabled' => true,
        'metadata' => [
                
        ],
        'contextGathering' => [
                
        ],
        'execution' => [
                
        ],
        'response' => [
                
        ],
        'postProcess' => [
                
        ],
        'input' => [
                
        ],
        'scope' => [
                
        ],
        'setup' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/agents/create"

	payload := strings.NewReader("{\n  \"data\": {\n    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"enabled\": true,\n    \"metadata\": {},\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/create")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"enabled\": true,\n    \"metadata\": {},\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/agents/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"name\": \"<string>\",\n    \"description\": \"<string>\",\n    \"rawInstructions\": \"<string>\",\n    \"instructions\": \"<string>\",\n    \"enabled\": true,\n    \"metadata\": {},\n    \"contextGathering\": {},\n    \"execution\": {},\n    \"response\": {},\n    \"postProcess\": {},\n    \"input\": {},\n    \"scope\": {},\n    \"setup\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}

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.

Body

Params

data · object · required

Show properties

name · string · required

Min 1 char. Agent display name.

description · string

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.

enabled · boolean

Whether the agent is active. Defaults to true.

metadata · object

Arbitrary metadata (e.g. { "type": "qa", "category": "brand" }).

contextGathering · object

Context gathering configuration.

Field	Type	Required	Description
strategies	string[]	no	Min 1 if provided. See context gathering strategies.
strategyOptions	object	no	Per-strategy option overrides, keyed by strategy name.

execution · 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).
strategyOptions	object	no	Per-strategy option overrides.
knowledge	object	no	Knowledge integration: { sourceIds?: string[], useMemory?: boolean, maxChunks?: number }. maxChunks range 1-50.

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

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 } — 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.

input · 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.

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 (enabled, targetProperty, pageDiscovery, optional pages[], sourceOfTruthKnowledgeSourceId).

setup · object

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

Fields: setupSamples[], checklistOrigin.

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

{
  "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

{
  "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

{
  "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

{
  "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).

{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}