以编程方式使用文档

本教程向您展示如何收集 Agent Server 运行的用户反馈并自动将其关联到 追踪记录 在 LangSmith 中。创建运行时,请在请求正文的 feedback_keys 字段中包含这些键。响应将返回每个键的预签名 URL,您的客户端可使用该 URL 为 Agent Server 运行收集用户反馈。

LangSmith 使用反馈来持续改进您的智能体实现。要了解有关反馈在 LangSmith 中如何工作的更多信息,请参阅 LangSmith 反馈.

工作原理

1. 创建一个运行并包含 feedback_keys 在请求正文中。例如,调用 POST /threads/{thread_id}/runs/stream时,设置 feedback_keys 在请求正文中为:

    ["user_liked", "user_disliked"]
    

2. feedback 响应中的对象包含每个键的预签名 URL。例如, feedback 对象为:

    {
        "user_liked": "https://api.smith.langchain.com/api/v1/feedback/tokens/ef19fedf-dcac-4cbb-a59c-00661efd6425",
        "user_disliked": "https://api.smith.langchain.com/api/v1/feedback/tokens/e952734e-c0a0-417b-a04d-fc2209691ed5"
    }
    

  1. 请求返回的 URL(例如 POST /api/v1/feedback/tokens/{token_id})以将反馈键与 Agent Server 运行生成的追踪记录关联起来。有关更多详细信息,请参阅 LangSmith API 参考.
  2. LangSmith 使用所选反馈键(例如 user_liked or user_disliked).

使用 feedback_keys

创建一个运行并解析 feedback 对象。

Python SDK

from langgraph_sdk import get_client

client = get_client(url="", api_key="")

thread = await client.threads.create()
thread_id = thread["thread_id"]

feedback_urls = {}

async for event in client.runs.stream(
    thread_id,
    "agent",
    input={
        "messages": [
            {"role": "user", "content": "Tell me a joke about databases."}
        ]
    },
    stream_mode="updates",
    feedback_keys=["user_liked", "user_disliked"],
):
    if event.event == "feedback":
        # Example: {"user_liked": ".../feedback/tokens/<id>", "user_disliked": "..."}
        feedback_urls = event.data
        print("Feedback URLs:", feedback_urls)
    elif event.event == "updates":
        print(event.data)

JavaScript SDK

const client = new Client({ apiUrl: "", apiKey: "" });

const thread = await client.threads.create();
const threadId = thread.thread_id;

let feedbackUrls = {};

const streamResponse = client.runs.stream(threadId, "agent", {
  input: {
    messages: [{ role: "user", content: "Tell me a joke about databases." }],
  },
  streamMode: "updates",
  feedbackKeys: ["user_liked", "user_disliked"],
});

for await (const event of streamResponse) {
  if (event.event === "feedback") {
    // Example: { user_liked: ".../feedback/tokens/<id>", user_disliked: "..." }
    feedbackUrls = event.data;
    console.log("Feedback URLs:", feedbackUrls);
  } else if (event.event === "updates") {
    console.log(event.data);
  }
}

cURL

curl --request POST \
  --url "/threads//runs/stream" \
  --header "Content-Type: application/json" \
  --header "x-api-key: " \
  --data '{
    "assistant_id": "agent",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Tell me a joke about databases."
        }
      ]
    },
    "stream_mode": "updates",
    "feedback_keys": ["user_liked", "user_disliked"]
  }'

处理流式 feedback 事件

流会发出一个 feedback 事件,如下所示:

event: feedback
data: {"user_liked":"https://api.smith.langchain.com/api/v1/feedback/tokens/ef19fedf-dcac-4cbb-a59c-00661efd6425", "user_disliked": "https://api.smith.langchain.com/api/v1/feedback/tokens/e952734e-c0a0-417b-a04d-fc2209691ed5"}

data 中的每个键对应您在 feedback_keys中传递的值之一。每个值都是一个生成的 URL,您的客户端可调用该 URL 来提交该运行的反馈。

使用生成的 URL 提交反馈

当用户选择反馈选项时, POST 到相应的 URL。 GET 也支持。请参阅 LangSmith API 参考 了解更多详情。

例如,如果用户点击了差评按钮,调用 user_disliked URL:

POST

curl --request POST \
  --url "https://api.smith.langchain.com/api/v1/feedback/tokens/e952734e-c0a0-417b-a04d-fc2209691ed5" \
  --header "Content-Type: application/json" \
  --data '{
    "score": 1,
    "value": 0,
    "comment": "I didn't like this joke because it didn't make me laugh.",
    "correction": {},
    "metadata": {}
  }'

GET

metadata 不支持与 GET.

curl --request GET \
  --url "https://api.smith.langchain.com/api/v1/feedback/tokens/e952734e-c0a0-417b-a04d-fc2209691ed5?score=1&value=0&comment=I%20didn%27t%20like%20this%20joke%20because%20it%20didn%27t%20make%20me%20laugh.&correction=%7B%7D"

此请求成功后,LangSmith 使用键 user_disliked.

优化反馈数据模型

user_likeduser_disliked 键也可以建模为单个键,例如 user_score.

例如:

  • - 配合 key="user_score" 使用 score=1 用于 user_liked
  • - 配合 key="user_score" 使用 score=-1 用于 user_disliked

这可以简化分析,因为所有用户偏好信号都归类在一个反馈键下。

反馈数据模型是灵活的,应该根据您的使用场景来设计。例如,一些应用可能偏好单独的布尔型键(user_liked, user_disliked),而其他应用可能偏好单个数值评分(user_score)或包含多个反馈键的更丰富的评分标准。

在客户端 UI 中实现生产化

生产化的解决方案将通过您的前端暴露生成的反馈 URL,而不是手动调用它们。

高级实现示例:

  1. 从您的后端或前端创建运行。
  2. 捕获 feedback 对象并存储返回的 URL。
  3. Render feedback controls such as thumbs up/down buttons and feedback forms.
  4. 在提交反馈时, POST or GET 根据用户的反馈意图生成一个反馈 URL。
  5. 提交后,可选择禁用反馈控件并向用户显示确认信息。