Quickstart: create and use a prompt

This quickstart stores a system prompt in Studio, uses it from a Python script through the production alias, then changes the script's behavior by pointing production at a new version. The script itself doesn't change.

You need Python 3.10 or later, uv, and a Mistral API key.

Install the SDK

uv init first-prompt && cd first-prompt
uv add mistralai
export MISTRAL_API_KEY="your-api-key"

uv init first-prompt && cd first-prompt
uv add mistralai
export MISTRAL_API_KEY="your-api-key"

Create the prompt

Create create_prompt.py. It stores a support-reply prompt with a {{product}} variable and points the production alias at its first version:

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

prompt = client.beta.prompts.create(
    name="support-reply",
    title="Support reply",
    description="Tone and structure for customer support replies.",
    definition={
        "content": (
            "You are a customer support assistant for {{product}}. "
            "Acknowledge the issue, then propose the next action."
        ),
        "variables": [{"name": "product"}],
    },
    aliases=["production"],
)
print(f"Prompt ID: {prompt.id}, version {prompt.version}")

import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

prompt = client.beta.prompts.create(
    name="support-reply",
    title="Support reply",
    description="Tone and structure for customer support replies.",
    definition={
        "content": (
            "You are a customer support assistant for {{product}}. "
            "Acknowledge the issue, then propose the next action."
        ),
        "variables": [{"name": "product"}],
    },
    aliases=["production"],
)
print(f"Prompt ID: {prompt.id}, version {prompt.version}")

Information

If a prompt named support-reply already exists in your workspace, create fails with a 409 error. Change name in the script, then run it again.

Run it, and copy the prompt ID it prints:

uv run create_prompt.py

uv run create_prompt.py

The prompt is private: only you can see it. It now appears in Studio›Prompts ↗ in Studio.

Use it from your code

Create app.py. It fetches the version that production points to, fills in the variable, and passes the result as the system message:

import os

from mistralai.client import Mistral

PROMPT_ID = "your-prompt-id"

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

prompt = client.beta.prompts.get(prompt_id=PROMPT_ID, alias="production")
system_prompt = prompt.definition.content.replace("{{product}}", "Acme Cloud")

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "I can't sign in to my account."},
    ],
)
print(f"Version {prompt.version}:\n{response.choices[0].message.content}")

import os

from mistralai.client import Mistral

PROMPT_ID = "your-prompt-id"

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

prompt = client.beta.prompts.get(prompt_id=PROMPT_ID, alias="production")
system_prompt = prompt.definition.content.replace("{{product}}", "Acme Cloud")

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "I can't sign in to my account."},
    ],
)
print(f"Version {prompt.version}:\n{response.choices[0].message.content}")

Replace your-prompt-id, then run it:

uv run app.py

uv run app.py

The script prints the version it used, 1, and the model's reply.

Promote a new version

Create promote.py. It saves a new version that asks for shorter replies, then points production at it:

import os

from mistralai.client import Mistral

PROMPT_ID = "your-prompt-id"

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

new_version = client.beta.prompts.create_version(
    prompt_id=PROMPT_ID,
    definition={
        "content": (
            "You are a customer support assistant for {{product}}. "
            "Acknowledge the issue, then propose the next action. "
            "Answer in two sentences at most."
        ),
        "variables": [{"name": "product"}],
    },
    notes="Shorter replies",
)

client.beta.prompts.update_version_metadata(
    prompt_id=PROMPT_ID,
    version=new_version.version,
    aliases={"values": ["production"]},
)
print(f"production now points to version {new_version.version}")

import os

from mistralai.client import Mistral

PROMPT_ID = "your-prompt-id"

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

new_version = client.beta.prompts.create_version(
    prompt_id=PROMPT_ID,
    definition={
        "content": (
            "You are a customer support assistant for {{product}}. "
            "Acknowledge the issue, then propose the next action. "
            "Answer in two sentences at most."
        ),
        "variables": [{"name": "product"}],
    },
    notes="Shorter replies",
)

client.beta.prompts.update_version_metadata(
    prompt_id=PROMPT_ID,
    version=new_version.version,
    aliases={"values": ["production"]},
)
print(f"production now points to version {new_version.version}")

Run it, then run app.py again without changing it:

uv run promote.py
uv run app.py

uv run promote.py
uv run app.py

You should see

app.py now prints Version 2, and the reply is at most two sentences long. Your application picked up the new prompt without a code change or a redeployment.

In Studio›Prompts ↗, open Support reply: the version history lists both versions, with the notes of version 2. The production alias is on version 2. To roll back, point production at version 1 again.

Going further

Versions and aliases

Use prompts in chat completions

Create a prompt in Studio

Create a skill in Studio

Quickstart: run your first evaluation