Skip to content

SDK di tracciamento (potato_trace)

Strumenta qualsiasi agente con l'SDK leggero potato_trace per catturarne le esecuzioni dentro Potato e valutarle. Decora le funzioni con @traceable (sincrone o asincrone) e le esecuzioni annidate vengono catturate e inviate al webhook di acquisizione di Potato, con esportazione opzionale verso OpenTelemetry.

potato_trace è un SDK leggero che cattura le esecuzioni del tuo agente e le invia a Potato per la valutazione. Potato si colloca nel percorso di esecuzione, quindi valuti esecuzioni reali mentre avvengono anziché limitarti a importare dump offline. Ha poche dipendenze (libreria standard più requests al momento dell'invio) ed è un pacchetto di primo livello, quindi importarlo non tira mai dentro un framework web.

Avvio rapido

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

Le chiamate @traceable annidate formano un albero di esecuzioni; quando la radice ritorna, l'intero albero viene inviato con una POST a /api/traces/webhook da un thread in background (il tracciamento non blocca né manda in crash il tuo agente). Se non è configurato nessun potato_url, il tracciamento non fa nulla e non fallisce.

API

SimboloScopo
configure(potato_url=, api_key=, project_name=)Imposta il client globale
@traceable / @traceable(run_type=, name=, tags=)Traccia una funzione (sincrona o asincrona); run_type: chain (predefinito), llm, tool, retriever
trace(name, run_type=...)Forma a gestore di contesto: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Allega gli output o l'uso di token all'esecuzione corrente
flush(timeout=30)Attende gli invii in background ancora in sospeso

Interoperabilità con OpenTelemetry (opzionale)

Se il tuo stack emette span OpenTelemetry (convenzioni semantiche GenAI), puoi esportarli direttamente verso Potato. opentelemetry-sdk è un extra opzionale:

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")))

Ricevere le tracce

Sul lato Potato, abilita l'acquisizione delle tracce affinché il webhook accetti le esecuzioni:

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

Le tracce catturate diventano elementi che puoi valutare, instradare con le regole di automazione o curare in dataset.

Correlati