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

# Prompts

> Version the prompts in your agent's code, see which prompt version produced each model call, and compare cost and latency across versions.

A prompt is a named piece of text that your agent sends to a model, such as its instructions or a task template. Tilde versions every prompt your agent ships, and links each model call to the prompt versions that produced it.

Your code owns its prompts. You write them in your framework, as you do today. When you deploy, Tilde reads them from your code and registers any new versions. To change a prompt, you change the code and deploy again.

## What Tilde records

Each distinct prompt text becomes an immutable version, identified by a hash. An unchanged prompt never creates a new version.

| Field | What it holds |
| - | - |
| Name | A stable name, such as `support-agent/instructions`. |
| Version | A number, such as v3, and a content hash. |
| Template | The prompt text, with its sections. |
| Config | Model settings you version with the text, such as the model and temperature. |
| Variables | The names the template expects. |
| Format | How the template marks variables. See [Formats](#formats). |
| Origin | Where your code declares the prompt, such as `src/agent.ts#support.instructions`. |
| First shipped by | The first deployment that shipped the version, and its commit. |

## How prompts are registered

`tilde deploy` registers a deployment and its prompts in one step.

<Steps>
  <Step title="Tilde loads your entry module">
    `tilde deploy` loads your agent's entry module in discovery mode. The SDK starts nothing in this mode, so your agent does not connect or run.
  </Step>

  <Step title="Tilde finds your prompts">
    It collects each prompt you declared with `definePrompt`, and each prompt your framework adapter recognises, such as an agent's instructions.
  </Step>

  <Step title="Tilde registers the deployment">
    It registers the deployment with those prompts, and prints the deployment token. New text becomes a new version.
  </Step>
</Steps>

Define your agents at module scope, and export them from the entry module, so discovery can find them. See [Release agents from CI](/docs/deployment/ci-cd).

```bash theme={"system"}
npx tilde deploy dist/index.js --dry-run   # print what would be registered
python -m tilde deploy main.py --dry-run
```

## Declare a prompt

Framework adapters register your framework's prompts for you. Use `definePrompt` for prompts the adapter cannot find, or when you want variables and sections.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  import { definePrompt } from "@trytilde/sdk";

  export const triage = definePrompt("triage", {
    template: "You triage requests for {{product}}.\n{{> tone}}",
    sections: { tone: "Be direct and warm." },
    config: { model: "gpt-5", temperature: 0.2 },
  });

  // Inside run(ctx):
  const instructions = ctx.prompt(triage).render({ product: "Acme" });
  ```

  ```python Python theme={"system"}
  import tilde

  TRIAGE = tilde.define_prompt(
      "triage",
      template="You triage requests for {{product}}.\n{{> tone}}",
      sections={"tone": "Be direct and warm."},
      config={"model": "gpt-5", "temperature": 0.2},
  )

  # Inside run(ctx):
  instructions = TRIAGE.render(product="Acme")
  ```
</CodeGroup>

`{{name}}` is a variable, and `{{> name}}` includes a section. Rendering fails if a variable is missing, or a section is not declared.

## Link model calls to prompts

A successful `render()` marks that prompt version as active for the invocation. From then on, the SDK tags each LLM request with the active prompt versions. The gateway reads the tag, removes it, and records it with the request.

Tilde also matches prompts it can see in the request itself. After each model call, the gateway compares the request's system, developer, and user messages with the text of the deployment's prompt versions. It does this off the request path, so matching adds no latency.

For [sidecar agents](/docs/deployment/sidecar-agents), the sidecar matches prompts locally. Request bodies never leave the sidecar. It sends the gateway only the matched prompt names and versions.

<Info>
  Tilde matches OpenAI, Anthropic, Google Gemini, Amazon Bedrock, and Cohere request formats. A dynamic prompt can only be linked through its tag, because its text exists only at runtime.
</Info>

In [traces](/docs/traces), spans from a stamped model call carry the prompt name and hash.

## Formats

| Format | Variables | Typical source |
| - | - | - |
| **Plain** | None | A fixed instruction string. |
| **Mustache** | `{{name}}`, and `{{> section}}` includes | `definePrompt`, and Mustache templates in frameworks. |
| **Braces** | `{name}` | Python format strings, LangChain f-string templates, and CrewAI YAML. |
| **Dynamic** | Decided at runtime | Instructions written as a function. Tilde stores the function's source as the template. |

Tilde reports some prompts as warnings, without versioning them. These include OpenAI hosted prompts, LangSmith Hub prompts, and Jinja2 templates. Their text lives outside your code.

## Limits

| Limit | Value |
| - | - |
| Name | 1 to 128 characters: letters, digits, `.`, `_`, `/`, and `-`. |
| Template | 256 KiB. |
| Config | 64 KiB. |
| Sections | 64 per prompt. |

## Next steps

<Columns cols={2}>
  <Card title="Manage prompts" href="/docs/prompts/management">
    Review versions, compare them, and see their usage.
  </Card>

  <Card title="Framework integrations" href="/docs/frameworks/overview">
    See which prompts each framework adapter registers.
  </Card>
</Columns>