Skip to content

SDK de traçage (potato_trace)

Instrumentez n'importe quel agent avec le SDK léger potato_trace pour capturer ses exécutions dans Potato et les évaluer. Décorez vos fonctions avec @traceable (synchrones ou asynchrones) : les exécutions imbriquées sont capturées et envoyées au webhook d'ingestion de Potato, avec export OpenTelemetry facultatif.

potato_trace est un SDK léger qui capture les exécutions de votre agent et les envoie à Potato pour évaluation. Potato se place sur le chemin d'exécution, ce qui vous permet d'évaluer de vraies exécutions au fil de l'eau au lieu d'importer seulement des vidages hors ligne. Il embarque peu de dépendances (la bibliothèque standard, plus requests au moment de l'envoi) et constitue un paquet de premier niveau, si bien que l'importer n'entraîne jamais de framework web.

Démarrage rapide

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

Les appels @traceable imbriqués forment un arbre d'exécutions ; lorsque la racine retourne, l'arbre entier part en POST vers /api/traces/webhook depuis un thread en arrière-plan (le traçage ne bloque jamais votre agent et ne le fait jamais planter). Si aucune potato_url n'est configurée, le traçage devient une opération neutre et sans risque.

API

SymboleRôle
configure(potato_url=, api_key=, project_name=)Définir le client global
@traceable / @traceable(run_type=, name=, tags=)Tracer une fonction (synchrone ou asynchrone) ; run_type : chain (par défaut), llm, tool, retriever
trace(name, run_type=...)Forme gestionnaire de contexte : with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Attacher des sorties ou l'usage de tokens à l'exécution en cours
flush(timeout=30)Attendre la fin des envois en arrière-plan encore en attente

Interopérabilité OpenTelemetry (facultatif)

Si votre stack émet des spans OpenTelemetry (conventions sémantiques GenAI), exportez-les directement vers Potato. opentelemetry-sdk est un extra facultatif :

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

Recevoir les traces

Du côté de Potato, activez l'ingestion de traces pour que le webhook accepte les exécutions :

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

Les traces capturées deviennent des éléments que vous pouvez évaluer, router avec des règles d'automatisation ou verser dans des jeux de données.

Pages liées