Author, register, version, test, and wire prompts into agents. Full lifecycle guide.

Prompts — Lifecycle & Registry

AgentBreeder treats prompts as first-class, versioned artifacts — not strings buried in code. Every prompt lives in the shared org registry, supports {{variable}} substitution, and can be tested before being wired into an agent.

Concepts

Concept	Meaning
Registry prompt	Versioned prompt stored by `name` + `version` — retrieved by ref at deploy time
Inline prompt	Literal string in `agent.yaml` — convenient for prototypes
Variable substitution	`{{key}}` placeholders replaced with values at agent runtime
Snapshot	Immutable content copy created on every `PUT .../content` call
Diff	Unified diff between any two snapshots — visible in the dashboard and API

Step 1 — Author

Write your prompt text. Use {{variable}} placeholders for anything that varies per agent or per request:

You are a {{role}} agent working for {{company}}.
Your job is to {{task}}.
Always respond in {{language}}.
Keep answers under {{max_words}} words.

Rules for placeholders:

Only word characters: {{snake_case}}, not {{my-var}} or {{my var}}
Unmatched placeholders are left as-is at runtime
Variables are substituted before the prompt is sent to the model

Step 2 — Register

Go to Registry → Prompts → New Prompt. Fill in name, version, and content. Click Save.

The dashboard generates a prompts/{name} reference you can copy directly into agent.yaml.

curl -X POST http://localhost:8000/api/v1/registry/prompts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-system",
    "version": "1.0.0",
    "content": "You are a {{role}} support agent. Handle {{topic}} tickets.",
    "description": "Tier-1 support system prompt",
    "team": "customer-success"
  }'

Response:

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "support-system",
    "version": "1.0.0",
    "content": "You are a {{role}} support agent...",
    "description": "Tier-1 support system prompt",
    "team": "customer-success",
    "created_at": "2026-04-14T00:00:00Z"
  }
}

# List all prompts
agentbreeder list prompts

# List prompts for a specific team
agentbreeder list prompts --team customer-success

# Search across all registry entities (including prompts)
agentbreeder search "support system"

Step 3 — Use in agent.yaml

Reference by name. AgentBreeder resolves the latest version at deploy time.

name: support-agent
version: 1.0.0
team: customer-success
framework: langgraph

prompts:
  system: prompts/support-system        # ← registry reference

# Alternatively, inline for quick prototypes:
# prompts:
#   system: "You are a helpful support agent."

Versioned reference — pin to an exact version:

prompts:
  system: prompts/support-system@1.0.0  # pins to this exact version

Variables are passed at runtime via your agent's context or via explicit variables config on the agent.

Step 4 — Test Before Deploying

Use the test endpoint to render variable substitution and preview the simulated model response before wiring the prompt to an agent.

curl -X POST http://localhost:8000/api/v1/prompts/test \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "You are a {{role}} agent. Handle {{topic}} tickets.",
    "model_name": "claude-sonnet-4",
    "variables": {
      "role": "billing specialist",
      "topic": "subscription cancellation"
    },
    "temperature": 0.7,
    "max_tokens": 512
  }'

Response:

{
  "data": {
    "rendered_prompt": "You are a billing specialist agent. Handle subscription cancellation tickets.",
    "response_text": "I understand you'd like to cancel your subscription...",
    "model_name": "claude-sonnet-4",
    "input_tokens": 14,
    "output_tokens": 43,
    "total_tokens": 57,
    "latency_ms": 312,
    "temperature": 0.7
  }
}

Test panel in the dashboard

The dashboard has a built-in Prompt Test Panel — open any prompt in Registry → Prompts, then click the Test tab. Fill in variable values and click Run — you see the rendered prompt, token counts, and a simulated response in real time.

Step 5 — Update & Version

Every content update auto-creates an immutable snapshot with author and change summary.

curl -X PUT http://localhost:8000/api/v1/registry/prompts/{id}/content \
  -H "Content-Type: application/json" \
  -d '{
    "content": "You are a senior {{role}} agent with 5 years of experience...",
    "change_summary": "Added seniority framing to improve response quality",
    "author": "alice@company.com"
  }'

This creates a PromptVersion snapshot automatically.

# Update description only — no snapshot created
curl -X PUT http://localhost:8000/api/v1/registry/prompts/{id} \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description for discovery"}'

# Creates a new Prompt record with patch version incremented (1.0.0 → 1.0.1)
curl -X POST http://localhost:8000/api/v1/registry/prompts/{id}/duplicate

Step 6 — View History & Diff

# List all version snapshots
GET /api/v1/registry/prompts/{id}/versions/history

# Diff two snapshots
GET /api/v1/registry/prompts/{id}/versions/history/{v1_id}/diff/{v2_id}

Diff response includes unified diff lines you can display in any UI or terminal:

{
  "data": {
    "version_a": { "version": "1", "author": "alice", "created_at": "..." },
    "version_b": { "version": "2", "author": "bob", "created_at": "..." },
    "diff": [
      "--- version_a",
      "+++ version_b",
      "@@ -1,3 +1,3 @@",
      "-You are a support agent.",
      "+You are a senior support agent with 5 years of experience."
    ]
  }
}

API Reference

Method	Path	Description
`POST`	`/api/v1/registry/prompts`	Register a new prompt
`GET`	`/api/v1/registry/prompts`	List prompts (paginated, filter by `team`)
`GET`	`/api/v1/registry/prompts/{id}`	Get prompt by ID
`PUT`	`/api/v1/registry/prompts/{id}`	Partial update (description only — no snapshot)
`PUT`	`/api/v1/registry/prompts/{id}/content`	Update content + auto-create snapshot
`DELETE`	`/api/v1/registry/prompts/{id}`	Delete prompt
`POST`	`/api/v1/registry/prompts/{id}/duplicate`	Create next patch version
`GET`	`/api/v1/registry/prompts/{id}/versions`	List all versions by name
`GET`	`/api/v1/registry/prompts/{id}/versions/history`	List all snapshots
`POST`	`/api/v1/registry/prompts/{id}/versions/history`	Create a manual snapshot
`GET`	`/api/v1/registry/prompts/{id}/versions/history/{v1}/diff/{v2}`	Diff two snapshots
`POST`	`/api/v1/prompts/test`	Test prompt with variable substitution

agent.yaml `prompts` field

prompts:
  system: string    # registry reference OR inline text

Value type	Example	Behavior
Registry ref	`prompts/my-prompt`	Resolved from registry at deploy time — latest version
Versioned ref	`prompts/my-prompt@1.2.0`	Pins to exact version
Inline string	`"You are a helpful agent."`	Used as-is — no registry lookup
Inline block	`\| You are a {{role}}.`	Multi-line literal with variable support

Next Steps

What	Where
Register and test tools	Tools →
Build a knowledge base	Knowledge Bases →
Add MCP servers	MCP Servers →
Full agent.yaml fields	agent.yaml Reference →

Prompts — Lifecycle & Registry

On this page