Agents Overview

Agents are production-ready deployments of your prompts that can be called via API from any application.

What are Agents?

An Agent is a prompt that has been:

✅ Version pinned - Uses a specific prompt version for stability
✅ Configured - Has defined variables, model settings, and rate limits
✅ API-enabled - Can be called externally via REST API
✅ Secured - Protected by API keys with customizable permissions

Think of Agents as AI microservices - each one does a specific task reliably and can be integrated into your applications.

Why Use Agents?

For Developers

API-First: RESTful endpoints with standard authentication
Version Control: Pin specific prompt versions - no surprises in production
Rate Limiting: Built-in protection against abuse
Monitoring: Track usage, performance, and costs

For Product Teams

No Code Changes: Update prompts without deploying code
A/B Testing: Deploy multiple agents with different strategies
Iteration: Improve prompts based on real usage data
Scalability: Handle thousands of requests per minute

For Business

Consistency: Same quality output every time
Control: Manage who can access what
Analytics: Understand usage patterns and ROI
Cost Management: Monitor and optimize AI spending

Agent Architecture

graph TB
    A[Your Application] -->|HTTPS Request| B[PrompTick API]
    B -->|Validate API Key| C{Authorized?}
    C -->|No| D[401 Unauthorized]
    C -->|Yes| E{Rate Limit OK?}
    E -->|No| F[429 Too Many Requests]
    E -->|Yes| G[Load Agent Config]
    G --> H[Load Pinned Prompt Version]
    H --> I[Substitute Variables]
    I --> J[Execute AI Model]
    J --> K[Return Response]
    K --> L[Log Analytics]
    L --> A

Agent Components

1. Prompt Version (Pinned)

Each agent is linked to a specific version of a prompt:

{
  promptId: "prompt_abc123",
  promptVersionId: "version_xyz789",
  promptVersionLabel: "V3"  // Human-readable label
}

Why pinning matters:

✅ Production stability - prompts don't change unexpectedly
✅ Rollback capability - easily revert to previous versions
✅ Testing - validate specific versions before deployment

2. Configuration

Override prompt defaults per agent:

{
  agentConfig: {
    model: "gemini-1.5-pro",      // Can differ from prompt default
    temperature: 0.7,              // Control creativity
    maxTokens: 1000,               // Limit response length
    topP: 0.95                     // Nucleus sampling
  }
}

3. Variables

Define what inputs the agent expects:

{
  requiredVariables: ["product_name", "target_audience"],
  optionalVariables: ["tone", "length"],
  defaultVariableValues: {
    tone: "professional",
    length: "medium"
  }
}

4. API Access Control

{
  apiEnabled: true,              // Enable external API access
  visibility: "private",         // private | public
  rateLimits: {
    requestsPerMinute: 100,
    requestsPerHour: 5000,
    requestsPerDay: 100000
  }
}

Agent Lifecycle

stateDiagram-v2
    [*] --> Draft: Create Agent
    Draft --> Testing: Enable API
    Testing --> Deployed: Mark as Deployed
    Deployed --> Testing: Rollback
    Deployed --> Paused: Disable
    Paused --> Deployed: Re-enable
    Testing --> [*]: Delete
    Paused --> [*]: Delete

Status Stages

Status	Description	API Access
Draft	Initial creation, not ready	❌ Disabled
Testing	Under validation	✅ Enabled (limited)
Deployed	Production-ready	✅ Fully enabled
Paused	Temporarily disabled	❌ Disabled

Agent Management Interface

PrompTick provides a dedicated interface for managing agents across all your projects.

Agents Page (`/agents`)

The unified agents page gives you a bird's-eye view of all your agents:

Cross-Project View - See agents from all projects in one place
Filtering - Filter by project, status, category, or tags
Search - Quickly find agents by name or description
Stats Dashboard - Overview of total agents, executions, and costs
Quick Actions - Execute, view details, or manage API keys directly

Access: Click "Agents" in the main navigation menu

Agent Detail Page

Each agent has a dedicated detail page with four tabs:

Overview Tab

Complete agent configuration
Prompt version information with update capability
Required and optional variables
Model settings (temperature, tokens, etc.)
Quick execution metrics

Executions Tab

Paginated History - View all past executions
Advanced Filtering - Filter by status, source, or date range
Execution Details - Click any execution to see full details including:
- Input variables used
- Complete prompts sent to AI
- Full output response
- Performance metrics (latency, tokens, cost)
- Error messages (if failed)
CSV Export - Download execution data for analysis

Analytics Tab

Usage trends over time
Success/failure rates
Cost breakdown
Performance metrics
Model usage distribution

Settings Tab

Update agent configuration
Manage API keys
Change status
Danger zone (pause, archive, delete)

Version Management

NEW: Update an agent's prompt version without recreating it!

Click the Version Selector in the Overview tab
Browse available prompt versions
Compare current vs new version
Update with one click
Rollback anytime if needed

Benefits:

✅ Keep same agent ID and API keys
✅ No integration changes needed
✅ Test new prompts in production
✅ Easy rollback if issues occur

See Version Management Guide for details.

Execution Monitoring

Track every agent execution with comprehensive details:

Real-time Updates - See executions as they happen
Filtering - Find specific executions by status or source
Detailed View - Inspect inputs, outputs, and prompts
Export Data - Download CSV for external analysis
Cost Tracking - Monitor spending per execution

See Execution History Guide for details.

Agent Types

1. Content Generation

Generate text content on demand.

Examples:

Product descriptions
Blog post outlines
Email templates
Social media posts

2. Data Processing

Transform or analyze structured data.

Examples:

Sentiment analysis
Category classification
Data extraction from text
JSON reformatting

3. Conversational

Interactive AI responses.

Examples:

Customer support chatbots
FAQ answerers
Virtual assistants
Guided workflows

4. Code Generation

Generate or transform code.

Examples:

Code snippets
API client generation
Documentation from code
Test case generation

How Agents Work

1. Request Flow

User Application
    ↓
1. HTTP POST with variables
    ↓
2. API key authentication
    ↓
3. Rate limit check
    ↓
4. Load agent configuration
    ↓
5. Load pinned prompt version
    ↓
6. Substitute variables
    ↓
7. Execute AI model
    ↓
8. Return response
    ↓
9. Log execution for analytics

2. Variable Substitution

Your prompt template:

Generate a product description for {{product_name}}
targeting {{target_audience}}. The tone should be {{tone}}.

API request:

{
  "variables": {
    "product_name": "Smart Watch Pro",
    "target_audience": "fitness enthusiasts",
    "tone": "energetic"
  }
}

Final prompt sent to AI:

Generate a product description for Smart Watch Pro
targeting fitness enthusiasts. The tone should be energetic.

3. Response Handling

Agents return a job ID immediately, then process asynchronously:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "agentId": "agent_123"
}

Poll for results:

GET /api/v1/agents/{agentId}/executions/{executionId}

Agent Pricing

Agents use AI models, which have associated costs:

Gemini 1.5 Flash: ~$0.00001 per request
Gemini 1.5 Pro: ~$0.0001 per request
GPT-4: ~$0.001 per request

Cost Optimization

Use faster models (Flash) for simple tasks
Set maxTokens to limit response length
Implement client-side caching for repeated requests

Security Best Practices

Rotate API Keys - Change keys regularly
Use Environment Variables - Never hardcode keys
Set Rate Limits - Prevent abuse
Monitor Usage - Detect anomalies
Restrict Origins - Use CORS for web apps

Next Steps

Create Your First Agent - Step-by-step guide
Manage API Keys - Secure your agents
Integration Guide - Connect your app
Best Practices - Production tips

Ready to build? Create your first agent →

What are Agents?​

Why Use Agents?​

For Developers​

For Product Teams​

For Business​

Agent Architecture​

Agent Components​

1. Prompt Version (Pinned)​

2. Configuration​

3. Variables​

4. API Access Control​

Agent Lifecycle​

Status Stages​

Agent Management Interface​

Agents Page (/agents)​

Agent Detail Page​

Overview Tab​

Executions Tab​

Analytics Tab​

Settings Tab​

Version Management​

Execution Monitoring​

Agent Types​

1. Content Generation​

2. Data Processing​

3. Conversational​

4. Code Generation​

How Agents Work​

1. Request Flow​

2. Variable Substitution​

3. Response Handling​

Agent Pricing​

Security Best Practices​

Next Steps​

What are Agents?

Why Use Agents?

For Developers

For Product Teams

For Business

Agent Architecture

Agent Components

1. Prompt Version (Pinned)

2. Configuration

3. Variables

4. API Access Control

Agent Lifecycle

Status Stages

Agent Management Interface

Agents Page (`/agents`)

Agent Detail Page

Overview Tab

Executions Tab

Analytics Tab

Settings Tab

Version Management

Execution Monitoring

Agent Types

1. Content Generation

2. Data Processing

3. Conversational

4. Code Generation

How Agents Work

1. Request Flow

2. Variable Substitution

3. Response Handling

Agent Pricing

Security Best Practices

Next Steps