> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Link prompt versions to traces from code

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = "Use case - Serving prompts from code while still tracking prompt version metadata in traces and experiments"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## Summary

When serving prompts from code, you can still link prompt versions to traces and experiments using two approaches. For Braintrust-managed prompts, use `load_prompt` and `prompt.build()` to automatically attach `metadata.prompt.id` to LLM spans, enabling native "Go to origin prompt" links in the trace UI. For hardcoded prompts served directly from your codebase, log custom metadata fields like `prompt.name` and `prompt.version` to track versions manually, though this won't provide native prompt linking.

## Configuration steps

### Option 1: Managed prompts (native trace linking)

Load a Braintrust-managed prompt by slug. Calling `prompt.build()` attaches `metadata.prompt.id` to the LLM span automatically, enabling the native "Go to origin prompt" link in the trace UI.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import braintrust

prompt = braintrust.load_prompt("my-prompt-slug")
# Optionally pin a version or environment:
# braintrust.load_prompt("my-prompt-slug", version="abc123")
# braintrust.load_prompt("my-prompt-slug", environment="production")

payload = prompt.build(input_var="hello")
response = openai_client.chat.completions.create(**payload)
```

Traces will show the exact prompt version as the origin. Use `version` for reproducible experiments; use `environment` to route to the env-assigned version.

### Option 2: Hardcoded/code-served prompts (custom metadata)

If prompts are not loaded from Braintrust, native prompt linking is not available. Log version identity as custom metadata instead.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
span.log(
    metadata={
        "prompt": {
            "name": "my-prompt",
            "version": "v1.2.0",  # or a Git SHA
        }
    }
)
```

This does **not** produce the native origin-prompt link, but the fields are filterable and can be used to build custom views in Logs.

### Viewing and testing raw prompts

For hardcoded prompts, click **Run** in the trace view to inspect and test the raw prompt ad hoc without saving it to Braintrust.

## Comparison

| Approach                       | Native trace link | Filterable | Ad-hoc testing |
| ------------------------------ | ----------------- | ---------- | -------------- |
| `load_prompt` + `prompt.build` | ✅                 | ✅          | ✅              |
| Hardcoded + custom metadata    | ❌                 | ✅          | ✅ (via Run)    |

> Native linking from slug alone (without `load_prompt`) is not yet supported. Track BT-4319 for updates.