Skip to content

Tracing SDK (potato_trace)

Beliebige Agenten mit dem leichtgewichtigen SDK potato_trace instrumentieren, um ihre Läufe zur Evaluierung in Potato zu erfassen. Funktionen mit @traceable dekorieren (synchron oder asynchron); verschachtelte Läufe werden erfasst und an den Ingestion-Webhook von Potato gesendet, optional mit OpenTelemetry-Export.

potato_trace ist ein leichtgewichtiges SDK, das die Läufe eines Agenten erfasst und zur Evaluierung an Potato sendet. Potato liegt im Laufzeitpfad, sodass sich echte Läufe evaluieren lassen, während sie passieren, statt nur Offline-Dumps zu importieren. Es ist abhängigkeitsarm (Standardbibliothek plus requests beim Senden) und ein Top-Level-Paket, sein Import zieht also nie ein Web-Framework mit.

Schnellstart

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

Verschachtelte @traceable-Aufrufe bilden einen Lauf-Baum; sobald die Wurzel zurückkehrt, wird der gesamte Baum in einem Hintergrund-Thread per POST an /api/traces/webhook geschickt (das Tracing blockiert den Agenten nie und bringt ihn nie zum Absturz). Ist kein potato_url konfiguriert, ist das Tracing ein gefahrloser No-op.

API

SymbolZweck
configure(potato_url=, api_key=, project_name=)Den globalen Client setzen
@traceable / @traceable(run_type=, name=, tags=)Eine Funktion tracen (synchron oder asynchron); run_type: chain (Standard), llm, tool, retriever
trace(name, run_type=...)Form als Kontextmanager: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Ausgaben bzw. Token-Verbrauch an den aktuellen Lauf hängen
flush(timeout=30)Auf ausstehende Sendevorgänge im Hintergrund warten

OpenTelemetry-Interoperabilität (optional)

Wenn der eigene Stack OpenTelemetry-Spans ausgibt (GenAI Semantic Conventions), lassen sie sich direkt nach Potato exportieren. opentelemetry-sdk ist ein optionales 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")))

Die Traces empfangen

Auf der Potato-Seite die Trace-Aufnahme aktivieren, damit der Webhook die Läufe annimmt:

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

Erfasste Traces werden zu Elementen, die sich evaluieren, mit Automatisierungsregeln weiterleiten oder in Datensätze kuratieren lassen.

Verwandte Themen