Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Rastreio e Observabilidade

Aula 14 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Rastreio e Observabilidade
  2. Rastreio Integrado
  3. Nomear Rastreios
  4. Dividir um Fluxo de Trabalho em Passos
  5. Processadores de Rastreio Personalizados
  6. Exportação para Sistemas Externos
  7. Não Perca os Últimos Rastreios
  8. Desativar o Rastreio
  9. Métricas-Chave a Monitorizar
  10. Pontos-chave

Atualizado a 3 de novembro de 2026. Os processadores de rastreio liam anteriormente trace.start_time, trace.end_time e span.name, que não existem no SDK: um rastreio não tem marca temporal e uma secção (« span ») contém started_at, ended_at e span_data. O processador de exportação não implementava on_trace_start, um método abstrato: a sua instanciação gerava um TypeError. Os « rastreios aninhados » criavam um novo rastreio dentro de outro, o que o SDK assinala como um erro provável: os passos utilizam agora custom_span(). Novidades: flush_traces(), gestão de dados sensíveis e Retenção Zero de Dados. Código verificado com openai-agents 0.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 com custom_span() e use group_id para ligar rastreios de uma conversa
  • Um rastreio não tem marca temporal; uma secção tem started_at, ended_at e span_data.type
  • Um TracingProcessor implementa os seus seis métodos; add_trace_processor() adiciona, set_trace_processors() substitui
  • trace_include_sensitive_data=False exclui entradas e saídas; flush_traces() força o envio
  • Desative o rastreio em testes com set_tracing_disabled(True) ou RunConfig(tracing_disabled=True)