Praison AI

Prompt Caching

Reduce costs for repeated prompts with prompt caching

The --prompt-caching flag enables prompt caching to reduce costs when using repeated or long system prompts.

Quick Start

bash
praisonai "Analyze this document..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514

!Prompt Caching Reduces Repeated Tokens

Usage

Basic Prompt Caching

bash
praisonai "Analyze this document..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514

Expected Output:

💾 Prompt Caching enabled

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│  👤 Agent: DirectAgent                                                       │
│  Role: Assistant                                                             │
│  Model: anthropic/claude-sonnet-4-20250514                                          │
│  Prompt Caching: Enabled                                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ Cache Status ───────────────────────────────────────────────────────────────╮
│  📊 Cache hit: System prompt (1,024 tokens saved)                           │
╰──────────────────────────────────────────────────────────────────────────────╯

Combine with Metrics

bash
# See cost savings with metrics
praisonai "Process data..." --prompt-caching --metrics --llm anthropic/claude-sonnet-4-20250514

Supported Providers

ProviderSupportNotes
OpenAIAutoAutomatic caching for repeated prompts
AnthropicManualExplicit caching with --prompt-caching
BedrockManualExplicit caching support
DeepseekManualExplicit caching support

How It Works

  1. Enable: The --prompt-caching flag activates caching
  2. Hash: System prompt is hashed for cache lookup
  3. Check: Provider checks if prompt is cached
  4. Reuse: Cached prompts skip re-processing
  5. Save: Reduced token costs for cached portions
Diagram

Yes

No

Request

Cached?

Use Cache

Process & Cache

Reduced Cost

Full Cost

Response

Cost Savings

Prompt caching can significantly reduce costs for:

ScenarioSavings
Long system promptsUp to 90%
Repeated instructionsUp to 80%
Document analysisUp to 70%
Multi-turn conversationsUp to 50%

Examples

Long System Prompt

bash
# Agent with extensive instructions benefits from caching
praisonai "Answer questions about the codebase" \
  --prompt-caching --llm anthropic/claude-sonnet-4-20250514

Document Analysis

bash
# Repeated analysis of same document
praisonai "Find security issues in this code..." \
  --prompt-caching --llm anthropic/claude-sonnet-4-20250514

Multi-Query Session

bash
# Multiple queries with same context
praisonai "Query 1..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514
praisonai "Query 2..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514
praisonai "Query 3..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514

Programmatic Usage

python
from praisonaiagents import Agent

agent = Agent(
    instructions="You are an AI assistant..." * 50,  # Long system prompt
    llm="anthropic/claude-sonnet-4-20250514",
    caching=True
)

# First call caches the prompt
result1 = agent.start("Question 1")

# Subsequent calls use cached prompt
result2 = agent.start("Question 2")  # Reduced cost
result3 = agent.start("Question 3")  # Reduced cost

Best Practices

DoDon’t
Use for long system promptsUse for short prompts
Use for repeated queriesUse for one-off queries
Combine with --metrics to track savingsIgnore cost monitoring
Use stable instructionsChange prompts frequently

Cache Behavior

ProviderCache DurationCache Scope
OpenAIAutomaticPer-request
Anthropic5 minutesPer-session
BedrockConfigurablePer-session
Deepseek5 minutesPer-session

Beyond the CLI Flag

The --prompt-caching flag controls whether caching is requested on the wire, but Praison now automatically arranges memory and tools cache-friendly for supported models — even without the CLI flag.

In code, your agent’s system prompt, memory context, and tools are automatically organized to maximize cache hits:

  • Deterministic tool order: Tools sorted by function name
  • Stable memory prefix: Memory sections emitted in fixed order
  • Reserved boundary constant: A CACHE_BOUNDARY marker is defined for future structured-cache metadata; today the caching benefit comes entirely from stable ordering above

See Prompt Cache Optimization for the complete pipeline integration.

Related