如何为 Agent Server 运行收集用户反馈

本教程向你展示如何为 Agent Server 运行收集用户反馈，并自动将它们关联到 LangSmith 中的追踪。创建运行时，将键包含在请求体的 feedback_keys 字段中。响应将为每个键返回一个预签名 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"
   }

3. 请求返回的 URL（例如 POST /api/v1/feedback/tokens/{token_id}），将反馈键与该 Agent Server 运行生成的追踪关联起来。更多详情请参阅 LangSmith API 参考。
4. LangSmith 使用所选的反馈键（例如 user_liked 或 user_disliked）将提交的反馈与该运行关联起来。

使用 feedback_keys 调用流式运行 API

创建一个运行，并从响应中解析 feedback 对象。

from langgraph_sdk import get_client

client = get_client(url="<DEPLOYMENT_URL>", api_key="<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)

处理流式传输的 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。也支持 GET。更多详情请参阅 LangSmith API 参考。

例如，如果用户点击了“踩”按钮，则调用 user_disliked URL：

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": {}
  }'

此请求成功后，LangSmith 会使用 user_disliked 键在该追踪上记录反馈。

优化反馈数据模型

user_liked 和 user_disliked 这两个键也可以建模为一个单一的键，例如 user_score。

例如：

• 对 user_liked 使用 key="user_score" 且 score=1
• 对 user_disliked 使用 key="user_score" 且 score=-1

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

反馈数据模型是灵活的，应针对你的用例进行设计。例如，某些应用可能更倾向于使用单独的布尔式键（user_liked、user_disliked），而其他应用可能更倾向于使用单一数值得分（user_score）或包含多个反馈键的更丰富的评分标准。

在客户端 UI 中实现产品化

产品化的解决方案会通过你的前端公开生成的反馈 URL，而不是手动调用它们。

高层次实现示例：

1. 从你的后端或前端创建运行。
2. 捕获 feedback 对象并存储返回的 URL。
3. 渲染反馈控件，例如点赞/点踩按钮和反馈表单。
4. 在提交反馈时，根据用户的反馈意图对反馈 URL 执行 POST 或 GET。
5. 可选地在提交后禁用反馈控件，并向用户显示确认信息。

---