Rastreio e Observabilidade
Nesta página
Atualizado a 3 de novembro de 2026. Os processadores de rastreio liam anteriormente
trace.start_time,trace.end_timeespan.name, que não existem no SDK: um rastreio não tem marca temporal e uma secção (« span ») contémstarted_at,ended_atespan_data. O processador de exportação não implementavaon_trace_start, um método abstrato: a sua instanciação gerava umTypeError. Os « rastreios aninhados » criavam um novo rastreio dentro de outro, o que o SDK assinala como um erro provável: os passos utilizam agoracustom_span(). Novidades:flush_traces(), gestão de dados sensíveis e Retenção Zero de Dados. Código verificado comopenai-agents0.24.0. Fontes: Tracing (documentação do SDK) · openai-agents-python.
Rastreio e Observabilidade
Um agente em produção é uma caixa negra se não rastrear as suas ações. Quando um cliente se queixa de uma resposta absurda, não tem nem o pedido exato, nem as ferramentas chamadas, nem os valores que devolveram. O rastreio do SDK regista cada passo da execução: chamadas ao modelo, ferramentas utilizadas, transferências (« handoffs ») e barreiras de segurança (« guardrails »). Esta é a sua ferramenta principal para depurar, otimizar e auditar os seus agentes.
Rastreio Integrado
Boas notícias: não precisa de ativar nada. O SDK rastreia automaticamente cada execução e, por predefinição, envia os rastreios para o painel da OpenAI em platform.openai.com. O agente abaixo, escrito sem uma única instrução de rastreio, já produz um rastreio utilizável.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Searches for a product in the catalog."""
return f"Product found: {name}, price €29.99"
agent = Agent(
name="Shop Agent",
instructions="You help customers find products.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Every execution automatically creates a trace
result = Runner.run_sync(agent, "Search for the pro laptop")
Visite o painel para ver o rastreio completo: duração, tokens consumidos, ferramentas chamadas e a resposta final.
Nomear Rastreios
Após algumas centenas de execuções, o painel torna-se numa lista indiferenciada. Dê nomes significativos aos seus rastreios para os encontrar facilmente; um nome de jornada de negócio é melhor do que um ID técnico.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"I want to order 5 laptops for my team",
)
O nome do rastreio aparece no painel e facilita a filtragem.
Dividir um Fluxo de Trabalho em Passos
Para um fluxo de trabalho com múltiplas chamadas, abra um rastreio em torno de tudo e marque cada passo com custom_span(). Não aninhe um trace() dentro de outro: o SDK regista então o aviso Trace already exists. Creating a new trace, but this is probably a mistake. As secções (« spans »), no entanto, são concebidas para serem aninhadas: cada uma situa-se sob a secção atual.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("order-workflow", group_id=conversation_id):
with custom_span("step-1-understanding"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("step-2-processing"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("step-3-confirmation", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
No painel, o rastreio order-workflow mostra os três passos e, sob cada um, as secções automáticas de execução: agente, chamadas ao modelo, ferramentas. O group_id liga rastreios da mesma conversa, utilizando, por exemplo, o seu ID de tópico.
Por predefinição, o SDK envolve cada Runner.run() num rastreio chamado Agent workflow e, dentro dos rastreios, o agente, cada geração de modelo, cada chamada de função, barreiras de segurança e transferências. Para uma hierarquia mais compacta, a documentação sugere cortar as secções automáticas de tarefa e de turno:
from agents import RunConfig
result = await Runner.run(
agent,
"Hello",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Processadores de Rastreio Personalizados
O painel da OpenAI é conveniente, mas a sua equipa de operações provavelmente monitoriza todo o resto noutro local. Para enviar rastreios para o seu próprio sistema, escreva um processador: este recebe eventos de início e fim, tanto para o rastreio completo como para cada secção. Todos os seis métodos de TracingProcessor são abstratos: implemente-os todos, mesmo que vazios, ou a instanciação falhará.
Eis o que cada objeto expõe realmente: um rastreio tem um trace_id e um name, e o seu método export() também devolve group_id e metadata; não tem marca temporal. Uma secção tem span_id, trace_id, parent_id, started_at e ended_at (cadeias ISO 8601) e span_data, cujo atributo type é agent, generation, function, handoff, guardrail, custom, etc. A duração do rastreio é, portanto, medida no processador.
import time
from datetime import datetime
from typing import Any
from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor
class MyTraceProcessor(TracingProcessor):
def __init__(self) -> None:
self._starts: dict[str, float] = {}
def on_trace_start(self, trace: Trace) -> None:
self._starts[trace.trace_id] = time.monotonic()
print(f"[TRACE START] {trace.name} - {trace.trace_id}")
def on_trace_end(self, trace: Trace) -> None:
duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
print(f"[TRACE END] {trace.name} - duration: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN START] {span.span_data.type}")
def on_span_end(self, span: Span[Any]) -> None:
if span.started_at and span.ended_at:
duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
print(f" [SPAN END] {span.span_data.type} - {duration.total_seconds():.2f} s")
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
add_trace_processor(MyTraceProcessor())
add_trace_processor() adiciona o seu processador ao original: os rastreios continuam a ir para o painel da OpenAI. set_trace_processors() substitui os processadores predefinidos: nada vai mais para a OpenAI, a menos que volte a colocar o seu exportador na lista.
Exportação para Sistemas Externos
Para uma ferramenta de observabilidade, só precisa de reformatar as secções. O exemplo abaixo escreve uma linha JSON por secção terminada, um formato que a maioria dos coletores de registos sabe ingerir; span.export() já fornece um dicionário completo.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Writes each finished span as JSON, for a log collector."""
def on_trace_start(self, trace: Trace) -> None:
pass
def on_trace_end(self, trace: Trace) -> None:
logger.info(json.dumps(trace.export(), default=str))
def on_span_start(self, span: Span[Any]) -> None:
pass
def on_span_end(self, span: Span[Any]) -> None:
logger.info(json.dumps(span.export(), default=str))
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
Vigie o que exporta: por predefinição, as secções de geração contêm entradas e saídas do modelo, e as secções de função contêm argumentos e resultados das ferramentas. Para os excluir, passe RunConfig(trace_include_sensitive_data=False) ou defina a variável de ambiente OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Para integrações prontas a usar, a documentação do SDK lista muitas ferramentas de terceiros que fornecem o seu próprio processador.
Não Perca os Últimos Rastreios
O exportador predefinido envia rastreios em segundo plano, a cada poucos segundos. Num trabalhador que processa tarefas e não para, ou num script curto, chame flush_traces() após fechar o rastreio para forçar o envio:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Summarize today's tickets")
flush_traces() # after the trace ends, never in the middle
Desativar o Rastreio
Existe um caso em que o rastreio atrapalha mais do que ajuda: uma suíte de testes que executa centenas de agentes simulados e polui o seu painel. Em testes ou durante o desenvolvimento local, pode, portanto, desativá-lo, quer globalmente quer para uma única execução.
from agents import RunConfig, set_tracing_disabled
# Disable completely (or environment variable OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Or for a single execution
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))
Um último ponto, este de natureza contratual: segundo a documentação, o rastreio para a OpenAI não está disponível para organizações sujeitas a uma política de Retenção Zero de Dados. Neste caso, apenas o seu próprio processador, instalado com set_trace_processors(), lhe fornecerá rastreios.
Métricas-Chave a Monitorizar
Então, o que deve observar? Em produção, seis indicadores bastam para qualificar a saúde de um agente. A latência total — o tempo entre o pedido e a resposta final — é o que os seus utilizadores sentem; é mais frequentemente explicada pelo número de turnos, ou seja, o número de vezes que o ciclo do agente foi executado. Os tokens consumidos, tanto de entrada como de saída por execução, determinam a sua fatura.
Os outros três relacionam-se com a qualidade. A taxa de falha das ferramentas, a percentagem de ferramentas que devolvem um erro, revela uma API de terceiros instável ou argumentos mal gerados. A taxa de acionamento das barreiras de segurança, visível nas secções guardrail, mede a frequência dos bloqueios: um pico súbito sinaliza quer um ataque quer uma barreira de segurança que se tornou demasiado estrita. Por fim, a distribuição das transferências indica qual o agente que responde com mais frequência — e, portanto, se a sua triagem está a enviar os pedidos para onde devem ir.
Pontos-chave
- O SDK rastreia automaticamente cada execução para o painel da OpenAI (exceto para organizações sob Retenção Zero de Dados)
- Um
trace()por fluxo de trabalho; marque os passos comcustom_span()e usegroup_idpara ligar rastreios de uma conversa - Um rastreio não tem marca temporal; uma secção tem
started_at,ended_atespan_data.type - Um
TracingProcessorimplementa os seus seis métodos;add_trace_processor()adiciona,set_trace_processors()substitui trace_include_sensitive_data=Falseexclui entradas e saídas;flush_traces()força o envio- Desative o rastreio em testes com
set_tracing_disabled(True)ouRunConfig(tracing_disabled=True)