feat(logfire): add ManagedPrompt capability

[dmontagu]

Adds ManagedPrompt, a capability that backs an agent's instructions with a Logfire-managed prompt so you can version, label, roll out, and A/B test prompts from the Logfire UI without redeploying.

Usage

from pydantic_ai import Agent
from pydantic_ai_harness.logfire import ManagedPrompt

agent = Agent(
    'openai:gpt-5',
    capabilities=[
        ManagedPrompt(
            'support_agent',
            default='You are a helpful customer support agent. Be friendly and concise.',
            label='production',
        )
    ],
)

The slug support_agent is declared as the managed variable prompt__support_agent (Logfire's Prompt-management naming; hyphens → underscores). The default is the offline safety net used when no remote value is available.

How it works

• Resolves the prompt once per run inside wrap_run, keeping the ResolvedVariable open as a context manager for the whole run — so the selected label/version are attached as baggage to every child span (model requests, tools, and the run span). Runs outermost (wraps=[Instrumentation]) so the run span is tagged too.
• The per-run resolution is held in a ContextVar, so a single capability instance is safe across concurrent runs.

API

• ManagedPrompt(slug, *, default, label=, targeting_key=, attributes=, render_template=, logfire_instance=).
• targeting_key/attributes accept a static value or a callable of RunContext (e.g. lambda ctx: ctx.deps.user_id).
• Pass an existing logfire.Variable instead of a slug to use your own declaration. Declaring the same slug twice is fine (each builds its own backing variable).
• render_template=True renders the prompt as Handlebars against deps (like TemplateStr); off by default. Requires pydantic-ai-slim[spec].
• ManagedPrompt.resolved exposes the active run's ResolvedVariable (value/label/version/reason).

Packaging

• New optional extra: pydantic-ai-harness[logfire] (logfire>=4.31.0, the CI-tested floor).
• Built directly on the public logfire.Variable API (no registry side effects, so duplicate slugs don't raise on any supported logfire version).
• Lives in pydantic_ai_harness.logfire; the test directory is named logfire_variables to avoid shadowing the third-party logfire package under pyright's tests execution-environment root.

Testing

• 100% branch coverage; pyright-strict and ruff clean.
• Covers code-default fallback, provider-backed resolution via LocalVariablesOptions (remote value + label baggage), span/baggage assertions via capfire inline snapshots, targeting, dedup, the prompt__ prefix warning, and Handlebars rendering.

Future: first-party Managed capability

A broader pydantic_ai.managed.logfire.Managed capability is in flight upstream in pydantic-ai#5107 — it'll cover instructions, model settings, and whole-spec variables, with a planned phase-2 contribute_run_spec hook. Once it ships, users will be able to import it directly from pydantic-ai and ManagedPrompt here can either delegate to it or stay as the prompt-only convenience.

The README's ManagedPrompt section now carries a callout pointing at #5107 so users picking it up today know where things are headed.

Related

• #90 — Prompt Templates / Parameterized User Prompts (complementary: user-prompt side)
• #99 — Cache-Aware Prompt Construction (this capability is the first concrete example of the trade-off; see the new README section)
• #147 — ModelSettings.cache_control (the cache-control surface that managed-prompt rollouts will interact with)

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.