AI Agents

AI Agents in VeriPrompt are reusable, configurable workflows that bundle prompts, routing rules, and personas into a single deployable unit. They are designed for repeated tasks such as support responses, compliance checks, content generation, and autonomous data processing.

Overview

Concept	Description
Agent	A named entity with a persona, system prompt, routing policy, and optional access profile. Each agent gets its own API key.
Scenario	An execution configuration linked to an agent. Defines what the agent runs (a stored prompt, a gateway call, a chain, etc.).
Run	A single execution of a scenario. Captures request/response, token usage, provider info, and warnings.

When to use agents

You need a consistent, repeatable workflow across a team or product.
You want a single API key that enforces a specific routing policy and access profile.
You run scheduled or automated prompts (compliance scans, report generation, monitoring).
You need audit trails with per-run token tracking and provider attribution.

Access and permissions

Role	Can create agents	Can run scenarios	Can view runs
Super Admin	Yes	Yes	Yes
Account Owner	Yes	Yes	Yes
Admin	Yes	Yes	Yes
Ranger	View only	No	No
User	No	No	No

Navigate to Admin > AI Agent in the sidebar to access the agent dashboard.

Key concepts

Personas

Every agent has a persona that shapes its behavior:

Name and Summary - human-readable identity (e.g. "ComplianceBot - Reviews financial reports for regulatory flags")
Tone - communication style (formal, casual, technical)
Role - one of the predefined roles:
- software_developer_integrator - builds and integrates AI features
- prompt_engineer - designs and optimizes prompts
- service_reseller - white-labels VeriPrompt for clients
- autonomous_system - runs without human intervention
- agentic_entity - multi-step decision-making agent
- privacy_individual - handles PII-sensitive workflows
- compliance_security_custodian - enforces regulatory rules
- approval_officer - reviews and approves outputs

Use cases

VeriPrompt provides pre-built use case templates to accelerate agent setup:

Use Case	Description
Financial Compliance Support	Regulatory report scanning and flag detection
Healthcare Patient Intake	Structured patient data collection
E-commerce Personal Shopper	Product recommendations and comparison
Legal Contract Review	Clause extraction and risk assessment
IT Support Triage	Issue classification and routing
Content Generation	Marketing copy and blog post creation

Each template includes suggested persona guidance, required inputs, and success metrics.

Scenario types

Scenarios define what happens when an agent runs:

Type	Description	Use when...
`GATEWAY`	Sends a runtime prompt directly to the AI gateway	You need ad-hoc, dynamic prompts
`STORED_PROMPT`	Executes a prompt from your Prompt Repository	You have a versioned, tested prompt
`PROMPT_VERSION`	Executes a specific version of a stored prompt	You need deterministic, pinned behavior
`CHAIN`	Runs a multi-step prompt chain sequentially	You need complex, multi-step workflows
`PROJECT_GATEWAY`	Uses a custom project gateway endpoint	You have a specialized provider setup

Execution modes

Mode	Description
`AUTONOMOUS`	Runs without human oversight
`INTERACTIVE`	Pauses for human input between steps
`SUPERVISED`	Requires approval before sending output

Trigger types

Trigger	Description
`MANUAL`	Triggered by clicking "Run" in the dashboard or calling the API
`SCHEDULED`	Runs on a configurable schedule (frequency set in agent settings)
`EXTERNAL_SIGNAL`	Triggered by a webhook or external system

How to create an agent

Step 1: Navigate to Agent Setup

Go to Admin > Agents in the sidebar (or /admin/agents).

Click Create New Agent.

Step 2: Configure the basics

Fill in the required fields:

Name:              ComplianceBot
Description:       Reviews financial reports for regulatory compliance
Use Case:          Financial Compliance Support

Step 3: Define the persona

Persona Name:      ComplianceBot
Persona Summary:   Scans documents for regulatory flags and summarizes findings
Persona Tone:      Professional, precise
Persona Role:      compliance_security_custodian
Success Metrics:   Flag detection rate > 95%, false positive rate < 5%

Step 4: Configure routing and access

Setting	Example	Purpose
Routing Policy	`compliance-high-accuracy`	Controls which providers and models are used
Provider Group	`enterprise-providers`	Restricts to approved providers
Access Profile	`compliance-restricted`	Enforces token limits and allowed operations
Protective Prompt	`financial-guardrail`	Adds safety instructions to every request
Default Quality	`quality`	Prefers accuracy over speed/cost

Step 5: Set usage pattern

Choose how the agent will interact with VeriPrompt:

gateway_anonymization_only - only uses the gateway for anonymous routing
full_stack_prompt_to_gateway - uses prompt repository + gateway (recommended)
prompt_git_byo_credentials - manages prompts in VeriPrompt, uses own provider keys
synthetic_qa_protective_addon - includes synthetic testing and guardrails

Step 6: Save and get the API key

After saving, VeriPrompt automatically generates an API key for the agent (prefixed vpak_). Copy it immediately - it cannot be retrieved later.

Agent API Key:  vpak_abc123def456...

You can also create additional gateway API keys for the agent in Admin > API Management and link them via the "Link to Agent" dropdown.

How to create and run scenarios

Step 1: Open the Scenario Manager

Navigate to Admin > AI Agent > Scenarios (or /admin/ai-agent/scenarios).

Click Create Scenario.

Step 2: Configure the scenario

Example: Gateway scenario with a runtime prompt

json

{
  "name": "Daily Compliance Check",
  "type": "GATEWAY",
  "triggerType": "MANUAL",
  "executionMode": "AUTONOMOUS",
  "runtimePrompt": {
    "prompt": "Review the attached document for regulatory compliance issues. List each issue with severity (high/medium/low) and the relevant regulation.",
    "systemPrompt": "You are a financial compliance expert. Return structured JSON.",
    "temperature": 0.2,
    "maxTokens": 2000
  }
}

Example: Stored Prompt scenario

json

{
  "name": "Weekly Report Summary",
  "type": "STORED_PROMPT",
  "storedPromptId": "sp_weekly_summary_v3",
  "triggerType": "SCHEDULED"
}

Step 3: Add file attachments (optional)

Scenarios support three attachment types:

Type	Field	Example
Inline text	`content`	`"Focus on sections 3 and 7"`
URL	`url`	`"https://example.com/report.pdf"`
Uploaded file	`fileId`	`"upl_123"` (from `/api/v1/files/upload`)

json

{
  "attachments": [
    { "type": "text", "content": "Highlight any warnings above medium severity." },
    { "type": "file", "fileId": "upl_123", "fileName": "guardrails.pdf" }
  ]
}

To upload a file first:

bash

curl -X POST https://app.veriprompt.tech/api/v1/files/upload?processContent=true&category=agent-scenario \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf"

Step 4: Configure warning thresholds (optional)

Monitor for rate limits and usage spikes:

json

{
  "warningThresholds": [
    { "warningType": "SUPABASE_RATE_LIMIT", "threshold": 1, "unit": "COUNT" },
    { "warningType": "SUPABASE_BILLABLE_TIER", "threshold": 80, "unit": "PERCENT" }
  ]
}

Step 5: Run the scenario

From the dashboard: Click the Run button on the AI Agent dashboard (/admin/ai-agent).

Via API:

bash

curl -X POST https://app.veriprompt.tech/api/admin/ai-agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scenarioId": "scenario_daily_compliance" }'

Step 6: Review results

Each run is recorded with:

Status: SUCCESS, WARNING, FAILED, or CANCELLED
Provider: which AI provider and model was used
Tokens: prompt tokens, completion tokens, total
Response: full output payload
Diff: comparison with the previous run (for detecting output drift)
Events: timeline of INFO, WARNING, and ERROR events

View results at Admin > AI Agent or via:

bash

GET /api/admin/ai-agent/results
GET /api/admin/ai-agent/results/{runId}

Agent settings

Configure agent behavior in Admin > AI Agent > Settings (/admin/ai-agent/settings):

Setting	Description
Auto-run	Enable/disable scheduled execution
Run frequency	How often scheduled scenarios run
Notification email	Email address for run alerts
Run retention	Maximum number of runs to keep (older runs are pruned)
Guardrail checklist	Pre-run safety checks that must pass

API reference

Agent CRUD

Method	Endpoint	Description
`POST`	`/api/v1/agents`	Create a new agent
`GET`	`/api/v1/agents`	List all agents for your company
`GET`	`/api/v1/agents/{agentId}`	Get agent details
`PUT`	`/api/v1/agents/{agentId}`	Update agent configuration
`POST`	`/api/v1/agents/{agentId}/clone`	Clone an agent
`POST`	`/api/v1/agents/{agentId}/regenerate-key`	Regenerate the agent API key
`GET`	`/api/v1/agents/{agentId}/gateway-keys`	List linked gateway API keys

Scenario management

Method	Endpoint	Description
`POST`	`/api/admin/ai-agent/scenarios`	Create a scenario
`GET`	`/api/admin/ai-agent/scenarios`	List all scenarios
`GET`	`/api/admin/ai-agent/scenarios/{scenarioId}`	Get scenario details
`PUT`	`/api/admin/ai-agent/scenarios/{scenarioId}`	Update a scenario
`DELETE`	`/api/admin/ai-agent/scenarios/{scenarioId}`	Archive a scenario

Execution

Method	Endpoint	Description
`POST`	`/api/admin/ai-agent/run`	Trigger a scenario run
`GET`	`/api/admin/ai-agent/status`	Get current agent status
`GET`	`/api/admin/ai-agent/results`	List recent runs
`GET`	`/api/admin/ai-agent/results/{runId}`	Get run details with diff
`GET`	`/api/admin/ai-agent/chains`	List available prompt chains

Create agent example

bash

curl -X POST https://app.veriprompt.tech/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ComplianceBot",
    "description": "Scans financial reports for regulatory issues",
    "useCaseId": "financial-compliance-support",
    "personaName": "ComplianceBot",
    "personaSummary": "Reviews documents for compliance flags",
    "personaTone": "Professional",
    "personaRole": "compliance_security_custodian",
    "defaultQuality": "quality",
    "mockCompanyName": "Acme Corp",
    "mockCompanyAccount": "acme-corp-001"
  }'

Response:

json

{
  "agent": {
    "id": "clx123...",
    "agentId": "agent_compliancebot_001",
    "name": "ComplianceBot",
    "apiKeyPrefix": "vpak_abc1"
  },
  "apiKey": "vpak_abc123def456..."
}

Troubleshooting

Problem	Cause	Solution
Scenario run fails with "provider unavailable"	Selected provider is down or rate-limited	Check provider health at `/api/gateway/health`. Update routing policy to include fallback providers.
Agent API key returns 401	Key is inactive, expired, or revoked	Regenerate the key via `/api/v1/agents/{agentId}/regenerate-key` or create a new one in API Management.
"Link to Agent" dropdown is empty	No agents exist yet	Create an agent first, then the dropdown will populate when creating API keys.
Run shows WARNING status	Supabase rate limit or usage threshold exceeded	Review warning thresholds in scenario settings. Reduce execution frequency or increase limits.
File attachment not included in run	File ID does not belong to your company	Ensure the file was uploaded under the same company account.
Token usage unexpectedly high	Large file attachments or verbose system prompts	Files are truncated at 5,000 characters. Review prompt length and set `maxTokens` limits.

Agent Setup Workflow - Step-by-step workflow guide
Agent Scenarios API - Detailed API reference with file attachments
AI Gateway - How routing and provider selection works
Prompt Git & Versioning - Managing prompts used by agents
Access Profiles - Controlling agent permissions

AI Agents ​

Overview ​

When to use agents ​

Access and permissions ​

Key concepts ​

Personas ​

Use cases ​

Scenario types ​

Execution modes ​

Trigger types ​

How to create an agent ​

Step 1: Navigate to Agent Setup ​

Step 2: Configure the basics ​

Step 3: Define the persona ​

Step 4: Configure routing and access ​

Step 5: Set usage pattern ​

Step 6: Save and get the API key ​

How to create and run scenarios ​

Step 1: Open the Scenario Manager ​

Step 2: Configure the scenario ​

Step 3: Add file attachments (optional) ​

Step 4: Configure warning thresholds (optional) ​

Step 5: Run the scenario ​

Step 6: Review results ​

Agent settings ​

API reference ​

Agent CRUD ​

Scenario management ​

Execution ​

Create agent example ​

Troubleshooting ​

Related guides ​

AI Agents

Overview

When to use agents

Access and permissions

Key concepts

Personas

Use cases

Scenario types

Execution modes

Trigger types

How to create an agent

Step 1: Navigate to Agent Setup

Step 2: Configure the basics

Step 3: Define the persona

Step 4: Configure routing and access

Step 5: Set usage pattern

Step 6: Save and get the API key

How to create and run scenarios

Step 1: Open the Scenario Manager

Step 2: Configure the scenario

Step 3: Add file attachments (optional)

Step 4: Configure warning thresholds (optional)

Step 5: Run the scenario

Step 6: Review results

Agent settings

API reference

Agent CRUD

Scenario management

Execution

Create agent example

Troubleshooting

Related guides