Skip to content

追踪 SDK（potato_trace）

用轻量的 potato_trace SDK 为任意智能体埋点，把它的运行记录捕获到 Potato 里做评估。用 @traceable 装饰函数（同步或异步），嵌套的运行会被一并捕获并发送到 Potato 的摄入 webhook，还可以选择导出 OpenTelemetry。

potato_trace 是一个轻量 SDK，负责捕获你的智能体运行记录并发送到 Potato 做评估。 Potato 位于运行时链路上，因此你评估的是正在发生的真实运行，而不只是导入离线数据。它依赖很少（标准库，加上发送时用到的 requests），并且是一个顶层包，导入它不会连带引入 Web 框架。

快速开始

python
import potato_trace
 
potato_trace.configure(
    potato_url="http://localhost:8000",   # or env POTATO_TRACE_URL
    api_key="",                            # or env POTATO_TRACE_API_KEY
    project_name="my-agent",
)
 
@potato_trace.traceable(run_type="tool")
def search(query):
    return run_search(query)
 
@potato_trace.traceable(run_type="llm")
def summarize(text):
    potato_trace.add_metadata(prompt_tokens=120, completion_tokens=40)
    return call_llm(text)
 
@potato_trace.traceable            # the outermost call is the trace root
def agent(task):
    return summarize(search(task))
 
agent("weather in NYC")
potato_trace.flush()               # ensure sends finish before a short script exits

嵌套的 @traceable 调用构成一棵运行树；根调用返回时，整棵树会在后台线程中 POST 到 /api/traces/webhook（追踪不会阻塞你的智能体，也不会让它崩溃）。如果没有配置 potato_url，追踪就是一个安全的空操作。

API

符号用途
configure(potato_url=, api_key=, project_name=)设置全局客户端
@traceable / @traceable(run_type=, name=, tags=)追踪一个函数（同步或异步）；run_type：chain（默认）、llm、tool、retriever
trace(name, run_type=...)上下文管理器写法：with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)把输出/token 用量附加到当前运行上
flush(timeout=30)等待后台待发送的数据发完

OpenTelemetry 互操作（可选）

如果你的技术栈会发出 OpenTelemetry span（GenAI 语义约定），可以把它们直接导出到 Potato。opentelemetry-sdk 是可选的额外依赖：

python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from potato_trace.otel_exporter import build_exporter
 
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(build_exporter(project_name="my-agent")))

接收轨迹

在 Potato 一侧启用轨迹摄入，webhook 才会接受这些运行记录：

yaml
trace_ingestion:
  enabled: true
  api_key: ""    # set a key in production; the SDK sends it as a Bearer token

捕获到的轨迹会成为条目，你可以对它们做评估、用自动化规则路由，或整理进数据集。

相关内容