Skip to content

SDK de tracing (potato_trace)

Instrumente qualquer agente com o SDK leve potato_trace para capturar suas execuções dentro do Potato e avaliá-las. Decore funções com @traceable (síncronas ou assíncronas) e as execuções aninhadas são capturadas e enviadas ao webhook de ingestão do Potato, com exportação opcional para OpenTelemetry.

O potato_trace é um SDK leve que captura as execuções do seu agente e as envia ao Potato para avaliação. O Potato fica no caminho de execução, então você avalia execuções reais conforme elas acontecem, em vez de apenas importar despejos offline. Ele tem poucas dependências (biblioteca padrão mais requests na hora do envio) e é um pacote de nível superior, então importá-lo nunca arrasta junto um framework web.

Início 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

As chamadas @traceable aninhadas formam uma árvore de execuções; quando a raiz retorna, a árvore inteira é enviada por POST para /api/traces/webhook em uma thread em segundo plano (o tracing nunca bloqueia nem derruba seu agente). Se nenhum potato_url estiver configurado, o tracing vira uma operação nula segura.

API

SímboloFinalidade
configure(potato_url=, api_key=, project_name=)Define o cliente global
@traceable / @traceable(run_type=, name=, tags=)Rastreia uma função (síncrona ou assíncrona); run_type: chain (padrão), llm, tool, retriever
trace(name, run_type=...)Forma de gerenciador de contexto: with trace("step"): ...
set_outputs({...}) / add_metadata(**kw)Anexa saídas / uso de tokens à execução atual
flush(timeout=30)Aguarda os envios pendentes em segundo plano

Interoperabilidade com OpenTelemetry (opcional)

Se a sua stack emite spans do OpenTelemetry (convenções semânticas de GenAI), exporte-os diretamente para o Potato. opentelemetry-sdk é um 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")))

Recebendo os rastros

Do lado do Potato, habilite a ingestão de rastros para que o webhook aceite as execuções:

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

Os rastros capturados viram itens que você pode avaliar, rotear com regras de automação ou curar em conjuntos de dados.

Relacionados