Background
Extra already integrates Langfuse for tracing via LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY, no YAML (observability/providers/langfuse/provider.py). Langfuse separately offers prompt management: a prompt has a name, each edit creates an immutable version, and a label (default production) is a movable pointer to one version.
Today prompts.system / user / orchestrator in agents.yml are always a local file path. This issue adds a second source: fetch by name from Langfuse instead.
Proposed YAML — needs research before locking in
# unchanged — bare string still means local file
system: "prompts/orders/system.md"
# new — object form opts into Langfuse (same shape for system/user/orchestrator)
system:
langfuse:
name: "returns-system" # required
label: production # default; mutually exclusive with version
# version: 3 # pins to one immutable revision
Two things the assignee needs to research and settle, not assume: whether production or latest (auto-tracks most recent save, no promotion step) is the better default label for this project; and whether langfuse: as a direct key is right, vs. reserving it for later if a second remote source ever shows up (default to the direct key — don't build for a hypothetical second backend now).
Runtime: fetch once at startup, no caching
One fetch per node when the graph is built at server startup, held for the process lifetime — no TTL, no refetching, no live updates in v1. A fetch failure at startup is fatal: the server refuses to start rather than run with a missing prompt (fail closed).
generate: health check, not scaffolding
#18 makes generate create local stub files for missing prompts — that doesn't apply here, since a Langfuse-sourced prompt has no local file by design. generate should skip these nodes for scaffolding, and instead run a lightweight connectivity check (credentials present, package importable, Langfuse reachable) — not a per-prompt existence check.
Non-goals for v1
- Chat-typed Langfuse prompts (role-tagged message arrays) — text-type only; error clearly on chat-type rather than mis-render it.
- Caching with a TTL, so a promoted prompt change is picked up without a restart.
- Reacting to prompt changes in Langfuse (e.g. refresh on label move) instead of requiring a redeploy.
Background
Extra already integrates Langfuse for tracing via
LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY, no YAML (observability/providers/langfuse/provider.py). Langfuse separately offers prompt management: a prompt has a name, each edit creates an immutable version, and a label (defaultproduction) is a movable pointer to one version.Today
prompts.system/user/orchestratorinagents.ymlare always a local file path. This issue adds a second source: fetch by name from Langfuse instead.Proposed YAML — needs research before locking in
Two things the assignee needs to research and settle, not assume: whether
productionorlatest(auto-tracks most recent save, no promotion step) is the better default label for this project; and whetherlangfuse:as a direct key is right, vs. reserving it for later if a second remote source ever shows up (default to the direct key — don't build for a hypothetical second backend now).Runtime: fetch once at startup, no caching
One fetch per node when the graph is built at server startup, held for the process lifetime — no TTL, no refetching, no live updates in v1. A fetch failure at startup is fatal: the server refuses to start rather than run with a missing prompt (fail closed).
generate: health check, not scaffolding#18 makes
generatecreate local stub files for missing prompts — that doesn't apply here, since a Langfuse-sourced prompt has no local file by design.generateshould skip these nodes for scaffolding, and instead run a lightweight connectivity check (credentials present, package importable, Langfuse reachable) — not a per-prompt existence check.Non-goals for v1