Skip to main content
Prompt management lets you version, store, and assign prompt templates to agents. Instead of hardcoding prompts in your agent code, define them in the Manager or YAML config and assign specific versions to agents. Prompts support Jinja2 variables ({{ variable }}) for dynamic content at runtime.

​
Key concepts

ConceptDescription
Prompt IDA logical name for a prompt family (e.g., system-prompt, rag-query)
VersionsEach prompt ID can have multiple versions. Content is immutable after creation. Updating a prompt creates a new version
Latest tagThe latest tag always points to the highest version and is managed automatically
Agent assignmentSpecific prompt versions are assigned to agents. Agents are pinned to a version until you reassign

​
Define prompts

Prompts are assigned to agents from the agent detail Prompts tab.Agent detail prompts tabThe Prompts page in the sidebar shows all prompts in your workspace. Create prompts with a name, content (using the built-in editor), and tags.

​
Manager API

The Manager provides full CRUD and assignment endpoints at /api/v1/prompts/.

​
Create a prompt

curl -X POST http://localhost:8000/api/v1/prompts/ \
  -H "Content-Type: application/json" \
  -b "sid=<session_cookie>" \
  -d '{
    "prompt_id": "system-prompt",
    "content": "You are a helpful assistant for {{ domain }}.",
    "tags": ["production"]
  }'
The first version is automatically v1. Subsequent POST requests with the same prompt_id auto-increment the version and move the latest tag.

​
List and filter prompts

# List all prompts
curl http://localhost:8000/api/v1/prompts/ -b "sid=<session_cookie>"

# Filter by prompt_id
curl "http://localhost:8000/api/v1/prompts/?prompt_id=system-prompt" \
  -b "sid=<session_cookie>"

# Filter by tag
curl "http://localhost:8000/api/v1/prompts/?tag=latest" \
  -b "sid=<session_cookie>"

​
Update tags

Content is immutable. Only tags can be updated: 
curl -X PATCH http://localhost:8000/api/v1/prompts/{id} \
  -H "Content-Type: application/json" \
  -b "sid=<session_cookie>" \
  -d '{"tags": ["production", "reviewed"]}'
The latest tag is managed server-side. Even if you remove it in a PATCH request, it is re-added if this is the highest version. You cannot assign latest to an older version manually.

​
Assign prompts to agents

# Assign a prompt version to an agent
curl -X POST http://localhost:8000/api/v1/prompts/{prompt_uuid}/assign/{agent_uuid} \
  -b "sid=<session_cookie>"

# Unassign
curl -X DELETE http://localhost:8000/api/v1/prompts/{prompt_uuid}/assign/{agent_uuid} \
  -b "sid=<session_cookie>"

# List prompts assigned to an agent
curl http://localhost:8000/api/v1/prompts/agent/{agent_uuid} \
  -b "sid=<session_cookie>"
Assigned prompts are automatically injected into the agent’s engine_config.prompts list when the engine fetches its config.

​
Delete a version

curl -X DELETE http://localhost:8000/api/v1/prompts/{id} \
  -b "sid=<session_cookie>"
If the deleted version had the latest tag, it is automatically promoted to the next-highest remaining version.

​
Using prompts in agent code

​
Load prompts

The engine provides helpers to load prompts from YAML or the Manager API: 
from idun_agent_engine.prompts import get_prompt

# Loads from YAML config, IDUN_CONFIG_PATH env, or Manager API
prompt = get_prompt("system-prompt")
Resolution priority:
  1. Explicit config_path argument
  2. IDUN_CONFIG_PATH environment variable
  3. Manager API (requires IDUN_AGENT_API_KEY + IDUN_MANAGER_HOST)

​
Render with Jinja2

Use format() to render template variables: 
prompt = get_prompt("system-prompt")
rendered = prompt.format(domain="healthcare")
# "You are a helpful assistant specializing in healthcare."
format() uses Jinja2 strict mode. Missing variables raise a ValueError with a message including the prompt ID and version.

​
LangChain integration

Convert a prompt to a LangChain PromptTemplate: 
prompt = get_prompt("rag-query")
lc_prompt = prompt.to_langchain()

result = lc_prompt.format(context="AI is...", query="What is AI?")
to_langchain() requires langchain-core. Install it with pip install langchain-core.

​
Best practices

  • Use descriptive prompt IDs like system-prompt, rag-query, summarization (not prompt-1)
  • Keep prompts atomic: one prompt per concern (system instructions, query template, output format)
  • Create new versions for meaningful changes, not typo fixes
  • Use tags like production, staging, experimental to track lifecycle
  • Pin specific versions to production agents rather than relying on latest

​
Troubleshooting

  1. Verify the prompt is assigned to the agent (check the Prompts tab in agent detail)
  2. Confirm both the prompt and agent are in the same workspace
  3. Check that the agent’s API key is valid (GET /agents/config requires Bearer auth)
  1. Use double braces: {{ variable }}, not { variable }
  2. Pass all required variables to format()
  3. The error message includes the prompt ID and version to help identify the issue
Version auto-increment is scoped to (workspace_id, prompt_id). If you create prompts in a different workspace, versioning starts from 1.
Last modified on March 22, 2026