Skip to content

トレーシング SDK（potato_trace）

軽量な potato_trace SDK で任意のエージェントを計装し、その実行を Potato に取り込んで評価します。関数を @traceable（同期・非同期どちらも）で修飾すると、ネストした実行も含めて記録され、Potato の取り込み webhook に送られます。OpenTelemetry からのエクスポートにも対応します。

potato_trace は、エージェントの実行を記録して Potato に送る軽量な SDK です。 Potato がランタイムの経路上に入るので、オフラインのダンプを取り込むだけでなく、実際の実行をその場で評価できます。依存は軽く（標準ライブラリと、送信時の requests のみ）、トップレベル・パッケージなので、import しても 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 呼び出しは実行ツリーを形成します。ルートが値を返すと、ツリー全体がバックグラウンド・スレッドで /api/traces/webhook に POST されます（トレーシングがエージェントをブロックしたり、クラッシュさせたりすることはありません）。potato_url が設定されていない場合、トレーシングは安全な no-op になります。

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)現在の実行に出力やトークン使用量を付与する
flush(timeout=30)未完了のバックグラウンド送信を待つ

OpenTelemetry との相互運用（任意）

スタックが OpenTelemetry のスパン（GenAI セマンティック規約）を出力しているなら、それをそのまま Potato にエクスポートできます。opentelemetry-sdk は任意の extra です。

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

記録されたトレースはアイテムになり、評価したり、自動化ルールで振り分けたり、データセットにキュレーションしたりできます。

関連項目