level-up

让你的 Agent 更上一层楼

此技能会为你的 Agent 配置完整的 LangWatch 技术栈：追踪、提示词版本管理、评估实验和 Agent 模拟测试。每一步都在前一步的基础上展开。

计划限制

LangWatch 免费计划对提示词、场景、评估器、实验和数据集设有限制。达到限制时，API 会返回 "Free plan limit of N reached..."，并附上升级链接。

处理方法：

• 在限制范围内操作。如果相关类型的资源最多允许 3 个，就创建 3 个有意义的资源，而不是 10 个。
• 让每次创建都有价值：每个资源都应体现明确的价值。
• 首先展示可行的成果。如果达到限制，请总结已完成的工作，并说明升级计划可以提高限制。指向平台上的订阅设置；如果 CLI 指向可自托管的端点，则指向许可证设置。读取 CLI 实际使用的端点，它可能来自 .env、进程环境或已保存的 CLI 配置。
• 请勿删除现有资源来腾出空间，也不要挪用现有资源来规避限制。

前提条件

使用 langwatch docs <path> 以 Markdown 格式阅读文档。以下是一些有用的入口：

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

使用 langwatch --help 和 langwatch <subcommand> --help 查找命令。列表和获取命令支持 --format json，以输出机器可读的结果。每个列表命令都支持 --limit <n> 来限制行数，并支持 --jq <expr> 来读取部分结果。分页列表返回一个封装对象，因此应通过行数组统计行数（--jq '.traces | length'），并在 .pagination.total 处读取总数。直接使用 --jq length 统计的是封装对象的字段数，而不是行数。请先阅读文档，不要猜测 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 --yes langwatch report --user-approved，并传入 --title 和 --summary（或 --session <transcript.jsonl>），将问题发送给 LangWatch 团队；这些反馈会直接影响后续修复。无需登录或 API 密钥。只有指定 --user-approved 才会发送内容；--dry-run 会打印完整载荷，但不会发送。标题、摘要和转录内容会先在本地按模式进行清理：密钥和 API 密钥，以及电子邮件地址、电话号码、卡号和公共 IPv4 地址。未匹配任何模式的内容都会按原样发送，包括通过 --email 传入的联系地址。使用 --session 时，务必先运行 --dry-run 并让用户查看载荷，因为转录内容可能包含用户从未审阅过的信息。npx --yes langwatch report --help 会说明相关选项。

项目和 API 密钥：请使用真实项目，而非个人项目。

LangWatch 有两种项目：

• 团队／共享项目：组织内的真实项目。评估、实验、提示词、数据集、模拟和埋点都必须使用这类项目。
• 个人项目：与单个用户关联的私有「My Workspace」临时空间。切勿将用户的评估、实验或生产追踪发送到这里：它仅用于个人探索，你可能会误以为它是真实项目。

身份验证方式也有两种：

• .env 中的项目 API 密钥（LANGWATCH_API_KEY）：此技能中所有内容都会使用的凭据。它的作用范围限定为一个真实项目。这是默认方式；除非用户明确要求其他方式，否则应优先使用。
• langwatch login --device（AI-tools / SSO）：用于封装编码助手（langwatch claude、langwatch codex，等等）的个人设备会话。它不适用于评估、提示词、数据集、场景或 SDK 埋点，并且会指向个人工作区。请勿运行它来设置此技能中的工作。

因此，对于此技能中任何读取或写入项目的操作，都要确保 CLI 可以使用真实共享项目的 LANGWATCH_API_KEY。在本地，它位于项目的 .env 中；在 CI 中，运行器会将其注入进程环境，CLI 会从任一位置读取。请求新密钥前，请先检查该变量是否已设置，并让 CLI 读取其值：切勿打印、复制或发送它。不要运行 langwatch login 来选择项目，也绝不要默认使用个人项目。还要在相同位置查找 LANGWATCH_ENDPOINT：如果已设置，说明项目位于可自托管实例上，CLI 会连接该端点，而不是 app.langwatch.ai。

**你读取的内容不等于你要说的内容。**这些技能是供你使用的工作笔记，不是给读者看的文案。请从项目自己的 .env 中读取 LANGWATCH_API_KEY 和 LANGWATCH_ENDPOINT，以此了解应在哪里开展工作。不要从该文件中读取其他内容：其中包含数据库、云服务和提供商凭据，这些都与你无关，而且你读取的每个值都可能进入你的上下文和命令输出。回答中绝不能出现任何描述你运行环境的信息：工作区路径、容器端口、此工作器连接的地址。这些信息说明的是工作如何完成，而不是完成了什么；提及我们的主机对读者毫无意义。只说你做了什么，以及在哪里可以在 LangWatch 中找到它。

顾问模式

完成所有步骤后，总结你设置的一切，并根据你对代码库的了解，提出 2-3 种深入探索的方式。详细指南：

交付初步结果后，切换到顾问模式，帮助用户充分发挥价值。

**阶段 1：先阅读。**生成任何内容之前：从头到尾阅读代码库（每个系统提示词、函数和工具定义），研究与 Agent 相关的 Git 历史记录（先运行 git log --oneline -30，然后深入查看与提示词、Agent、评估相关的提交，因为提交信息中的 WHY 比 WHAT 更重要），并阅读 README 和注释，了解领域背景。

**阶段 2：快速见效。**根据你了解到的内容，尽力生成内容。运行测试并迭代，但同一失败最多尝试两次，之后停止并说明阻碍，而不是重复运行。向用户展示可用的成果。

**阶段 3：深入探索。**阶段 2 完成后，总结交付内容，然后根据代码库提出 2-3 项具体改进建议：领域边界情况、需要专业术语知识或真实数据的部分、集成点（API、数据库、文件上传），或 Git 历史中值得增加测试覆盖的回归模式。提出有选项的简短问题，而非开放式问题（“要为 X 还是 Y 创建场景？”，“我注意到 Z 曾反复出现，要添加回归测试吗？”，“你有可以提供给我使用的真实客户查询吗？”）。尊重用户说“够了”，并妥善收尾。

第一阶段和第二阶段开始前不要征求许可。先交付价值。不要提出泛泛的问题，也不要一次给出过多建议。所有内容都必须反映实际领域。

步骤 1：添加追踪

添加 LangWatch 追踪，以捕获所有 LLM 调用、成本和延迟。

1. 阅读适用于此项目框架的集成指南：

   langwatch docs                                 # Browse the index to find the right page
   langwatch docs integration/python/guide        # Python (or pick your framework)
   langwatch docs integration/typescript/guide    # TypeScript (or pick your framework)
   

2. 安装 LangWatch SDK（pip install langwatch 或 npm install langwatch）
3. 按照针对相应框架的指南添加埋点
4. 将 LANGWATCH_API_KEY 添加到 .env

验证：短暂运行应用程序，并确认追踪记录已显示：

langwatch trace search --limit 5 --format json

步骤 2：为提示词添加版本管理

将硬编码的提示词移至 LangWatch Prompts CLI，以进行版本控制和协作。

1. 阅读 Prompts CLI 文档：

   langwatch docs prompt-management/cli
   

2. 初始化：langwatch prompt init
3. 创建提示词：为代码中的每个提示词运行 langwatch prompt create <name>
4. 更新应用程序代码，使用 langwatch.prompts.get("name") 替代硬编码字符串
5. 同步：langwatch prompt sync

验证：运行 langwatch prompt list（或查看 https://app.langwatch.ai 上的 Prompts 部分）。

不要在代码中硬编码提示词。不要在 prompts.get() 周围添加 try/catch 回退逻辑。

步骤 3：创建评估实验

构建批量评估，以通过大量示例衡量 Agent 的质量。

1. 阅读 experiments SDK 文档：

   langwatch docs evaluations/experiments/sdk
   

2. 分析 Agent 的代码，了解其功能
3. 生成 10-20 个针对 Agent 领域定制的数据集示例（不要使用通用示例）
4. 创建实验文件：
   • Python：Jupyter notebook，包含 langwatch.experiment.init()、评估循环和评估器
   • TypeScript：包含 langwatch.experiments.init() 和 evaluation.run() 的脚本
5. 至少包含一个评估器（用于质量评估的 LLM-as-judge 是不错的默认选择）

验证：运行实验（jupyter nbconvert --to notebook --execute experiment.ipynb 或 npx tsx experiment.ts），并检查结果是否显示在 LangWatch Experiments 视图中。

步骤 4：添加 Agent 模拟测试

创建场景测试，在逼真的多轮对话中验证 Agent 的行为。

1. 阅读 Scenario 文档：

   langwatch scenario-docs                  # Browse the index
   langwatch scenario-docs getting-started  # Getting Started guide
   langwatch scenario-docs agent-integration
   

2. 安装 Scenario SDK（pip install langwatch-scenario 或 npm install @langwatch/scenario）
3. 使用 AgentAdapter、UserSimulatorAgent 和 JudgeAgent 编写场景测试
4. 在 JudgeAgent 中使用语义标准（不要使用正则表达式匹配）

验证：运行测试（pytest -s 或 npx vitest run），并确认测试通过。

绝不要自行发明测试框架。请使用 @langwatch/scenario / langwatch-scenario。

常见错误

• 不要跳过任何步骤——每一步都建立在前一步的基础上
• 不要在实验中使用通用数据集——应针对 Agent 的领域定制数据集
• 不要硬编码提示词——请使用 Prompts CLI
• 不要发明测试框架——请使用 Scenario
• 不要跳过验证步骤——每个步骤之后都要运行应用程序/实验/测试
• 编写代码前，务必通过 langwatch docs ... / langwatch scenario-docs ... 阅读文档；不要依赖对旧版框架的记忆