Studio 中的可观测性

LangSmith Studio 提供了超越执行的检查、调试和改进你应用的工具。通过处理追踪、数据集和提示，你可以深入了解应用程序的行为方式、衡量其性能并优化其输出：

• 迭代提示：直接在图节点内或通过 Playground 修改提示。
• 在数据集上运行实验：在你的助手上执行一个 LangSmith 数据集以评分并比较结果。
• 调试 LangSmith 追踪：将已追踪的运行导入 Studio，并可选择将其克隆到你的本地 agent。
• 向数据集添加节点：将线程历史的各部分转化为数据集示例，用于评估或进一步分析。

迭代提示

Studio 支持以下在图中修改提示的方法：

• 直接节点编辑
• Playground 界面

直接节点编辑

Studio 允许你直接从图界面编辑在单个节点内使用的提示。

图配置

定义你的配置，使用 langgraph_nodes 和 langgraph_type 键来指定提示字段及其关联的节点。

langgraph_nodes

• 描述：指定配置字段与图中的哪些节点相关联。
• 值类型：字符串数组，其中每个字符串是你图中一个节点的名称。
• 使用上下文：在 Pydantic 模型的 json_schema_extra 字典中，或 dataclass 的 metadata["json_schema_extra"] 字典中包含此项。
• 示例：

  system_prompt: str = Field(
      default="You are a helpful AI assistant.",
      json_schema_extra={"langgraph_nodes": ["call_model", "other_node"]},
  )

langgraph_type

• 描述：指定配置字段的类型，这决定了它在 UI 中如何被处理。
• 值类型：字符串
• 支持的值：
  • "prompt"：表明该字段包含在 UI 中需要特殊处理的提示文本。
• 使用上下文：在 Pydantic 模型的 json_schema_extra 字典中，或 dataclass 的 metadata["json_schema_extra"] 字典中包含此项。
• 示例：

  system_prompt: str = Field(
      default="You are a helpful AI assistant.",
      json_schema_extra={
          "langgraph_nodes": ["call_model"],
          "langgraph_type": "prompt",
      },
  )

完整示例配置

## Using Pydantic
from pydantic import BaseModel, Field
from typing import Annotated, Literal

class Configuration(BaseModel):
    """The configuration for the agent."""

    system_prompt: str = Field(
        default="You are a helpful AI assistant.",
        description="The system prompt to use for the agent's interactions. "
        "This prompt sets the context and behavior for the agent.",
        json_schema_extra={
            "langgraph_nodes": ["call_model"],
            "langgraph_type": "prompt",
        },
    )

    model: Annotated[
        Literal[
            "anthropic/claude-sonnet-4-6",
            "anthropic/claude-haiku-4-5-20251001",
            "openai/o1",
            "openai/gpt-5.4-mini",
            "openai/o1-mini",
            "openai/o3-mini",
        ],
        {"__template_metadata__": {"kind": "llm"}},
    ] = Field(
        default="openai/gpt-5.4-mini",
        description="The name of the language model to use for the agent's main interactions. "
        "Should be in the form: provider/model-name.",
        json_schema_extra={"langgraph_nodes": ["call_model"]},
    )

## Using Dataclasses
from dataclasses import dataclass, field

@dataclass(kw_only=True)
class Configuration:
    """The configuration for the agent."""

    system_prompt: str = field(
        default="You are a helpful AI assistant.",
        metadata={
            "description": "The system prompt to use for the agent's interactions. "
            "This prompt sets the context and behavior for the agent.",
            "json_schema_extra": {"langgraph_nodes": ["call_model"]},
        },
    )

    model: Annotated[str, {"__template_metadata__": {"kind": "llm"}}] = field(
        default="anthropic/claude-sonnet-4-6",
        metadata={
            "description": "The name of the language model to use for the agent's main interactions. "
            "Should be in the form: provider/model-name.",
            "json_schema_extra": {"langgraph_nodes": ["call_model"]},
        },
    )

在 UI 中编辑提示

1. 在带有关联配置字段的节点上找到齿轮图标。
2. 点击以打开配置模态框。
3. 编辑这些值。
4. 保存以更新当前助手版本或创建一个新版本。

Playground

Playground 界面允许在不运行整个图的情况下测试单个 LLM 调用：

1. 选择一个线程。
2. 在一个节点上点击 View LLM Runs。这会列出该节点内进行的所有 LLM 调用（如有）。
3. 选择一个 LLM 运行以在 Playground 中打开。
4. 修改提示并测试不同的模型和工具设置。
5. 将更新后的提示复制回你的图。

在数据集上运行实验

Studio 让你能够运行评估，方法是在预定义的 LangSmith 数据集上执行你的助手。这让你能够在各种输入上测试性能、将输出与参考答案进行比较，并使用配置的评估器为结果评分。

本指南展示如何直接从 Studio 运行一次完整的端到端实验。

前提条件

在运行实验之前，请确保你具备以下内容：

• 一个 LangSmith 数据集：你的数据集应包含你想要测试的输入，以及可选的用于比较的参考输出。输入的 schema 必须与助手所要求的输入 schema 匹配。有关 schema 的更多信息，请参阅 graph API schema 文档。有关创建数据集的更多信息，请参阅如何管理数据集。
• （可选）评估器：你可以在 LangSmith 中将评估器（例如 LLM-as-a-Judge、启发式规则或自定义函数）附加到你的数据集上。这些会在图处理完所有输入后自动运行。
• 一个运行的应用：实验可以针对以下对象运行：
  • 部署在 LangSmith上的应用。
  • 通过 langgraph-cli启动的本地运行应用。

NOTE

Studio 实验遵循与其他实验相同的数据保留规则。默认情况下，追踪具有基础层级保留（14 天）。但是，如果向追踪添加了反馈，它们会自动升级到延长层级保留（截至 2026 年 9 月 14 日为 180 天）。可以通过两种方式添加反馈：

• 数据集配置了评估器。
• 手动向追踪添加反馈。

此自动升级会同时增加追踪的保留期和成本。更多详情，请参阅数据保留自动升级。

实验设置

1. 启动实验。点击 Studio 页面右上角的 Run experiment 按钮。
2. 选择你的数据集。在出现的模态框中，选择用于实验的数据集（或特定的数据集切分）并点击 Start。
3. 监控进度。数据集中的所有输入现在都会在活跃助手上运行。通过右上角的徽章监控实验进度。
4. 你可以在实验于后台运行时继续在 Studio 中工作。随时点击 arrow="true" 图标按钮以导航到 LangSmith 并查看详细的实验结果。

调试 LangSmith 追踪

本指南解释如何在 Studio 中打开 LangSmith 追踪以进行交互式调查和调试。

打开已部署的线程

1. 打开 LangSmith 追踪，选择根运行。
2. 点击 Run in Studio。

这会打开 Studio，它连接到相关部署，并选中该追踪的父线程。

使用远程追踪测试本地 agent

本节解释如何针对来自 LangSmith 的远程追踪测试本地 agent。这使你能够使用生产追踪作为本地测试的输入，从而在你的开发环境中调试和验证 agent 的修改。

前置条件

• 一个被 LangSmith 追踪的线程
• 一个本地运行的 agent。

INFO

本地 agent 要求

• langgraph>=0.3.18
• langgraph-api>=0.0.32
• 包含与远程追踪中相同的一组节点

克隆线程

1. 打开 LangSmith 追踪，选择根运行。
2. 点击 Run in Studio 旁边的下拉菜单。
3. 输入你本地 agent 的 URL。
4. 选择 Clone thread locally。
5. 如果存在多个图，选择目标图。

你的本地 agent 中会创建一个新线程，其线程历史从远程线程推断并复制而来，并且你会被导航到用于本地运行应用的 Studio。

向数据集添加节点

从线程日志中的节点添加示例到 LangSmith 数据集。这对于评估 agent 的各个步骤很有用。

1. 选择一个线程。
2. 点击 Add to Dataset。
3. 选择你希望将其输入/输出添加到数据集的节点。
4. 对于每个选定的节点，选择要在其中创建示例的目标数据集。默认会选择一个针对特定助手和节点的数据集。如果该数据集尚不存在，将会被创建。
5. 在将示例添加到数据集之前，按需编辑该示例的输入/输出。
6. 选择页面底部的 Add to dataset，以将所有选定节点添加到各自的数据集。

更多详情，请参阅如何评估应用的中间步骤。

---