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

捕獲到的軌跡會成為條目，你可以對它們做評估、用自動化規則路由，或整理進資料集。

相關內容