Skip to content

SDK de tracing (potato_trace)

Instrumenta cualquier agente con el SDK ligero potato_trace para capturar sus ejecuciones en Potato y evaluarlas. Decora funciones con @traceable (síncronas o asíncronas) y las ejecuciones anidadas se capturan y se envían al webhook de ingesta de Potato, con exportación opcional a OpenTelemetry.

potato_trace es un SDK ligero que captura las ejecuciones de tu agente y las envía a Potato para evaluarlas. Potato se sitúa en la ruta de ejecución, así que evalúas ejecuciones reales según ocurren en lugar de importar solo volcados offline. Tiene pocas dependencias (la biblioteca estándar más requests en el momento del envío) y es un paquete de nivel superior, de modo que importarlo nunca arrastra un framework web.

Inicio rápido

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

Las llamadas anidadas con @traceable forman un árbol de ejecuciones; cuando la raíz retorna, el árbol completo se envía por POST a /api/traces/webhook desde un hilo en segundo plano (el tracing nunca bloquea ni tumba tu agente). Si no hay ninguna potato_url configurada, el tracing no hace nada y no falla.

API

SímboloPropósito
configure(potato_url=, api_key=, project_name=)Configurar el cliente global
@traceable / @traceable(run_type=, name=, tags=)Trazar una función (síncrona o asíncrona); run_type: chain (por defecto), llm, tool, retriever
trace(name, run_type=...)Forma de gestor de contexto: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Adjuntar salidas o uso de tokens a la ejecución actual
flush(timeout=30)Esperar a los envíos pendientes en segundo plano

Interoperabilidad con OpenTelemetry (opcional)

Si tu stack emite spans de OpenTelemetry (convenciones semánticas de GenAI), puedes exportarlos directamente a Potato. opentelemetry-sdk es un extra opcional:

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

Recibir las trazas

Del lado de Potato, activa la ingesta de trazas para que el webhook acepte las ejecuciones:

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

Las trazas capturadas se convierten en elementos que puedes evaluar, enrutar con reglas de automatización o curar en datasets.

Relacionado