agent-observability

Observabilidade de Agentes

Registre as chamadas de LLM do seu agente uma vez, reproduza-as offline em menos de 1 ms, zero chamadas de API, zero custo.

---

Seu agente LangGraph falha após o passo 8. O LangSmith mostra o que quebrou. Para reproduzir: mais 8 chamadas de LLM. Mais 30 segundos. Mais $0,15 em custo de API. Se a falha foi causada por uma saída transitória do modelo, você não consegue reproduzi-la de forma alguma.

A Observabilidade de Agentes resolve isso. Registre uma vez. Reproduza offline em 0,93 ms. Zero chamadas de API. Zero custo.

Recording overhead:   0.011%   (0.090 ms added per LLM call)
Replay latency:       0.93 ms  mean (vs ~8,500 ms live on GPT-4o × 10 steps)
Replay fidelity:      100%     (response bytes byte-for-byte identical)
CI cost per replay:   $0

---

Instalação

pip install agent-observability-trace-cli
# or
uv add agent-observability-trace-cli

Suporte a LangGraph:

pip install agent-observability-trace-cli[langgraph]

Suporte a OpenAI Agents SDK:

pip install agent-observability-trace-cli[openai-agents]

Início rápido via CLI em 30 segundos

# Record a live run (your script just needs `import agent_trace` somewhere)
agent-trace run --name my_agent -- python my_agent.py

# List recorded runs
agent-trace list

# Replay offline: zero network, zero cost
agent-trace replay run_<id>

# Show the trace for a run
agent-trace show run_<id>

list, inspect, diff, replay e run suportam --json para saída analisável por máquina, então um agente orquestrador ou um job de CI pode chamar qualquer um deles da mesma forma que uma pessoa faria e analisar o resultado. (run --json imprime seu próprio status no stderr e a saída do processo filho no stdout, terminando com uma linha final de resumo JSON, já que a saída do próprio filho não pode ser estruturada.) show não tem modo --json próprio. Ele aceita --errors-only para filtrar sua saída para spans com falha. Veja a referência completa da CLI abaixo para as flags de cada subcomando.

Quer controle programático em vez da CLI? Use a API Python:

from agent_trace import tracer
import httpx

@tracer.instrument(record=True)
def fetch_data(query: str) -> dict:
    with tracer.span("http-call") as span:
        resp = httpx.get("https://httpbin.org/get", params={"q": query})
        span.set_attribute("http.status_code", resp.status_code)
        return resp.json()

result = fetch_data("hello")
# Trace and fixture saved to ~/.agent-trace/runs/run_<id>/

Reproduza offline, sem chamadas de API, sem tokens:

from agent_trace import replay

with replay("run_<id>") as ctx:
    result = fetch_data("hello")  # served from fixture, zero network
    print(result)                 # identical to the original run

[!TIP] Para armazenar a entrada para recuperação posterior na reprodução, chame ctx.fixture.set_metadata('input', query) dentro do contexto de gravação.

[!NOTE] Clientes síncronos e assíncronos: A Observabilidade de Agentes intercepta httpx.Client, httpx.AsyncClient e requests.Session — incluindo o cliente assíncrono usado por padrão no OpenAI Python SDK v1.x e no Anthropic SDK. O patch é instalado no momento do despacho da requisição, então também cobre clientes construídos antes do início da gravação/reprodução (por exemplo, uma instância de openai.AsyncOpenAI() no nível do módulo).

---

Servidor MCP

agent-observability inclui um servidor Model Context Protocol para que um agente de IA (Claude, Cursor ou qualquer cliente compatível com MCP) possa listar, inspecionar e reproduzir execuções gravadas diretamente, sem que um humano invoque a CLI manualmente.

Instale o extra:

pip install "agent-observability-trace-cli[mcp]"

Adicione-o à configuração do seu cliente MCP (para Claude Desktop, claude_desktop_config.json):

{
  "mcpServers": {
    "agent-observability": {
      "command": "uvx",
      "args": ["--from", "agent-observability-trace-cli", "agent-trace-mcp"]
    }
  }
}

O servidor expõe uma ferramenta, run, que executa a CLI agent-trace com o subcomando e argumentos fornecidos, além de --json, e retorna o resultado JSON analisado:

run(["list"])
run(["replay", "run_abc123def456"])

O transporte é stdio, então não há nada para hospedar: o cliente MCP inicia o servidor como um subprocesso local. Fonte: src/agent_trace/mcp_server.py.

---

Frameworks suportados

LangGraph · OpenAI Agents SDK · CrewAI · AutoGen · LlamaIndex · Haystack · Agno · PydanticAI · Google GenAI Além disso: qualquer httpx.Client, httpx.AsyncClient ou requests.Session — sem necessidade de framework.

---

Referência da CLI

agent-trace tem 7 subcomandos. Cada subcomando aceita -h/--help para o mesmo nível de detalhe mostrado aqui.

agent-trace version

Imprime a versão instalada e sai. Sem argumentos.

agent-trace list

Lista todas as execuções gravadas no diretório de rastreamento (~/.agent-trace/runs por padrão, ou $AGENT_TRACE_TRACE_DIR).

Flag	Padrão	Descrição
--json	desligado	Imprime JSON analisável por máquina em vez de uma tabela legível por humanos.

agent-trace show <run_id>

Imprime de forma legível o trace.json armazenado para uma execução.

Argumento	Obrigatório	Descrição
run_id	sim	ID da execução, ex.: run_abc123def456.

Flag	Padrão	Descrição
--errors-only	desligado	Imprime apenas spans com status ERROR, cada um com seu texto de exceção capturado.

show não tem modo --json. Ele imprime o rastreamento (colorido via rich quando instalado, json.dumps simples caso contrário), não um objeto de resumo estruturado.

agent-trace replay <run_id>

Entra no modo de reprodução para uma execução e imprime a árvore de spans resultante, além de timing de streaming, trocas de erros HTTP e os mesmos diagnósticos entre spans que show imprime (classificação de erros, spans de nós duplicados, tempestades de tentativas, spans atribuídos incorretamente, durabilidade de checkpoints, atualizações de zero tarefas).

Argumento	Obrigatório	Descrição
run_id	sim	ID da execução, ex.: run_abc123def456.
--json	não	Imprime um resumo JSON estruturado (caminho do fixture, contagens de spans/trocas, o rastreamento original) em vez da árvore de spans legível por humanos.

agent-trace inspect <run_id>

Sinaliza automaticamente formas conhecidas de requisição/resposta malformadas e anomalias entre spans para uma execução.

Argumento	Obrigatório	Descrição
run_id	sim	ID da execução, ex.: run_abc123def456.

Flag	Padrão	Descrição
--registered-tools	nenhum	Lista separada por vírgulas de nomes de ferramentas registradas. Habilita as verificações de correspondência difusa de nomes de chamadas de ferramentas, compostos com pontos, nome de ação ReAct não registrado e nome de chamada de ferramenta não registrado.
--configured-host	nenhum	Host do endpoint LLM configurado do framework. Habilita a verificação de incompatibilidade de host do endpoint.
--check-kwarg	nenhum	Caminho de kwarg com pontos (ex.: extra_body.chat_template_kwargs.thinking) esperado para estar presente no wire. Sinaliza requisições onde está ausente.
--diff-field	nenhum	Campo de resposta para verificar presença-no-wire-mas-ausente-no-downstream: uma chave de nível superior (ex.: usage) ou um caminho com pontos/segmentos numéricos de índice de lista (ex.: choices.0.message.reasoning_content, para campos de provedores como o reasoning_content da DeepSeek).
--diff-get-post-field	nenhum	Caminho de campo com pontos (ex.: instructions) para comparar entre uma resposta GET anterior e um corpo de requisição POST posterior, causalmente relacionado, referenciando o mesmo ID de recurso (veja issue #2620). Sinaliza incompatibilidades de valores obsoletos, como um POST GPTAssistantAgent /runs ainda enviando instructions que não correspondem mais ao que o GET /assistants/{id} retorna.
--diff-get-post-id-field	id	Nome do campo que a resposta GET usa para o ID do recurso.
--diff-get-post-post-id-field	igual a --diff-get-post-id-field	Nome do campo que o corpo da requisição POST usa para referenciar o mesmo ID de recurso, se diferente (ex.: assistant_id).
--json	desligado	Imprime JSON analisável por máquina em vez de listas de sinalizações legíveis por humanos.

agent-trace diff <run_id_a> <run_id_b>

Compara as trocas de duas execuções gravadas, correspondidas por URL, destacando diferenças no nível de campo entre corpos de requisição/resposta, além de uma verificação de reinício-vs-retomada para um thread_id LangGraph compartilhado (veja issue #161).

Argumento	Obrigatório	Descrição
run_id_a	sim	Primeiro ID da execução.
run_id_b	sim	Segundo ID da execução.

Flag	Padrão	Descrição
--json	desligado	Imprime JSON analisável por máquina em vez de um diff legível por humanos.

agent-trace run -- <command> [args...]

Executa um processo filho com gravação pré-habilitada em todo o processo (AGENT_TRACE_AUTO_RECORD=1), para que o primeiro import agent_trace dentro desse processo, mesmo que pertencente a uma CLI de terceiros como langgraph dev, comece a gravar sem exigir nenhuma mudança de código no seu próprio código de agente. Sai com o código de saída do próprio processo filho.

Flag	Padrão	Descrição
--run-id	aleatório (run_<12-hex-chars>), impresso no início	ID de execução explícito.
--name	auto-record	Nome do rastreamento gravado nos metadados de trace.json.
--json	desligado	Imprime o status do agent-trace como uma linha final JSON no stdout (linhas de status vão para o stderr). Deve vir antes do comando filho, ex.: agent-trace run --json -- langgraph dev.
child_command (posicional)	nenhum	Tudo após -- é executado como o processo filho, ex.: -- langgraph dev. Isso captura o restante da linha de comando, então --run-id/--name/--json devem ser fornecidos antes dele, não depois.

---

O problema

Uma execução LangGraph falha após o passo 8. Seu rastreamento no LangSmith ou Langfuse mostra o que quebrou. Mas para reproduzir, você precisa reexecutar o agente inteiro: mais 8 chamadas de LLM, mais 30 segundos, mais $0,15 em custo de API. Se a falha foi causada por uma resposta específica de ferramenta ou uma saída transitória do modelo, você não consegue reproduzi-la de forma alguma. Você está depurando contra um alvo em movimento.

A Observabilidade de Agentes resolve isso na camada de transporte HTTP. Ela registra cada requisição e resposta verbatim em um arquivo SQLite local. A reprodução serve esses bytes exatos de volta em sequência, em menos de 1 ms por troca: mesmo caminho de código, mesma árvore de spans, mesma falha. Sem chamadas de API.

---

Uso em CI: reprodução a custo zero

Registre uma vez. Faça commit do fixture. Reproduza em cada execução de CI a custo zero de API:

# tests/test_agent.py
import pytest
from pathlib import Path
from agent_trace import replay

FIXTURE_PATH = Path("fixtures/my_agent_run.db")

@pytest.mark.skipif(
    not FIXTURE_PATH.exists(),
    reason="Run: python scripts/record_fixture.py to generate the fixture"
)
def test_agent_answer():
    with replay(FIXTURE_PATH) as ctx:
        from my_module import my_agent
        result = my_agent("what is 2+2?")
    assert "4" in result

Defina AGENT_TRACE_NETWORK_GUARD=1 no CI. Qualquer chamada HTTP que não esteja no fixture levanta NetworkGuardError imediatamente, capturando regressões antes que cheguem à produção.

AGENT_TRACE_NETWORK_GUARD=1 uv run pytest tests/

O que isso economiza para você?

10-step agent × $0.15 per run × 10 debug sessions per week = $15/week in API costs
With Agent Observability CI replay: $0/week

At scale (10 engineers, each debugging 3 failures/week):
Before: ~$45/week, ~5 hours/week waiting for live re-runs
After: $0/week, 0.93 ms per replay

---

Por que não usar apenas LangSmith, Langfuse ou Helicone?

Resposta curta: eles mostram o que aconteceu. Não conseguem reproduzir offline. Os cassetes VCR do LangSmith são apenas Python + LangChain, não capturam bytes completos do wire, e exigem uma conta LangSmith. A Observabilidade de Agentes funciona em qualquer cliente HTTP Python, não precisa de conta e reproduz em 0,93 ms com 100% de fidelidade.

A maioria das ferramentas de observabilidade para agentes LLM são apenas de observação: elas mostram um rastreamento do que aconteceu, mas reproduzir uma falha ainda exige reexecutar o agente completo contra APIs ao vivo.

Capacidade	Observabilidade de Agentes	LangSmith	Langfuse	Helicone	OpenLLMetry
Reprodução offline a partir de fixture local	Sim	Parcial ¹	Não	Não	Não
Funciona com qualquer cliente HTTP	Sim	Não	Não	Não	Não
Reprodução em CI sem chaves de API	Sim	Parcial ¹	Não	Não	Não
Timing determinístico de spans na reprodução	Sim	Não	Não	Não	Não
Captura bytes brutos de requisição/resposta HTTP	Sim	Não	Não	Sim	Não
Rastreamento no nível de span	Sim	Sim	Sim	Sim	Sim
Exportação OTLP (Jaeger, Grafana Tempo)	Sim	Não	Sim	Não	Sim
Núcleo de código aberto	Sim	Não	Sim	Não	Sim
Apenas local, sem servidor necessário	Sim	Não	Self-host	Não	Self-host

¹ LangSmith tem LANGSMITH_TEST_CACHE / cassetes VCR (langsmith[vcr]) apenas para Python + LangChain. Ele captura HTTP para api.openai.com, mas não clientes HTTP arbitrários, não registra bytes completos no nível do wire e exige uma conta LangSmith.

Escolha LangSmith se sua equipe está no LangChain e precisa de gerenciamento de datasets, versionamento de prompts e loops de feedback humano.

Escolha Langfuse se você quer uma stack de observabilidade totalmente open-source e auto-hospedável, com armazenamento robusto baseado em Postgres.

Escolha OpenLLMetry se sua equipe já usa OpenTelemetry e quer spans padrão de gen_ai.* sem adicionar um novo sistema de observabilidade.

Observabilidade de Agentes não substitui dashboards e pipelines de avaliação. Ela resolve o problema upstream específico: reproduzir uma execução falha específica sem nenhum custo de API LLM, para qualquer agente construído em qualquer cliente HTTP Python.

---

Experimente com Docker

A Observabilidade de Agentes emite spans OTLP. Execute uma stack de observabilidade local para navegar pelas árvores de rastreamento:

git clone https://github.com/RudrenduPaul/agent-observability
cd agent-observability
docker compose up -d

Inicia três serviços (todos opcionais):

• Jaeger (http://localhost:16686): ingestão de spans OTLP e UI de rastreamento
• Grafana (http://localhost:3000): dashboards e alertas
• Tempo (porta 3200): backend de armazenamento de rastreamento de longo prazo

Depois aponte seu exporter para o coletor:

from agent_trace.exporters.otlp import OTLPExporter

# 4317 = OTLP gRPC ingestion endpoint
exporter = OTLPExporter(endpoint="http://localhost:4317")
exporter.export(trace)

---

Falhas reais que o registro/reprodução captura

• A saída transitória do modelo na etapa 6 faz uma ferramenta downstream falhar. Irreproduzível com uma nova execução, trivial de reproduzir.
• A resposta de limite de taxa na etapa 3 aciona um caminho de fallback silencioso, visível apenas nos bytes do fixture gravado, não em uma nova execução ao vivo.
• Erro de serialização do esquema da ferramenta antes do despacho HTTP, capturado por LangGraphTracer.on_llm_error mesmo que nunca alcance o interceptor (consulte Limitações conhecidas).
• Ordenação não determinística de ferramentas em um ramo paralelo: a reprodução fixa a sequência exata que produziu a falha, então você está depurando a execução real em vez de uma nova.
• Resposta gRPC unary-stream do Gemini que só falha em um limite de chunk específico, gravada uma vez e reproduzida byte a byte em vez de acionar novamente uma chamada de streaming ao vivo a cada vez.

---

Limitações conhecidas

O modelo de captura do Agent Observability é baseado em interceptor HTTP (mais callbacks de framework instrumentados para as integrações sob src/agent_trace/integrations/) e local ao processo. Esse modelo tem arestas reais, declaradas explicitamente aqui para que fiquem claras antes de você encontrar uma, não depois:

• Somente local ao processo. A gravação/reprodução acontece dentro do processo Python no qual você importa agent_trace (httpx.Client(transport= RecordingTransport(...)), session.mount(..., RecordingAdapter(...)), ou os monkeypatches de ReplayEngine.replay(), consulte src/agent_trace/interceptor/). Ele não pode observar ou reproduzir chamadas feitas por um serviço hospedado de terceiros que você não executa ou implanta você mesmo (por exemplo, o assistente de chat hospedado de um fornecedor). Ele só vê as chamadas de saída do seu próprio processo.

• A cobertura gRPC é parcial. src/agent_trace/interceptor/grpc_hook.py aplica patches em grpc.secure_channel/grpc.insecure_channel (e nos equivalentes grpc.aio) para capturar tráfego Gemini/Vertex AI que ignora httpx completamente. Chamadas unary-unary (por exemplo, GenerateContent) e chamadas síncronas unary-stream (por exemplo, StreamGenerateContent) são totalmente gravadas e reproduzidas. Chamadas gRPC client-streaming e bidirecional-streaming, e qualquer chamada de streaming grpc.aio, não são capturadas. Essas vão direto para a rede ao vivo sem interceptação, tanto durante a gravação quanto (se tentado) na reprodução.

• A captura começa quando um objeto de requisição existe. RecordingTransport. handle_request/AsyncRecordingTransport.handle_async_request (httpx_hook.py) e RecordingAdapter.send (requests_patch.py) só são executados quando um httpx.Request/PreparedRequest totalmente construído os alcança. Qualquer exceção levantada antes disso, enquanto um SDK está serializando um esquema de ferramenta, construindo cabeçalhos ou montando a chamada, ou até mesmo antes durante a construção de objetos Python simples (por exemplo, TypeError de abc.ABCMeta ao instanciar uma classe abstrata incorretamente), acontece inteiramente a montante da superfície de captura do interceptor e produz zero linhas de fixture. O callback de erro próprio de uma integração de framework conectada (por exemplo, LangGraphTracer.on_llm_error) ainda captura tais exceções pré-HTTP quando elas se propagam pelo próprio try/except do framework, então "invisível para o interceptor" não é o mesmo que "invisível em todos os lugares". Depende se uma integração de framework está conectada para a exceção passar por ela.

• Sem visibilidade no código de print/display do próprio framework. Exceções levantadas dentro da maquinaria local de logging/printing/display, por exemplo, saída de Console rich ou hooks de display IPython/Jupyter, acionadas pelo próprio logging verbose=True de um framework, têm zero tráfego HTTP e zero superfície de callback de framework. Nenhum mecanismo de captura existente ou planejado (interceptor HTTP, hook de transporte stdio MCP ou qualquer integração de framework) observa essa categoria de falha.

---

Segurança

• Cadeia de suprimentos: Os lançamentos são construídos e publicados via GitHub Actions (release.yml). A proveniência SLSA Nível 2 via assinatura OIDC Sigstore é verificada como funcional (.sigstore.json bundles genuinamente produzidos para cada artefato dist); o SBOM (CycloneDX JSON + XML) é gerado e anexado ao GitHub Release junto com os artefatos assinados.
• Varredura de vulnerabilidades: dependabot.yml abre PRs semanais de atualização de versão do pip e mensais do GitHub Actions. Alertas de aviso de segurança do Dependabot, varredura de segredos e proteção de push de varredura de segredos estão todos habilitados neste repositório.
• Segurança do fixture: Arquivos de fixture em ~/.agent-trace/runs/ contêm corpos completos de requisições e respostas HTTP, incluindo chaves de API e conteúdos de prompts. Adicione .agent-trace/ e *.db ao seu .gitignore.
• Divulgação: SECURITY.md — relate vulnerabilidades para agent.obs.oss.security@gmail.com com um SLA de resposta de 48 horas.

[!WARNING] Nunca faça commit de um fixture gerado contra uma chave de API de produção. Arquivos de fixture capturam corpos completos de requisição/resposta literalmente, então um fixture commitado pode vazar chaves de API reais e conteúdos de prompts para o seu histórico do git.

Avisos upstream conhecidos

• chromadb (extra opcional [crewai] apenas): GHSA para uma vulnerabilidade de injeção de código pré-autenticação que afeta chromadb 1.0.0 até o lançamento mais recente atual (1.5.9). A correção upstream (chroma-core/chroma PR #7237) foi mesclada em 2026-07-07, mas não foi lançada em nenhuma versão PyPI desde então — atualmente não há versão corrigida para fixar. chromadb é puxado apenas pelo extra de integração opcional crewai (pip install agent-observability-trace-cli[crewai]), não instalado por padrão, e este projeto nunca executa um servidor Chroma com uma API HTTP exposta, então o caminho real de exploração (um endpoint /api/v2/.../collections alcançável por atacante) não se aplica ao uso normal deste pacote. Se você instalar o extra [crewai] e executar seu próprio servidor Chroma em outro lugar, acompanhe o aviso upstream e atualize chromadb assim que uma versão corrigida for lançada.

  Roteiro futuro: assim que o chromadb lançar uma versão contendo a correção, fixe chromadb nessa versão imediatamente. Se nenhuma correção for lançada até a próxima revisão de segurança agendada e o extra [crewai] vir uso real insignificante, remover o extra completamente é o fallback em consideração para encerrar isso de vez.

---

FAQ

O que é o Agent Observability e como ele é diferente de uma ferramenta típica de rastreamento de LLM?

É uma biblioteca Python e CLI (agent-trace) que grava cada requisição e resposta HTTP que seu agente faz, literalmente, em um fixture SQLite local, e depois reproduz esses bytes exatos mais tarde sem chamada de rede. A maioria das ferramentas de rastreamento, incluindo LangSmith, Langfuse, Helicone e OpenLLMetry, mostram o que aconteceu durante uma execução. O Agent Observability adicionalmente permite que você reproduza essa execução exata offline, deterministicamente, sem tocar na API ao vivo. Consulte "Por que não usar apenas LangSmith, Langfuse ou Helicone?" acima para a análise completa de capacidades contra essas quatro ferramentas.

Como a gravação/reprodução determinística realmente funciona?

A gravação aplica patches em httpx.Client, httpx.AsyncClient e requests.Session na camada de transporte (src/agent_trace/interceptor/) para capturar cada requisição e resposta de saída como bytes brutos em fixture.db. A reprodução instala um FixtureClock (src/agent_trace/core/clock.py) e serve esses mesmos bytes de volta na sequência original, então o caminho de código, a árvore de spans e os timestamps correspondem todos à gravação original. Os números de benchmark citados acima (0,011% de overhead de gravação, 0,93ms de latência média de reprodução, 100% de fidelidade) vêm de benchmarks/test_overhead.py, benchmarks/test_replay_vs_live.py e benchmarks/test_fidelity.py neste repositório, executáveis por você mesmo com uv run pytest benchmarks/.

Como eu instalo e quais plataformas são suportadas?

pip install agent-observability-trace-cli, ou uv add agent-observability-trace-cli. Requer Python 3.10 ou mais recente e depende apenas de httpx e rich, sem extensões compiladas, então instala em qualquer lugar onde essas wheels existam. CI (.github/workflows/ci.yml) passa no Ubuntu, macOS e Windows, em Python 3.10 a 3.13. Um wrapper npm, agent-observability-trace-cli (código-fonte sob npm/ neste repositório), também é publicado para equipes que usam npx/npm, mas ele ainda chama o CLI Python internamente, então o pacote Python também deve ser instalado.

Como isso se compara especificamente ao LangSmith?

O LANGSMITH_TEST_CACHE do LangSmith (cassetes estilo VCR, via langsmith[vcr]) é o equivalente integrado mais próximo. É Python mais LangChain apenas, captura chamadas HTTP para api.openai.com em vez de qualquer cliente HTTP, não grava bytes completos no nível de fio e requer uma conta LangSmith. O Agent Observability funciona com qualquer cliente HTTP Python, além de interceptadores dedicados para tráfego gRPC, aiohttp, botocore e WebSocket, grava bytes completos de requisição e resposta localmente e não precisa de conta ou serviço hospedado. Escolha LangSmith se você já está no LangChain e quer gerenciamento de datasets, versionamento de prompts e loops de feedback humano junto com o rastreamento. Escolha Agent Observability se o objetivo é reproduzir uma execução falha específica a custo zero de API, independentemente de qual SDK fez a chamada.

O que acontece se a reprodução não encontrar uma entrada de fixture correspondente?

Com AGENT_TRACE_NETWORK_GUARD=1 definido, qualquer requisição ausente do fixture levanta NetworkGuardError imediatamente em vez de cair silenciosamente para uma chamada ao vivo. A causa mais comum é um cliente HTTP construído antes do contexto de gravação ou reprodução ser iniciado, já que o patch só se aplica a clientes criados dentro do bloco start_trace/replay. Consulte "Limitações conhecidas" acima para a lista completa de arestas, incluindo cobertura parcial de streaming gRPC e exceções pré-HTTP que nunca alcançam o interceptor.

Ele captura agentes construídos em frameworks não-Python?

Não. A captura é um interceptor de transporte HTTP Python mais callbacks instrumentados para as integrações sob src/agent_trace/integrations/ (LangGraph, CrewAI, AutoGen, LlamaIndex, Haystack, Agno, PydanticAI, Google GenAI e outros). Ele só vê tráfego do seu próprio processo Python. Agentes construídos em outras linguagens, ou chamadas feitas por um serviço hospedado de terceiros que você não executa, estão fora da sua superfície de captura.

Os arquivos de fixture são seguros para commit no controle de versão?

Não por padrão. fixture.db contém corpos completos de requisições e respostas HTTP, o que significa chaves de API e conteúdos de prompts sempre que aparecem em cabeçalhos ou payloads. Adicione .agent-trace/ e *.db ao .gitignore, e nunca faça commit de um fixture gravado contra uma chave de API de produção. Remova ou redija segredos primeiro se quiser manter um fixture como um ativo de teste de CI commitado.

Isso é gratuito para uso comercial?

Sim. O projeto é licenciado sob Apache 2.0 (consulte LICENSE), que permite uso comercial, modificação e redistribuição, incluindo dentro de produtos de código fechado, sujeito aos termos de atribuição e aviso da própria licença. Não há nível pago separado ou licença comercial.

---

Contribuindo

• Leia CONTRIBUTING.md antes de abrir um PR
• Boas primeiras issues são rotuladas em GitHub Issues
• O mecanismo de reprodução (src/agent_trace/_replay/) requer 80% de cobertura de teste (crítico para correção)
• O interceptor (src/agent_trace/interceptor/) requer 80% de cobertura de teste
• GitHub Discussions para perguntas de design e ideias

Apache 2.0. Contribuições são bem-vindas.

---

Construído por Rudrendu Paul e Sourav Nandy