Skip to main content
POST
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

string
required
Your API key.
string
required

Body

Params

object
required

Context gathering strategies

Context gathering strategy options

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

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. RestApiEndpoint fields: auth shapes:
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) 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.
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): auth shapes (identical to the rest-api strategy):
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; 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.
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. 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: 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). A value of the wrong type is ignored, and the default applies.
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:
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. For a finding titled “CTA uses non-brand color”, the two formats produce:
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.

Response Descriptions

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

Example Requests

1. Minimal agent

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

3. Agent with live REST API context

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

Response

Success Response

Failure Response

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