Dynamic Prompts - Vizra ADK

Why Dynamic Prompts Change Everything

Remember changing code just to tweak your AI’s personality? Those days are OVER! With dynamic prompts, you can experiment, test, and perfect your agent’s responses without deploying a single line of code.

A/B Testing

Test different prompts side-by-side

Instant Rollback

Revert to any previous version

Track Performance

See which prompts work best

Versions vs Variants: What’s the Difference?

There’s an important distinction between versions and variants. Vizra ADK supports BOTH seamlessly!

Versions

Track improvements over time. Each version builds on the last, getting better and smarter.

v1: "You are a helpful assistant"
v2: "You are a helpful assistant. Be concise."
v3: "You are a helpful assistant. Be concise and cite sources."

Use for: A/B testing improvements, safe rollbacks, tracking prompt evolution

Variants

Different styles for different contexts. Same capability, different personality.

formal: "I shall assist you with utmost professionalism"
casual: "Hey! Happy to help out"
technical: "Initiating support protocol. State your query."

Use for: User preferences, context-specific responses, brand voices

The Magic: Use Both Together!

File Structure:

resources/prompts/support_agent/
├── v1/
│   ├── default.md
│   ├── formal.md
│   └── casual.md
└── v2/
    ├── default.md
    ├── formal.md
    └── casual.md

Usage Examples:

// Use latest version, default variant
SupportAgent::run('Help')->go();

// Use specific variant
SupportAgent::run('Help')
    ->withPromptVersion('formal')
    ->go();

// Use specific version & variant
SupportAgent::run('Help')
    ->withPromptVersion('v1/casual')
    ->go();

Getting Started with Dynamic Prompts

When you create an agent using the vizra:make:agent command, it automatically creates a prompt blade file for you in /resources/prompts/YourAgent. This gives you instant access to dynamic prompts without any additional setup!

Quick Example

// Use a variant
MyAgent::run('Hello')
    ->withPromptVersion('brief')
    ->go();

// Use a specific version/variant
MyAgent::run('Hello')
    ->withPromptVersion('v2/formal')
    ->go();

Real-World Example: Customer Support Agent

Let’s see how versions and variants work together in practice. Imagine evolving a customer support agent over time while maintaining different tones for different customers.

Usage in Production

// A/B test new version with specific users
$version = $user->isInTestGroup() ? 'v3' : 'v2';
$variant = $user->preferredTone ?? 'default';

$response = CustomerSupportAgent::run($query)
    ->withPromptVersion("$version/$variant")
    ->forUser($user)
    ->go();

// Or use smart routing based on context
$promptVersion = match(true) {
    $isAngryCustomer => 'v3/empathetic',
    $isTechnicalIssue => 'v3/technical',
    $isVipCustomer => 'v3/formal',
    default => 'v3/default'
};

$response = CustomerSupportAgent::run($query)
    ->withPromptVersion($promptVersion)
    ->go();

Blade Templates for Dynamic Prompts

Use Laravel’s Blade templating engine to create dynamic prompts that adapt based on user data, context, and session state.

How It Works

Save your prompts with a .blade.php extension instead of .md:

resources/prompts/customer_support/default.blade.php

You are {{ $agent['name'] }}, a helpful assistant.

@if(isset($user_name))
Hello {{ $user_name }}! How can I help you today?
@else
Hello! How can I assist you?
@endif

@if($tools->isNotEmpty())
Available capabilities:
@foreach($tools as $tool)
- {{ $tool['description'] }}
@endforeach
@endif

Available Variables

Core Variables

$agent - Agent info (name, model, etc.)
$context - Full AgentContext object
$user_input - Current user input
$session_id - Session identifier

User & Memory

$user, $user_name - User data
$memory_context - Previous interactions
$tools - Available tools collection
$sub_agents - Sub-agents collection

Custom Variables

Add your own variables to inject into the blade prompt with getPromptData():

class SalesAgent extends BaseLlmAgent
{
    protected function getPromptData(?AgentContext $context): array
    {
        return [
            'company_name' => config('app.company_name'),
            'promotions' => $this->getActivePromotions(),
            'business_hours' => '9 AM - 5 PM EST',
        ];
    }
}

When to Use What

Use Markdown When:

Prompts are mostly static
Simple version control needed
No dynamic content required

Use Blade When:

Need user personalization
Conditional logic required
Dynamic content injection

Blade templates work seamlessly with the existing versioning system - just use withPromptVersion('name') as usual!

Organizing Your Prompts

Keep your prompts organized with these flexible structures:

Simple Structure (Variants Only)

resources/prompts/
├── weather_reporter/
│   ├── default.md      # Standard tone
│   ├── detailed.md     # Comprehensive
│   ├── concise.md      # Brief responses
│   └── professional.md # Business tone
└── customer_support/
    ├── default.md
    ├── friendly.md
    └── technical.md

Versioned Structure (Versions + Variants)

resources/prompts/
├── weather_reporter/
│   ├── v1/
│   │   ├── default.md
│   │   └── concise.md
│   └── v2/
│       ├── default.md
│       ├── concise.md
│       └── detailed.md    # New in v2
└── customer_support/
    ├── v1/
    │   └── default.md
    └── v2/
        ├── default.md
        ├── friendly.md    # New variant
        └── technical.md   # New variant

Start simple with just variants. Add versioning when you need to track improvements over time!

CLI Command Mastery

The vizra:prompt command is your Swiss Army knife for prompt management!

Creating Prompts

Terminal

# Interactive mode - enter multi-line content
php artisan vizra:prompt create weather_reporter friendly

# Quick mode - inline content
php artisan vizra:prompt create weather_reporter v2 --content="You are a helpful weather assistant."

Listing Prompts

Terminal

# List all prompts
php artisan vizra:prompt list

# List for specific agent
php artisan vizra:prompt list weather_reporter

# Example output:
# +------------------+----------+--------+--------+---------------------+
# | Agent            | Version  | Source | Active | Created             |
# +------------------+----------+--------+--------+---------------------+
# | weather_reporter | default  | File   | ✓      | 2024-01-15 10:30:00 |
# | weather_reporter | detailed | File   |        | 2024-01-15 11:00:00 |
# | weather_reporter | concise  | File   |        | 2024-01-15 11:30:00 |
# +------------------+----------+--------+--------+---------------------+

Import & Export

Terminal

# Export a prompt to file
php artisan vizra:prompt export weather_reporter detailed --file=weather_detailed.md

# Import from file
php artisan vizra:prompt import weather_reporter v3 --file=weather_detailed.md

# View prompt content directly
php artisan vizra:prompt export weather_reporter detailed

Runtime Magic

Switch prompt versions on the fly - no redeploys needed!

Setting Default Version in Agent Class

You can define a default prompt version directly in your agent class:

Agent with Default Prompt Version

class WeatherReporterAgent extends BaseLlmAgent
{
    protected string $name = 'weather_reporter';

    // Set default prompt version for this agent
    protected ?string $promptVersion = 'professional';

    // This will be overridden by the professional.md file
    protected string $instructions = 'You are a weather reporter.';
}

// Now all calls use 'professional' by default
$response = WeatherReporterAgent::run('What\'s the weather?')->go();

// Override the default when needed
$response = WeatherReporterAgent::run('Current temperature?')
    ->withPromptVersion('concise')
    ->go();

Using Blade Templates at Runtime

Blade templates work seamlessly with the existing prompt versioning system:

Using Blade Templates with Runtime API

// Blade templates work just like markdown versions
$response = WeatherReporter::run('What\'s the weather?')
    ->withPromptVersion('detailed')  // Can be detailed.blade.php
    ->go();

// Mix and match - the system automatically detects the file type
// Version 'friendly' could be friendly.md or friendly.blade.php
$response = CustomerSupport::run($query)
    ->withPromptVersion('friendly')
    ->go();

// Pass additional context for Blade templates
$response = SalesAgent::run('Show me pricing')
    ->withContext([
        'premium_user' => true,
        'account_age_days' => 365,
        'preferred_language' => 'es',
    ])
    ->withPromptVersion('personalized')  // Uses personalized.blade.php
    ->go();

// Works with async operations too
$job = ReportGenerator::run($data)
    ->withPromptVersion('executive')  // executive.blade.php with dynamic formatting
    ->async()
    ->go();

Runtime Version Selection

Using Prompt Versions in Code

// Using specific version
$response = WeatherReporterAgent::run('What\'s the weather?')
    ->withPromptVersion('detailed')
    ->go();

// Using Agent Facade
$response = Agent::build('weather_reporter')
    ->withPromptVersion('concise')
    ->run('Current temperature?')
    ->go();

// Version from variable (great for A/B testing!)
$version = $user->prefers_detailed ? 'detailed' : 'concise';
$response = WeatherReporter::run($query)
    ->withPromptVersion($version)
    ->go();

Advanced Patterns

Advanced Prompt Version Usage

// A/B Testing Pattern
$versions = ['default', 'friendly', 'professional'];
$results = [];

foreach ($versions as $version) {
    $startTime = microtime(true);

    $response = CustomerSupportAgent::run($testQuery)
        ->withPromptVersion($version)
        ->go();

    $results[$version] = [
        'response' => $response,
        'time' => microtime(true) - $startTime,
        'length' => strlen($response)
    ];
}

// Find the best performer
$bestVersion = collect($results)->sortBy('time')->keys()->first();

Evaluation Integration

Test different prompt versions systematically with evaluations!

CSV-Driven Testing

evaluation_data.csv

location,expected_format,prompt_version
"New York",detailed,detailed
"London",concise,concise
"Tokyo",professional,professional
"Paris",friendly,friendly

Evaluation Class with Prompt Versions

class PromptComparisonEval extends BaseEvaluation
{
    public string $agentName = 'weather_reporter';

    // CSV column that specifies prompt version
    public ?string $promptVersionColumn = 'prompt_version';

    // Or set a default for all tests
    public array $agentConfig = [
        'prompt_version' => 'detailed',
        'temperature' => 0.7,
    ];

    public function evaluateRow(array $csvRow, string $response): array
    {
        // Your evaluation logic here
        // The correct prompt version is automatically used!
    }
}

Configuration Options

Customize prompt versioning behavior in config/vizra-adk.php:

Prompt Configuration

'prompts' => [
    // Enable database storage (optional)
    'use_database' => env('VIZRA_ADK_PROMPTS_USE_DATABASE', false),

    // Custom storage path
    'storage_path' => env('VIZRA_ADK_PROMPTS_PATH', resource_path('prompts')),

    // Track usage analytics
    'track_usage' => env('VIZRA_ADK_PROMPTS_TRACK_USAGE', false),
],

Database Storage (Advanced)

For production environments, enable database storage:

Terminal

# Run migrations
php artisan migrate

# Update .env
VIZRA_ADK_PROMPTS_USE_DATABASE=true

# Activate a version
php artisan vizra:prompt activate weather_reporter v2

Best Practices

Naming Conventions

default - Always have one!
friendly - Descriptive names
2024_01_15_improved - Date versions
~~v2~~ - Too vague!

Testing Strategy

Start with file-based prompts
Test with evaluations
A/B test in production
Move winners to database

Troubleshooting

Prompt Not Loading?

Check file exists: resources/prompts/{agent_name}/{version}.md
Verify file permissions are readable
Clear cache: php artisan cache:clear
Check agent name matches directory name

Database Prompts Not Working?

Ensure use_database is true in config
Run migrations: php artisan migrate
Check prompt exists: php artisan vizra:prompt list
Verify database connection is working

You’re Now a Dynamic Prompts Pro!

With dynamic prompts, your AI agents can evolve and improve without touching code. Test freely, roll back instantly, and find the perfect voice for every agent. The future of AI development is here!

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

API Reference

​Why Dynamic Prompts Change Everything

A/B Testing

Instant Rollback

Track Performance

​Versions vs Variants: What’s the Difference?

Versions

Variants

​The Magic: Use Both Together!

​Getting Started with Dynamic Prompts

​Real-World Example: Customer Support Agent

​Blade Templates for Dynamic Prompts

​How It Works

​Available Variables

Core Variables

User & Memory

​Custom Variables

​When to Use What

Use Markdown When:

Use Blade When:

​Organizing Your Prompts

Simple Structure (Variants Only)

Versioned Structure (Versions + Variants)

​CLI Command Mastery

​Creating Prompts

​Listing Prompts

​Import & Export

​Runtime Magic

​Setting Default Version in Agent Class

​Using Blade Templates at Runtime

​Runtime Version Selection

​Advanced Patterns

​Evaluation Integration

​CSV-Driven Testing

​Configuration Options

​Database Storage (Advanced)

​Best Practices

Naming Conventions

Testing Strategy

​Troubleshooting

​Prompt Not Loading?

​Database Prompts Not Working?

​You’re Now a Dynamic Prompts Pro!

Why Dynamic Prompts Change Everything

Versions vs Variants: What’s the Difference?

The Magic: Use Both Together!

Getting Started with Dynamic Prompts

Real-World Example: Customer Support Agent

Blade Templates for Dynamic Prompts

How It Works

Available Variables

Custom Variables

When to Use What

Organizing Your Prompts

CLI Command Mastery

Creating Prompts

Listing Prompts

Import & Export

Runtime Magic

Setting Default Version in Agent Class

Using Blade Templates at Runtime

Runtime Version Selection

Advanced Patterns

Evaluation Integration

CSV-Driven Testing

Configuration Options

Database Storage (Advanced)

Best Practices

Troubleshooting

Prompt Not Loading?

Database Prompts Not Working?

You’re Now a Dynamic Prompts Pro!