Prompts — Lifecycle & Registry

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

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 Studio 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.

Studio 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"
  }
}

# Push a prompt file to the registry (auth-gated — requires AGENTBREEDER_API_TOKEN)
agentbreeder registry prompt push prompts/microlearning-system.md \
  --version 1.0.0 \
  --team eng \
  --description "Microlearning ebook system prompt"

# List all prompts (optionally filter by team)
agentbreeder registry prompt list
agentbreeder registry prompt list --team eng

# Try a registered prompt against a real LLM (Gemini)
agentbreeder registry prompt try microlearning-system \
  --input "What's your job?" \
  --model gemini-2.5-flash

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

Auto patch bump on save

Pushing or saving a prompt with the same name auto-bumps the patch version: 1.0.0 → 1.0.1 → 1.0.2. Drive minor/major bumps explicitly with --version.

Step 3 — Use in agent.yaml

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

name: microlearning-ebook-agent
version: 1.0.0
team: eng
framework: google_adk

prompts:
  system: prompts/microlearning-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/microlearning-system@1.0.2  # pins to this exact version

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

Resolver chain (file → registry → inline)

prompts.system is resolved by engine.prompt_resolver.resolve_prompt() in this order:

Local file — <project>/prompts/<name>.md (primary; lets you edit prompts in-repo)
Registry API — ${AGENTBREEDER_REGISTRY_URL}/api/v1/registry/prompts (DB-backed fallback)
Inline literal — the value of prompts.system is used as the prompt itself (backward compat)

The TypeScript counterpart is resolvePrompt() in engine/runtimes/templates/node/_shared_loader.ts — same precedence, same semantics.

Wiring `agent.py`

The runtime wrapper (google_adk_server.py, etc.) imports your agent module and reads its INSTRUCTION. Use the resolver so the same code works locally, in CI, and in deployed containers:

# agent.py
from pathlib import Path

try:
    from engine.prompt_resolver import resolve_prompt
    INSTRUCTION = resolve_prompt(
        "prompts/microlearning-system",
        project_root=Path(__file__).parent,
    )
except ImportError:
    # Fallback when the engine isn't on the path (e.g., editor IntelliSense)
    INSTRUCTION = (Path(__file__).parent / "prompts" / "microlearning-system.md").read_text()

SDK Usage

from agenthub import Agent

agent = (
    Agent("support-agent")
        .with_framework("claude_sdk")
        .with_prompts(system="prompts/support-system-v3")   # registry ref
        # or inline:
        # .with_prompts(system="You are a {{role}} support agent.")
        .with_deploy(cloud="aws", runtime="app-runner")
)

import { Agent } from "@agentbreeder/sdk";

const agent = new Agent("support-agent")
  .withFramework("claude_sdk")
  .withPrompts({ system: "prompts/support-system-v3" })
  .withDeploy({ cloud: "aws", runtime: "app-runner" });

Prompt Caching (Claude SDK)

When using the Claude SDK framework, set prompt_caching: true to enable Anthropic's prompt caching for the system prompt. Caching applies when the system prompt is at least 8 192 tokens (Sonnet) — repeated requests with the same cached prefix are significantly cheaper and faster.

framework: claude_sdk

prompts:
  system: prompts/support-system-v3   # large, stable system prompt

claude_sdk:
  prompt_caching: true

Step 4 — Test Before Deploying

The Test tab now executes a real LLM call (Google AI Studio / gemini-*) — not a simulation. The endpoint pairs your registered prompt as the system message with a user message you supply, and returns the model's actual output.

curl -X POST http://localhost:8000/api/v1/registry/prompts/{prompt_id}/render \
  -H "Authorization: Bearer $AGENTBREEDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Make me a 30-minute ebook on transformer attention.",
    "model": "gemini-2.5-flash",
    "temperature": 0.7
  }'

Response:

{
  "data": {
    "output": "# Transformer Attention in 30 Minutes\n\n## Module 1 — Why attention?...",
    "model": "gemini-2.5-flash",
    "duration_ms": 1842,
    "error": null
  }
}

Test panel in Studio

Open any prompt in Registry → Prompts and click the Test tab. Type a user message, pick a model, hit Run — you see the actual model response, the model name, and the round-trip duration. Auth is required (any authenticated user; no role gate).

You can also drive the same flow from the CLI:

agentbreeder registry prompt try microlearning-system \
  --input "Make me a 30-minute ebook on transformer attention." \
  --model gemini-2.5-flash

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/registry/prompts/{id}/render`	Render a registered prompt against a real LLM (Gemini)
`POST`	`/api/v1/prompts/test`	Test prompt with variable substitution (legacy)

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