> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.

# Getting started with the Prompt Library

Your agent depends on prompts that change frequently. The Prompt Library lets you manage them
outside your codebase, version each change automatically, and link the exact version that ran
to its trace.

![Prompt Library page showing versioned prompts](/docs/opik/_fern-img/58b75fbabe1f162e05e87ab9041465da51f2f3e0dc2b321179672fcd84dc5a20.webp)

## Adding the Prompt Library to your code

#### AI Integration

You can use the Opik skills to wire your existing agent up to the Prompt Library:

#### Install the Opik skill

```bash wordWrap
uvx opik mcp configure
```

It installs the Opik skills and connects the Opik MCP server. It needs [`uv`](https://docs.astral.sh/uv/).

This skill is compatible with all coding agents including Claude Code, Codex, Cursor, OpenCode and more.

#### Run the integration

Once the skill is installed, you can integrate with Opik using the following prompt:

```
Version my prompts in Opik using the /opik-instrument command.
```

#### Manual integration

There are two parts: you **create** a prompt, and then you **fetch** it at runtime from
inside your agent.

### Step 1 — Define and push your first prompt

Push the prompt to Opik. You only do this once (or whenever you want to create a new version
from code).

**`Python`**

```python title="Python" wordWrap
import opik

client = opik.Opik()

client.create_prompt(
    name="system_prompt",
    prompt="You are a helpful assistant specializing in {{domain}}.",
    project_name="my-agent",
)
```

**`TypeScript`**

```ts title="TypeScript" wordWrap
import { Opik } from "opik";

const client = new Opik();

await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a helpful assistant specializing in {{domain}}.",
  projectName: "my-agent",
});
```

> **Tip**
>
> Prompts are **project-scoped**. Always pass a `project_name` / `projectName` so two agents can use the same prompt names independently.

### Step 2 — Fetch your prompt at runtime

Use `get_prompt` / `getPrompt` inside your agent to pull the version you want and render it
with your runtime values.

**`Python`**

```python title="Python" wordWrap
import opik

client = opik.Opik()

@opik.track(project_name="my-agent")
def run_agent(user_input: str):
    prompt = client.get_prompt(
        name="system_prompt",
        project_name="my-agent",
    )

    system_prompt = prompt.format(domain="customer support")

    response = call_llm(
        model="gpt-4o-mini",
        system_prompt=system_prompt,
        user_input=user_input,
    )
    return response
```

**`TypeScript`**

```ts title="TypeScript" wordWrap
import { Opik, track } from "opik";

const client = new Opik();

const runAgent = track(
  { name: "run_agent", projectName: "my-agent" },
  async (userInput: string) => {
    const prompt = await client.getPrompt({
      name: "system_prompt",
      projectName: "my-agent",
    });

    const systemPrompt = prompt?.format({ domain: "customer support" });

    const response = await callLlm({
      model: "gpt-4o-mini",
      systemPrompt,
      userInput,
    });
    return response;
  },
);
```

> **Tip**
>
> Calling `get_prompt` / `getPrompt` inside a tracked function (`@opik.track` in Python,
> `track()` in TypeScript) lets Opik link the prompt version to the trace automatically.

## Choosing a version

Pass `version` or `environment` to control which version is returned:

* **Omit `version`** (default): The most recently created version. Useful when you want the agent to pick up new prompt edits automatically.
* **`"v3"`** (or any `v<N>` name): A specific version. Useful when you want the prompt to stay fixed regardless of newer edits, for example when reproducing a past run or comparing versions.
* **`environment="production"`**: The version deployed to that environment. Useful in production code: you choose which version the agent serves from the Opik UI, without changing code. See [Environments](/docs/opik/development/prompt-library/environments).

**`Python`**

```python title="Python" wordWrap
# Fetch a specific version
v3 = client.get_prompt(name="system_prompt", version="v3", project_name="my-agent")

# Fetch the most recent version (omit `version`)
latest = client.get_prompt(name="system_prompt", project_name="my-agent")

# Fetch the version deployed to production
prod = client.get_prompt(name="system_prompt", environment="production", project_name="my-agent")
```

**`TypeScript`**

```ts title="TypeScript" wordWrap
// Fetch a specific version
const v3 = await client.getPrompt({
  name: "system_prompt",
  version: "v3",
  projectName: "my-agent",
});

// Fetch the most recent version (omit `version`)
const latest = await client.getPrompt({
  name: "system_prompt",
  projectName: "my-agent",
});

// Fetch the version deployed to production
const prod = await client.getPrompt({
  name: "system_prompt",
  environment: "production",
  projectName: "my-agent",
});
```

## Chat prompts

For multi-turn agents with system, user, and assistant roles, use `create_chat_prompt` /
`createChatPrompt` and the matching `get_chat_prompt` / `getChatPrompt`. See
[Text and chat prompts](/docs/opik/development/prompt-library/prompt-types) for a deeper comparison,
multimodal content, and template engines.

**`Python`**

```python title="Python" wordWrap
client.create_chat_prompt(
    name="support_assistant",
    messages=[
        {"role": "system", "content": "You are a helpful support agent for {{company}}."},
        {"role": "user", "content": "{{user_query}}"},
    ],
    project_name="my-agent",
)

chat_prompt = client.get_chat_prompt(
    name="support_assistant",
    version="v3",
    project_name="my-agent",
)

messages = chat_prompt.format(
    variables={"company": "Acme", "user_query": "How do I reset my password?"},
)
```

**`TypeScript`**

```ts title="TypeScript" wordWrap
await client.createChatPrompt({
  name: "support_assistant",
  messages: [
    { role: "system", content: "You are a helpful support agent for {{company}}." },
    { role: "user", content: "{{user_query}}" },
  ],
  projectName: "my-agent",
});

const chatPrompt = await client.getChatPrompt({
  name: "support_assistant",
  version: "v3",
  projectName: "my-agent",
});

const messages = chatPrompt?.format({
  company: "Acme",
  user_query: "How do I reset my password?",
});
```

> **Tip**
>
> **Recommended if you build with an AI coding assistant.** One command — `opik configure` —
> installs both the [MCP server](/docs/opik/mcp-server) and the Opik skills, and your assistant can then
> version prompts here as it edits them, and measure whether a change actually helped instead of
> you judging by eye.
>
> An example prompt:
>
> *"Rewrite this system prompt to cut hallucinations, save each attempt to the Opik prompt library,
> and evaluate every version against my dataset so we can see which one wins."*