Workflow: Agent Setup

This guide walks through creating an AI Agent from scratch, configuring scenarios, and running your first execution. By the end you will have a working agent with an API key, a linked scenario, and a verified run.

Prerequisites

• Role: Account Owner, Admin, or Super Admin
• Prompts (optional): If using STORED_PROMPT or CHAIN scenarios, create the prompts first in Prompt Git
• Routing Policy (optional): Create one in Admin > Routing if you need specific provider rules
• Access Profile (optional): Create one in Admin > Access Profiles if you need token or permission limits

Quick start (5 minutes)

1. Create the agent

Navigate to Admin > Agents and click Create New Agent.

Name:            SupportBot
Description:     Handles tier-1 customer support queries
Use Case:        IT Support Triage
Persona Name:    SupportBot
Persona Summary: Classifies incoming support tickets and suggests solutions
Persona Tone:    Friendly, professional
Persona Role:    autonomous_system
Default Quality: fast

Click Save. Copy the generated API key (vpak_...) immediately.

2. Create a scenario

Navigate to Admin > AI Agent > Scenarios and click Create Scenario.

Name:         Ticket Classification
Type:         GATEWAY
Trigger:      MANUAL
Execution:    AUTONOMOUS

Add a runtime prompt:

{
  "prompt": "Classify this support ticket into one of: billing, technical, account, other. Return JSON: {\"category\": \"...\", \"priority\": \"high|medium|low\", \"suggestedAction\": \"...\"}",
  "systemPrompt": "You are a support ticket classifier. Be concise and accurate.",
  "temperature": 0.1,
  "maxTokens": 200
}

Click Save.

3. Run the scenario

Go to Admin > AI Agent and click Run. The dashboard shows:

• Status: RUNNING then SUCCESS
• Provider and model used
• Token count
• Full response

4. Use the agent via API

curl -X POST https://app.veriprompt.tech/api/gateway/execute \
  -H "Authorization: Bearer vpak_YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Customer says: I cannot log in to my account since yesterday. Error code 403.",
    "maxTokens": 200
  }'

The agent's routing policy, access profile, and quality setting are applied automatically.

---

Detailed setup

Step 1: Plan your agent

Before creating, decide:

Question	Example answer
What task does it perform?	Classify support tickets
How often does it run?	On every new ticket (API-triggered)
Which AI providers should it use?	OpenAI GPT-4o, with Anthropic Claude fallback
What quality/cost tradeoff?	fast for ticket classification, quality for report generation
Does it need file attachments?	No (text-only tickets)
Who can trigger it?	External webhook from ticketing system

Step 2: Create supporting resources (if needed)

Routing Policy (optional):

1. Go to Admin > Routing Policies
2. Create a policy: name support-fast, prefer gpt-4o-mini, fallback to claude-haiku
3. Note the policy ID

Access Profile (optional):

1. Go to Admin > Access Profiles
2. Create a profile: name support-limited, max 500 tokens/request, 10,000 tokens/month
3. Note the profile ID

Stored Prompt (optional):

1. Go to Prompts > Repository
2. Create a prompt with your classification template
3. Publish a version
4. Note the prompt ID

Step 3: Create the agent

Via UI:

1. Go to Admin > Agents
2. Click Create New Agent
3. Fill in all fields (see field reference below)
4. Click Save

Via API:

curl -X POST https://app.veriprompt.tech/api/v1/agents \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SupportBot",
    "description": "Tier-1 support ticket classifier",
    "useCaseId": "it-support-triage",
    "personaName": "SupportBot",
    "personaSummary": "Classifies tickets and suggests solutions",
    "personaTone": "Friendly, professional",
    "personaRole": "autonomous_system",
    "defaultQuality": "fast",
    "routingPolicyId": "pol_support_fast",
    "agentAccessProfileId": "ap_support_limited",
    "mockCompanyName": "Demo Corp",
    "mockCompanyAccount": "demo-corp-001",
    "visibility": "company"
  }'

Save the returned apiKey value - it is shown only once.

Step 4: Create scenarios

An agent can have multiple scenarios. Common patterns:

Pattern A: Simple gateway call

Best for dynamic, ad-hoc prompts where the input changes every time.

curl -X POST https://app.veriprompt.tech/api/admin/ai-agent/scenarios \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ticket Classifier",
    "type": "GATEWAY",
    "triggerType": "MANUAL",
    "executionMode": "AUTONOMOUS",
    "runtimePrompt": {
      "prompt": "Classify this ticket: {{ticket_text}}",
      "systemPrompt": "You are a support classifier.",
      "temperature": 0.1,
      "maxTokens": 200
    }
  }'

Pattern B: Stored prompt execution

Best for versioned, tested prompts that rarely change.

curl -X POST https://app.veriprompt.tech/api/admin/ai-agent/scenarios \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Summary",
    "type": "STORED_PROMPT",
    "storedPromptId": "sp_weekly_summary",
    "triggerType": "SCHEDULED"
  }'

Pattern C: Document analysis with attachments

Best for scenarios that process uploaded files.

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

# Step 2: Create scenario with file reference
curl -X POST https://app.veriprompt.tech/api/admin/ai-agent/scenarios \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quarterly Compliance Review",
    "type": "GATEWAY",
    "triggerType": "MANUAL",
    "executionMode": "SUPERVISED",
    "runtimePrompt": {
      "prompt": "Review the attached report for compliance issues.",
      "systemPrompt": "Return JSON: {\"issues\": [{\"severity\": \"...\", \"description\": \"...\", \"regulation\": \"...\"}]}",
      "temperature": 0.2,
      "maxTokens": 2000
    },
    "attachments": [
      { "type": "file", "fileId": "upl_123", "fileName": "quarterly_report.pdf" }
    ]
  }'

Pattern D: Multi-step prompt chain

Best for complex workflows with multiple sequential steps.

curl -X POST https://app.veriprompt.tech/api/admin/ai-agent/scenarios \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Full Compliance Pipeline",
    "type": "CHAIN",
    "chainId": "chain_compliance_pipeline",
    "triggerType": "SCHEDULED",
    "executionMode": "AUTONOMOUS"
  }'

Step 5: Configure agent settings

Navigate to Admin > AI Agent > Settings to configure:

Setting	Recommendation
Auto-run	Enable for scheduled scenarios
Frequency	Match your business cadence (hourly, daily, weekly)
Notification email	Set to your team's alerts inbox
Run retention	Keep 50-100 runs for audit; prune older ones
Guardrail checklist	Enable for compliance-sensitive agents

Step 6: Test and verify

1. Run manually from the AI Agent dashboard
2. Check the results - verify status is SUCCESS
3. Review the response - confirm output format matches expectations
4. Check the diff - compare with previous runs to detect drift
5. Monitor tokens - ensure usage is within budget

Step 7: Link API keys (optional)

If you need separate API keys with different permissions for the same agent:

1. Go to Admin > API Management
2. Click Create API Key
3. The "Link to Agent" dropdown appears (only when agents exist)
4. Select your agent
5. The key inherits the agent's access profile and routing policy

---

Agent field reference

Field	Required	Description
name	Yes	Display name for the agent
description	No	What the agent does
useCaseId	Yes	Pre-built template ID
personaName	Yes	Human-readable persona identity
personaSummary	Yes	One-line persona description
personaTone	No	Communication style
personaRole	No	Role from the persona catalog
successMetrics	No	How to measure agent effectiveness
defaultQuality	No	cheap, fast, secure, or quality
systemPrompt	No	Default system instruction for all requests
routingPolicyId	No	Link to a routing policy
providerGroupId	No	Restrict to specific providers
agentAccessProfileId	No	Enforce token/permission limits
protectivePromptId	No	Add safety guardrails
visibility	No	company (default), project, or public
mockCompanyName	Yes	Test company name for simulation
mockCompanyAccount	Yes	Test account identifier
linkedPromptId	No	Default prompt from the repository
usagePatternId	No	How the agent uses VeriPrompt features
usageModules	No	Array of enabled capability modules

Scenario field reference

Field	Required	Description
name	Yes	Scenario display name
type	Yes	GATEWAY, STORED_PROMPT, PROMPT_VERSION, CHAIN, or PROJECT_GATEWAY
triggerType	No	MANUAL (default), SCHEDULED, or EXTERNAL_SIGNAL
executionMode	No	AUTONOMOUS (default), INTERACTIVE, or SUPERVISED
storedPromptId	Conditional	Required for STORED_PROMPT type
promptVersionId	Conditional	Required for PROMPT_VERSION type
chainId	Conditional	Required for CHAIN type
projectGatewayId	Conditional	Required for PROJECT_GATEWAY type
runtimePrompt	Conditional	Required for GATEWAY type. Object with prompt, systemPrompt, temperature, maxTokens
attachments	No	Array of {type, content/url/fileId} objects
routingPolicyId	No	Override the agent's default routing
providerGroupId	No	Override the agent's default providers
warningThresholds	No	Array of {warningType, threshold, unit}

Common workflows

Cloning an agent

Quickly duplicate an agent with all its settings:

curl -X POST https://app.veriprompt.tech/api/v1/agents/agent_compliancebot_001/clone \
  -H "Authorization: Bearer YOUR_API_KEY"

The clone gets a new name (suffixed with "- Copy"), a new agent ID, and a fresh API key.

Regenerating an API key

If a key is compromised:

curl -X POST https://app.veriprompt.tech/api/v1/agents/agent_compliancebot_001/regenerate-key \
  -H "Authorization: Bearer YOUR_API_KEY"

The old key is immediately invalidated.

Archiving a scenario

Soft-delete a scenario (keeps run history):

curl -X DELETE https://app.veriprompt.tech/api/admin/ai-agent/scenarios/scenario_daily_compliance \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

Problem	Solution
Agent creation fails	Ensure all required fields (name, useCaseId, personaName, personaSummary, mockCompanyName, mockCompanyAccount) are provided
Scenario run returns empty response	Check that the runtime prompt or stored prompt has content. Verify the routing policy includes active providers.
API key returns 403	The key may be linked to an access profile that blocks the requested operation. Check the profile's allowed providers and token limits.
Scheduled runs not triggering	Verify auto-run is enabled in Agent Settings and the frequency is configured.
High token usage	Review maxTokens in scenario runtime prompts. File attachments are truncated at 5,000 characters but can still be large.
"No agents found" in API key modal	Create at least one agent first. The "Link to Agent" dropdown only appears when agents exist.

Next steps

• AI Agents Feature Reference - Full feature overview with all configuration options
• Agent Scenarios API - Detailed API reference for scenario management
• Prompt Chaining - Build multi-step chains for complex agents
• Synthetic Testing - Test agent outputs for quality and consistency