Skip to main content

Agent Education

The pavri.education module provides a library of security-focused system prompt templates that help agent developers build safer AI agents. These templates are opt-in and do not modify any existing SDK runtime behavior — they are prompt text you can integrate into your agent's system message.

Built-in Templates​

NamePurpose~Tokens
injection_resistanceResist prompt injection from untrusted sources~160
safe_tool_usageVerify tool parameters; reject suspicious inputs~120
pii_handlingRecognise PII, minimise access, prevent unauthorised forwarding~150
cost_awarenessStay within token and call budgets~140
output_validationPre-return PII scan, scope check, factual claim marking~170

Quick Start​

from pavri.education import get_template, render

# Get the injection resistance template
template = get_template("injection_resistance")

# Render it with your agent's context
rendered = render(template, {
    "agent_name": "SupportBot",
    "trusted_principal": "the operator",
})

# Use the rendered system prompt
agent = your_framework.Agent(
    system_message=rendered.system_prompt,
    # ... other config
)

Template Reference​

injection_resistance​

Hardens your agent against prompt injection attacks embedded in user input, tool outputs, retrieved documents, and environment data.

Required variables: agent_name, trusted_principal

rendered = render(get_template("injection_resistance"), {
    "agent_name": "ResearchBot",
    "trusted_principal": "the product team",
})

Guardrails included:

  • Untrusted data isolation — treats all user input and tool output as data, not instructions
  • Instruction-in-content detection — flags and ignores embedded override directives
  • Role/persona override resistance — identity and constraints are immutable at runtime
  • System prompt confidentiality — does not reveal the system prompt on request

When to use: Any agent that processes untrusted user input, web content, or third-party tool outputs.

safe_tool_usage​

Teaches the agent to verify tool parameters, reject suspicious inputs, and never use tools to access resources outside the stated task scope.

Required variables: agent_name, task

rendered = render(get_template("safe_tool_usage"), {
    "agent_name": "DataAgent",
    "task": "customer analytics",
})

Guardrails included:

  • Parameter validation before every tool call
  • Scope restriction to declared task domain
  • Refusal on unexpected parameter injection
  • Clarification request on ambiguous tool use

When to use: Agents with write access to tools (databases, APIs, file systems, external services).

pii_handling​

Instructs the agent to recognise PII, avoid unnecessary logging or forwarding, and redact sensitive data before storing or transmitting it.

Required variables: agent_name, task

rendered = render(get_template("pii_handling"), {
    "agent_name": "HRBot",
    "task": "employee onboarding",
})

Guardrails included:

  • Minimum necessary data access
  • No unsanctioned PII forwarding
  • Discard irrelevant PII
  • Approved-destination check before transmission

When to use: Agents processing forms, user profiles, healthcare data, or any data that may contain personal information.

cost_awareness​

Guides the agent to minimise unnecessary API calls, token usage, and tool invocations to stay within cost and rate-limit budgets.

Required variables: agent_name, max_tokens, max_tool_calls, max_api_calls

rendered = render(get_template("cost_awareness"), {
    "agent_name": "AnalyticsAgent",
    "max_tokens": "4000",
    "max_tool_calls": "20",
    "max_api_calls": "10",
})

Guardrails included:

  • Token budget enforcement
  • Tool call count limit
  • Deduplication of repeated fetches
  • Budget-exceeded escalation (asks user instead of continuing)

When to use: High-volume agents, agents running in cost-sensitive environments, or agents prone to runaway loops.

output_validation​

Instructs the agent to validate its own output before returning it, checking for PII leakage, hallucinated facts, and policy violations.

Required variables: agent_name, task, trusted_principal

rendered = render(get_template("output_validation"), {
    "agent_name": "ReportBot",
    "task": "financial report generation",
    "trusted_principal": "the finance team",
})

Guardrails included:

  • Pre-return PII scan
  • Response scope enforcement
  • Factual claim marking (uncertain claims tagged "(unverified)")
  • Policy compliance check before returning

When to use: Agents generating reports, summaries, or content that will be shared externally.

Rendering Templates​

The renderer supports variable substitution. Extra variables are silently ignored. Missing required variables raise a ValueError.

from pavri.education import render, get_template

template = get_template("cost_awareness")

# Missing required var — raises ValueError
try:
    rendered = render(template, {"agent_name": "Bot"})
except ValueError as e:
    print(e)
# ValueError: Template 'cost_awareness' requires variables ['max_api_calls', 'max_tool_calls', 'max_tokens'] ...

# Correct
rendered = render(template, {
    "agent_name": "Bot",
    "max_tokens": "2000",
    "max_tool_calls": "10",
    "max_api_calls": "5",
})
print(rendered.system_prompt)

The user_prompt_template returned by render() may still contain a {user_request} placeholder — fill this at runtime with the actual user request before sending to the model.

CLI​

The pavri-education CLI is included with the SDK:

# List all templates
pavri-education list

# Show details for a template (including the full system prompt)
pavri-education show injection_resistance

# Render a template to stdout
pavri-education render injection_resistance \
  --vars agent_name=MyBot trusted_principal=operator

# JSON output for all commands
pavri-education --json list
pavri-education --json show injection_resistance
pavri-education --json render safe_tool_usage \
  --vars agent_name=SafeBot task="file processing"

Combining Templates​

For high-security agents, you can combine multiple templates by concatenating their system prompts:

from pavri.education import render, get_template

vars_common = {"agent_name": "HighSecurityAgent", "task": "data processing"}
injection = render(get_template("injection_resistance"), {
    **vars_common, "trusted_principal": "the security team"
})
pii = render(get_template("pii_handling"), vars_common)

combined_system_prompt = injection.system_prompt + "\n\n---\n\n" + pii.system_prompt

Note: combining multiple templates increases token count. For token-sensitive deployments, choose the template most relevant to your threat model.

Effectiveness​

These templates are designed to reduce the effectiveness of known attack categories:

TemplateDefends Against
injection_resistancePrompt injection, jailbreaks, persona overrides, "ignore previous instructions"
safe_tool_usageTool parameter injection, scope creep, unauthorised resource access
pii_handlingAccidental PII exposure, unsanctioned data exfiltration
cost_awarenessRunaway loops, cost explosion, rate limit exhaustion
output_validationPII leakage in responses, hallucination propagation, policy violations
note

Prompt-level instructions are a defence-in-depth measure, not a complete solution. Use them alongside Pavri runtime governance policies (T0/T1/T2 detection, policy enforcement, response actions) for layered protection.