Skip to main content

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​

StatusDescriptionAPI Access
DraftInitial creation, not ready❌ Disabled
TestingUnder validation✅ Enabled (limited)
DeployedProduction-ready✅ Fully enabled
PausedTemporarily 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 an execution ID immediately (202 Accepted), then process asynchronously:

{
"success": true,
"executionId": "550e8400-e29b-41d4-a716-446655440000",
"agentId": "agent_123",
"status": "processing",
"statusUrl": "/api/v1/agents/agent_123/executions/550e8400-e29b-41d4-a716-446655440000"
}

Poll for results:

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

Agent cost​

Every agent execution consumes an AI Action against your plan's monthly quota (see Pricing → Quotas and limits). The actual model-level cost depends on which model the agent is pinned to and the size of the request — fast models cost a small fraction of the most capable ones.

Cost optimization
  • Pick a fast model for simple, latency-sensitive tasks; reserve the most capable models for complex reasoning.
  • Set maxTokens to cap response length.
  • Cache identical requests on your side to avoid duplicate calls.

Security Best Practices​

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

Next Steps​


Ready to build? Create your first agent →