Prompt Templates

Prompt templates let you version-control your prompts outside of your agent code. Store prompts in 2Signal, push new versions as you iterate, and resolve the latest (or a pinned) version at runtime. Every span can reference the prompt template version it used, giving you full traceability from prompt change to agent behavior.

Why Use Prompt Templates?

• Version history — see every prompt change with commit messages, roll back if a new version causes regressions
• Decouple prompts from code — update prompts without redeploying your agent
• Traceability — every LLM span records which prompt template version was used, so you can correlate prompt changes with score changes
• Variables — define parameterized prompts with variables that get filled at runtime
• Trace replay — replay traces with a different prompt template version to compare results

Core Concepts

Templates

A template is a named prompt definition scoped to a project. Templates have a name, optional description, and one or more versions.

Versions

Each version is an immutable snapshot of the prompt content. Version numbers auto-increment starting from 1. Once created, a version cannot be modified — push a new version instead.

Variables

Variables are placeholders in the prompt content that get filled at runtime. They are automatically extracted from the content when a version is created.

Creating a Template

Use the REST API to create a template or push a new version:

curl -X POST https://api.2signal.dev/api/v1/prompt-templates \
  -H "Authorization: Bearer ts_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support",
    "content": "You are a helpful customer support agent for {{company_name}}. The customer\'s name is {{customer_name}}. Respond politely and accurately.",
    "variables": ["company_name", "customer_name"],
    "commitMessage": "Initial version with company and customer name variables"
  }'

Response:

{
  "data": {
    "templateId": "tmpl-abc-123",
    "templateName": "customer-support",
    "versionId": "ver-def-456",
    "version": 1
  }
}

If the template already exists, posting with the same name creates a new version with an auto-incremented version number.

Resolving a Template

Fetch the latest version of a template by name:

curl "https://api.2signal.dev/api/v1/prompt-templates?name=customer-support" \
  -H "Authorization: Bearer ts_your_api_key"

Or pin to a specific version:

curl "https://api.2signal.dev/api/v1/prompt-templates?name=customer-support&version=2" \
  -H "Authorization: Bearer ts_your_api_key"

Listing Templates

List all templates for a project:

curl "https://api.2signal.dev/api/v1/prompt-templates" \
  -H "Authorization: Bearer ts_your_api_key"

Using Templates in Your Agent

import httpx

# Resolve the latest prompt template
response = httpx.get(
    "https://api.2signal.dev/api/v1/prompt-templates",
    params={"name": "customer-support"},
    headers={"Authorization": "Bearer ts_your_api_key"},
)
template = response.json()["data"]
prompt = template["content"]

# Fill in variables
prompt = prompt.replace("{{company_name}}", "Acme Corp")
prompt = prompt.replace("{{customer_name}}", user.name)

# Use the prompt in your LLM call
# The span will automatically record the prompt template version ID

Dashboard

Prompt templates can also be managed in the dashboard. Navigate to your project and use the tRPC-powered interface to create, view versions, and manage templates.

Prompt Templates + Trace Replay

One of the most powerful uses of prompt templates is combined with trace replay. You can replay a trace with a different prompt template version to see how a prompt change affects agent behavior — without re-running the full agent pipeline.

API Reference

See the Prompt Templates API reference for full endpoint documentation including request/response schemas.