Skip to content

Templates & Variables

Prompt templates let you define reusable, parameterized interactions that customers can fill in and execute via the API.

Overview

Templates combine:

  • A prompt template with {{VARIABLE}} placeholders
  • A variable schema defining expected inputs
  • An agent type to handle the rendered prompt

This enables structured, repeatable interactions without requiring customers to write prompts from scratch.

How Templates Work

Template: "Summarize the following document: {{DOCUMENT_TEXT}}"
                                    │
                                    ▼
Customer provides: { "DOCUMENT_TEXT": "..." }
                                    │
                                    ▼
Rendered prompt sent to agent → Response returned

Managing Templates

Templates are created and managed via the Dashboard:

  1. Go to Agent Types > select a type > Templates
  2. Click Create Template
  3. Define the template prompt with {{VARIABLE}} placeholders
  4. Configure variable schema (name, type, required)
  5. Publish the template

Using Templates via API

List Published Templates

curl https://api.ag2trust.com/api/v1/pool/templates \
  -H "X-API-Key: cust_your_api_key"

Response:

[
  {
    "id": 1,
    "name": "Document Summary",
    "description": "Summarize a document",
    "variables": [
      {"name": "DOCUMENT_TEXT", "type": "string", "required": true}
    ]
  }
]

Get Template Details

curl https://api.ag2trust.com/api/v1/pool/templates/1 \
  -H "X-API-Key: cust_your_api_key"

Store Variables (No Agent Call)

Use /use to store variables and get the rendered content without calling an agent:

curl -X POST https://api.ag2trust.com/api/v1/pool/templates/1/use \
  -H "X-API-Key: cust_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "DOCUMENT_TEXT": "The quarterly report shows..."
    },
    "thread_id": "thread_abc123"
  }'

Start Template (Store Variables + Call Agent)

Use /start to store variables and immediately send the rendered prompt to an agent:

curl -X POST https://api.ag2trust.com/api/v1/pool/templates/1/start \
  -H "X-API-Key: cust_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "DOCUMENT_TEXT": "The quarterly report shows..."
    },
    "agent_type_slug": "summarizer"
  }'

Response matches the standard pool endpoint response.

Variables

Variables are the building blocks of templates and context injection. See the Knowledge Base guide for full details on variable management.

Variable Types

Type Example Description
string "Hello" Text value (default)
int 42 Integer number
float 3.14 Decimal number
boolean true True/false
date 2025-01-15 Date value

Validators

Validator Description
none No validation (default)
email Must be a valid email address
url Must be a valid URL
phone Must be a valid phone number
regex Must match a custom regex pattern

Static vs Dynamic Variables

Property Static (is_dynamic: false) Dynamic (is_dynamic: true)
Value source Stored in DB (KMS-encrypted) Provided at runtime via context_variables
Use case Company info, policies User-specific data
Persistence Persisted Ephemeral (per-request only)

Naming Convention

Variable names must be UPPERCASE_SNAKE_CASE:

CUSTOMER_NAME     ✓
USER_EMAIL        ✓
order_id          ✗ (must be uppercase)

API Reference

Method Endpoint Description
GET /api/v1/pool/templates List published templates
GET /api/v1/pool/templates/{id} Get template with variable schema
POST /api/v1/pool/templates/{id}/use Store variables (no agent call)
POST /api/v1/pool/templates/{id}/start Store variables + call agent

Best Practices

  1. Use descriptive variable names — CUSTOMER_COMPLAINT is better than TEXT
  2. Add validation — Use email, url, or regex validators to catch bad input early
  3. Keep templates focused — One template per use case (e.g., "Summarize Document", "Draft Email Response")
  4. Use static variables for constants — Company name, support hours, and policies should be static variables, not runtime inputs

Next Steps