Prompt Management

Open Astra provides three layers of prompt management: reusable templates with variable substitution, per-agent prompt versioning with rollback, and live prompt overrides with TTL for temporary behavior changes.

Prompt templates

Templates are reusable prompt fragments with placeholders. Templates track usage and can be filtered by category.

bash

# Create a prompt template
curl -X POST http://localhost:3000/prompt-templates \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review",
    "category": "engineering",
    "template": "Review the following {{language}} code for security issues, performance problems, and style violations:\n\n{{code}}",
    "variables": ["language", "code"]
  }'

# Render a template with variables
curl -X POST http://localhost:3000/prompt-templates/pt_abc123/render \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "language": "TypeScript", "code": "const data = eval(userInput)" } }'

Prompt versioning

Every change to an agent's system prompt creates a new version. Versions are auto-numbered and can be restored at any time.

bash

# List prompt versions for an agent
curl http://localhost:3000/agents/code-agent/prompt-versions \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Create a new prompt version
curl -X POST http://localhost:3000/agents/code-agent/prompt-versions \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are a senior code reviewer. Focus on security and performance.",
    "label": "v2-security-focus"
  }'

# Restore a previous version
curl -X POST http://localhost:3000/agents/code-agent/prompt-versions/3/restore \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Hot prompt swap

Override an agent's prompt in real-time with a TTL. Useful for incident mode, A/B testing, or temporary behavior changes. Default TTL is 1 hour (3,600 seconds), max 24 hours.

bash

# Hot-swap an agent's prompt (live override with TTL)
curl -X POST http://localhost:3000/agents/code-agent/prompt-override \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are in incident mode. Prioritize speed over thoroughness.",
    "ttlSeconds": 3600
  }'

# Clear the override (revert to default prompt)
curl -X DELETE http://localhost:3000/agents/code-agent/prompt-override \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Endpoint reference

Method	Endpoint	Description
`GET`	`/prompt-templates`	List templates (filter by `category`)
`GET`	`/prompt-templates/:id`	Get template
`POST`	`/prompt-templates`	Create template
`PUT`	`/prompt-templates/:id`	Update template
`DELETE`	`/prompt-templates/:id`	Delete template
`POST`	`/prompt-templates/:id/render`	Render with variables
`GET`	`/agents/:id/prompt-versions`	List versions
`POST`	`/agents/:id/prompt-versions`	Create version
`GET`	`/agents/:id/prompt-versions/:ver`	Get version
`POST`	`/agents/:id/prompt-versions/:ver/restore`	Restore version
`POST`	`/agents/:id/prompt-override`	Set live override (TTL 1h default, 24h max)
`DELETE`	`/agents/:id/prompt-override`	Clear override