prompts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Version Your Prompts with LangWatch Prompts CLI

使用LangWatch Prompts CLI管理提示词版本

Determine Scope

确定操作范围

If the user's request is general ("set up prompt versioning", "version my prompts"):

Read the full codebase to find all hardcoded prompt strings
Study git history to understand what changed and why — focus on agent behavior changes, prompt tweaks, bug fixes. Read commit messages for context.
Set up the Prompts CLI and create managed prompts for each hardcoded prompt
Update all application code to use
```
langwatch.prompts.get()
```

If the user's request is specific ("version this prompt", "create a new prompt version"):

Focus on the specific prompt
Create or update the managed prompt
Update the relevant code to use
```
langwatch.prompts.get()
```

如果用户的需求是通用型（如“设置提示词版本控制”、“为我的提示词添加版本管理”）：

扫描整个代码库，找出所有硬编码的提示词字符串
查看git历史记录，了解变更内容及原因——重点关注Agent行为变化、提示词调整、Bug修复，通过提交信息获取上下文
配置Prompts CLI，为每个硬编码提示词创建托管提示词
更新所有应用代码，改用
```
langwatch.prompts.get()
```
调用提示词

如果用户的需求是特定型（如“为这个提示词添加版本”、“创建新的提示词版本”）：

聚焦于指定的提示词
创建或更新托管提示词
更新相关代码，改用
```
langwatch.prompts.get()
```
调用提示词

Plan Limits

计划限制说明

LangWatch's free plan has limits on prompts, scenarios, evaluators, experiments, and datasets. When you hit a limit, the API returns

"Free plan limit of N reached..."

with an upgrade link.

How to handle:

Work within the limits. If 3 resources of the relevant type are allowed, create 3 meaningful ones, not 10.
Make every creation count: each one should demonstrate clear value.
Show what works FIRST. If you hit a limit, summarize what was accomplished and note that upgrading the plan raises it — point to the subscription settings on the platform (license settings instead, if
```
LANGWATCH_ENDPOINT
```
is set — self-hosted).
Do NOT delete existing resources to make room or repurpose an existing resource to evade the limit.

LangWatch的免费计划在提示词、场景、评估器、实验和数据集方面存在限制。当达到限制时，API会返回

"Free plan limit of N reached..."

并附带升级链接。

处理方式：

在限制范围内操作。如果允许创建3个相关资源，就创建3个有实际价值的资源，而非10个
确保每个创建的资源都能体现明确价值
优先展示可行方案。如果达到限制，总结已完成的工作，并说明升级计划可提升限制——指向平台的订阅设置（若设置了
```
LANGWATCH_ENDPOINT
```
即自托管环境，则指向许可证设置）
不要删除现有资源腾出空间，也不要复用现有资源规避限制

Step 1: Read the Prompts CLI Docs

步骤1：查阅Prompts CLI文档

Use

langwatch docs <path>

to read documentation as Markdown. Some useful entry points:

bash

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

Discover commands with

langwatch --help

and

langwatch <subcommand> --help

. List and get commands accept

--format json

for machine-readable output. Read the docs first instead of guessing SDK APIs or CLI flags.

If no shell is available, fetch the same Markdown over plain HTTP. Append

.md

to any docs path (e.g. https://langwatch.ai/docs/integration/python/guide.md). Index: https://langwatch.ai/docs/llms.txt. Scenario index: https://langwatch.ai/scenario/llms.txt

If anything fails or confuses you while following this skill (broken commands, docs that do not match reality, errors you had to work around), ask the user for permission and run

npx langwatch report --user-approved

with a

--title

and

--summary

(or

--session <transcript.jsonl>

) to send it to the LangWatch team. No login needed, secrets and personal data are redacted locally, and it directly shapes what gets fixed.

npx langwatch report --help

explains the options.

Projects and API keys: target a real project, not a personal one.

LangWatch has two kinds of project:

Team / shared projects: real projects inside an organization. Evaluations, experiments, prompts, datasets, simulations and instrumentation must always target one of these.
Personal projects: a private "My Workspace" scratch space tied to a single user. Never send a user's evaluations, experiments or production traces here: it is for personal exploration only and is easily confused with a real project.

And two ways to authenticate:

A project API key in
.env
(
```
LANGWATCH_API_KEY
```
): the credential everything in these skills uses. It is scoped to one real project. This is the default; prefer it unless the user explicitly asks for something else.
langwatch login --device
(AI-tools / SSO): a personal device session for wrapping coding assistants (
```
langwatch claude
```
,
```
langwatch codex
```
, …). It is NOT for evaluations, prompts, datasets, scenarios or SDK instrumentation, and it points at a personal workspace. Do not run it to set up the work in these skills.

So for anything in these skills: make sure

LANGWATCH_API_KEY

for a real, shared project is in the project's

.env

— most environments already have this provisioned. Do NOT run

langwatch login

to pick a project, and never default to a personal project. If

LANGWATCH_ENDPOINT

is set, they are self-hosted, use that endpoint instead of app.langwatch.ai.

Then specifically read the Prompts CLI guide:

bash

langwatch docs prompt-management/cli

CRITICAL: Do NOT guess how to use the Prompts CLI. Read the docs first.

使用

langwatch docs <path>

命令以Markdown格式查阅文档。以下是一些实用的入口：

bash

langwatch docs                                    # 文档索引
langwatch docs integration/python/guide           # Python集成指南
langwatch docs integration/typescript/guide       # TypeScript集成指南
langwatch docs prompt-management/cli              # Prompts CLI文档
langwatch scenario-docs                           # 场景文档索引

通过

langwatch --help

和

langwatch <subcommand> --help

查看命令列表。列表和查询命令支持

--format json

参数以获取机器可读的输出。请先查阅文档，不要猜测SDK API或CLI参数。

如果没有可用的Shell环境，可通过普通HTTP请求获取相同的Markdown文档。在任意文档路径后添加

.md

即可（例如https://langwatch.ai/docs/integration/python/guide.md）。文档索引：https://langwatch.ai/docs/llms.txt。场景索引：https://langwatch.ai/scenario/llms.txt

如果在使用本技能过程中遇到任何问题或困惑（如命令失效、文档与实际不符、需要解决的错误），请先征得用户许可，然后运行

npx langwatch report --user-approved

命令，附带

--title

和

--summary

参数（或

--session <transcript.jsonl>

）将问题反馈给LangWatch团队。无需登录，敏感信息会在本地自动脱敏，反馈内容将直接用于问题修复。

npx langwatch report --help

可查看详细参数说明。

项目与API密钥：请指向真实项目，而非个人项目

LangWatch有两种类型的项目：

团队/共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和工具集成必须始终指向此类项目
个人项目：绑定单个用户的私有“我的工作区”临时空间。请勿将用户的评估、实验或生产追踪数据发送到此处：它仅用于个人探索，容易与真实项目混淆

两种认证方式：

.env
中的项目API密钥（
```
LANGWATCH_API_KEY
```
）：本技能所有操作使用的凭证，仅对单个真实项目生效。这是默认方式，除非用户明确要求，否则优先使用此方式
langwatch login --device
（AI工具/SSO）：用于封装代码助手的个人设备会话（如
```
langwatch claude
```
、
```
langwatch codex
```
等）。它不适用于评估、提示词、数据集、场景或SDK集成，且指向个人工作区。请勿使用此方式完成本技能中的设置工作

因此，对于本技能中的所有操作：确保项目的

.env

文件中配置了真实共享项目的

LANGWATCH_API_KEY

——大多数环境已预先配置此密钥。请勿运行

langwatch login

命令选择项目，且永远不要默认使用个人项目。如果设置了

LANGWATCH_ENDPOINT

，说明是自托管环境，请使用该端点而非app.langwatch.ai。

然后专门查阅Prompts CLI指南：

bash

langwatch docs prompt-management/cli

重要提示：请勿猜测Prompts CLI的使用方法，请先查阅文档。

Step 2: Initialize Prompts in the Project

步骤2：在项目中初始化提示词管理

bash

langwatch prompt init

Creates a

prompts.json

config and a

prompts/

directory in the project root.

bash

langwatch prompt init

此命令会在项目根目录创建

prompts.json

配置文件和

prompts/

目录。

Step 3: Create a Managed Prompt for Each Hardcoded Prompt

步骤3：为每个硬编码提示词创建托管提示词

Scan the codebase for hardcoded prompt strings (system messages, instructions). For each:

bash

langwatch prompt create <name>

Edit the generated

.prompt.yaml

file to match the original prompt content.

Model: keep the generated

model

on a current model (the latest OpenAI generation is

openai/gpt-5.5

). Never downgrade a new prompt to a legacy model like

gpt-4o-mini

Temperature: the gpt-5 family rejects a custom

temperature

— do not add

modelParameters.temperature

for those models.

create

omits it on purpose.

Structured outputs: if the prompt must return strict JSON, add a

response_format

block instead of asking for JSON in prose:

yaml

response_format:
  name: product_category
  schema:
    type: object
    properties:
      category: { type: string }
      reasoning: { type: string }
    required: [category, reasoning]
    additionalProperties: false

response_format

round-trips losslessly through

sync

pull

. See

langwatch docs prompt-management/cli

for the full format.

扫描代码库，找出所有硬编码的提示词字符串（系统消息、指令）。针对每个提示词运行：

bash

langwatch prompt create <name>

编辑生成的

.prompt.yaml

文件，使其与原始提示词内容一致。

模型选择：保留生成的

model

为当前主流模型（最新的OpenAI模型是

openai/gpt-5.5

）。请勿将新提示词降级为

gpt-4o-mini

等旧模型。

温度参数：gpt-5系列模型不支持自定义

temperature

参数——请勿为这些模型添加

modelParameters.temperature

配置。

create

命令会有意省略该参数。

结构化输出：如果提示词必须返回严格的JSON格式，请添加

response_format

块，而非在提示文本中要求返回JSON：

yaml

response_format:
  name: product_category
  schema:
    type: object
    properties:
      category: { type: string }
      reasoning: { type: string }
    required: [category, reasoning]
    additionalProperties: false

response_format

配置可通过

sync

pull

命令无损同步。完整格式请查阅

langwatch docs prompt-management/cli

。

Step 4: Update Application Code

步骤4：更新应用代码

Replace every hardcoded prompt string with a call to

langwatch.prompts.get()

Python (BAD → GOOD):

python

agent = Agent(instructions="You are a helpful assistant.")

python

import langwatch
prompt = langwatch.prompts.get("my-agent")
agent = Agent(instructions=prompt.compile().messages[0]["content"])

TypeScript (BAD → GOOD):

typescript

const systemPrompt = "You are a helpful assistant.";

typescript

const langwatch = new LangWatch();
const prompt = await langwatch.prompts.get("my-agent");

CRITICAL: Do NOT wrap

langwatch.prompts.get()

in a try/catch with a hardcoded fallback string. The whole point of prompt versioning is that prompts are managed externally. A fallback defeats this by silently reverting to a stale hardcoded copy.

将所有硬编码的提示词字符串替换为

langwatch.prompts.get()

调用。

Python（错误写法 → 正确写法）：

python

agent = Agent(instructions="You are a helpful assistant.")

python

import langwatch
prompt = langwatch.prompts.get("my-agent")
agent = Agent(instructions=prompt.compile().messages[0]["content"])

TypeScript（错误写法 → 正确写法）：

typescript

const systemPrompt = "You are a helpful assistant.";

typescript

const langwatch = new LangWatch();
const prompt = await langwatch.prompts.get("my-agent");

重要提示：请勿在

langwatch.prompts.get()

外围添加try/catch块并设置硬编码的回退字符串。提示词版本控制的核心价值在于提示词可外部管理，回退机制会无声地恢复为陈旧的硬编码副本，从而失去版本控制的意义。

Step 5: Sync to the Platform

步骤5：同步到平台

bash

langwatch prompt sync

bash

langwatch prompt sync

Step 6: Tag Versions for Deployment

步骤6：为部署版本添加标签

Three built-in tags:

latest

(auto-assigned),

production

staging

. Update code to fetch by tag:

python

prompt = langwatch.prompts.get("my-agent", tag="production")

typescript

const prompt = await langwatch.prompts.get("my-agent", { tag: "production" });

Assign tags via the CLI (or the Deploy dialog in the LangWatch UI):

bash

langwatch prompt tag assign my-agent production

For canary or blue/green deployments, create custom tags with

langwatch prompt tag create

内置三个标签：

latest

（自动分配）、

production

、

staging

。更新代码以按标签获取提示词：

python

prompt = langwatch.prompts.get("my-agent", tag="production")

typescript

const prompt = await langwatch.prompts.get("my-agent", { tag: "production" });

通过CLI（或LangWatch UI中的部署对话框）分配标签：

bash

langwatch prompt tag assign my-agent production

对于金丝雀发布或蓝绿部署，可使用

langwatch prompt tag create

创建自定义标签。

Step 7: Verify

步骤7：验证

Run

langwatch prompt list

to confirm everything synced, or open the Prompts section in the LangWatch app.

运行

langwatch prompt list

命令确认所有内容已同步，或打开LangWatch应用的提示词板块查看。

Common Mistakes

常见错误

Do NOT hardcode prompts — always fetch via
```
langwatch.prompts.get()
```
Do NOT add a hardcoded fallback string in a try/catch — that silently defeats versioning
Do NOT manually edit
```
prompts.json
```
— use the CLI
Do NOT skip
```
langwatch prompt sync
```
after creating prompts
Prefer the current flagship (
```
openai/gpt-5.5
```
) — pick an older model like
```
gpt-4o-mini
```
only when intentionally optimizing for cost or latency
Do NOT set
```
modelParameters.temperature
```
on a gpt-5-family model — it will be rejected
Do NOT ask for JSON in the prompt text when output must be structured — use a
```
response_format
```
block

请勿硬编码提示词——始终通过
```
langwatch.prompts.get()
```
获取
请勿在try/catch块中添加硬编码回退字符串——这会无声地破坏版本控制机制
请勿手动编辑
```
prompts.json
```
——请使用CLI操作
创建提示词后请勿跳过
```
langwatch prompt sync
```
步骤
优先使用当前主流模型（
```
openai/gpt-5.5
```
）——仅在有意优化成本或延迟时才选择
```
gpt-4o-mini
```
等旧模型
请勿为gpt-5系列模型设置
```
modelParameters.temperature
```
参数——该参数会被拒绝
当输出需要结构化时，请勿在提示文本中要求返回JSON——请使用
```
response_format
```
块