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

# Link prompt versions to traces from code

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> * Use case - Serving prompts from code while still tracking prompt version metadata in traces and experiments

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.