---
title: Prompts
description: Versioned prompts. SWR cache + fallback.
---

# Prompts

Versioned prompts served by the control plane, cached SWR-style (stale-while-revalidate) with an inline fallback. This is the Langfuse **prompt cache**: `init()` first, then `get_prompt()` — no extra registry dependency.

## Fetch a prompt

```python
import agenko

agenko.init()

p = agenko.get_prompt("support-reply", label="production", fallback="Hi {{name}}")
text = p.compile(name="Sam", ticket="refund")
```

```typescript
import agenko from "@agenko/sdk";

agenko.init();

const p = await agenko.getPrompt("support-reply", { label: "production", fallback: "Hi {{name}}" });
const text = p.compile({ name: "Sam", ticket: "refund" });
```

`get_prompt()` returns a `Prompt` with `slug`, `version`, `content`, `labels`, `variables`, and a `compile(**variables)` method. `{{mustache}}`-style variables are filled by `compile()`.

## Arguments

| Argument | Default | Meaning |
|---|---|---|
| `slug` | — | Prompt identifier |
| `label` | `"production"` | Deploy-by-label (Langfuse pattern) |
| `version` | latest by label | Pin a specific version |
| `project_id` / `projectId` | `AGENKO_PROJECT_ID` | Project scope; required if the env var is unset |
| `cache_ttl_seconds` / `cacheTtlSeconds` | `60` | Stale-while-revalidate TTL; `0` disables cache, `null` uses default |
| `fallback` | none | Local content used when the server is unreachable |

## Cache

`cache_ttl_seconds=0` disables the cache in dev (Langfuse convention). `clear_prompt_cache()` invalidates the in-process cache.

## Fallback

Without an API key or when the control plane is down, pass `fallback=` to keep running locally:

```python
p = agenko.get_prompt("greeting", fallback="Hello {{name}}")
```

```typescript
const p = await agenko.getPrompt("greeting", { fallback: "Hello {{name}}" });
```

## How it resolves

1. Reads `AGENKO_HOST` (default `http://localhost:8000`).
2. GET `/api/v1/prompts/by-slug/{project_id}/{slug}?label=production` with `X-API-Key`.
3. SWR-caches the result for `cache_ttl_seconds`.
4. Stamps `prompt.slug` / `prompt.version` onto the active span.

## Next

- [Environment](/environment) — `AGENKO_PROJECT_ID`, `AGENKO_HOST`
- [Python SDK](/python) · [TypeScript SDK](/typescript)
- [OpenTelemetry](/opentelemetry) — what gets stamped on spans
- [What we reuse](/reuse) — Langfuse extraction map

## Agent instructions

This page: https://docs.agenko.app/prompts.md

Fetch `/llms.txt` for the full index. Search: `GET /api/search-docs?query=...`
