agent-observability

Agent Observability

Registra las llamadas LLM de tu agente una vez, reprodúcelas sin conexión en menos de 1 ms, cero llamadas API, cero coste.

---

Tu agente LangGraph falla después del paso 8. LangSmith te muestra qué se rompió. Para reproducirlo: 8 llamadas LLM más. 30 segundos más. 0,15 $ más en coste de API. Si el fallo fue causado por una salida transitoria del modelo, no puedes reproducirlo en absoluto.

Agent Observability soluciona esto. Registra una vez. Reproduce sin conexión en 0,93 ms. Cero llamadas API. Cero coste.

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

---

Instalación

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

Soporte de LangGraph:

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

Soporte de OpenAI Agents SDK:

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

Inicio rápido de CLI en 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 y run admiten todos --json para salida analizable por máquina — un agente orquestador o un trabajo de CI puede llamar a cualquiera de ellos de la misma manera que lo haría una persona y analizar el resultado. (run --json imprime su propio estado en stderr y la salida del proceso hijo en stdout, terminando con una línea final de resumen JSON, ya que la salida del propio hijo no puede estructurarse.) show no tiene modo --json propio — acepta --errors-only para filtrar su salida a spans fallidos en su lugar. Consulta la referencia de CLI completa a continuación para ver las banderas de cada subcomando.

¿Quieres control programático en lugar de la CLI? Usa la API de 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>/

Reproduce sin conexión — sin llamadas API, sin 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 almacenar la entrada para su posterior recuperación en la reproducción, llama a ctx.fixture.set_metadata('input', query) dentro del contexto de grabación.

[!NOTE] Clientes síncronos y asíncronos: Agent Observability intercepta httpx.Client, httpx.AsyncClient y requests.Session — incluido el cliente asíncrono usado por defecto en el SDK de Python de OpenAI v1.x y el SDK de Anthropic. El parche se instala en el momento del envío de la solicitud, por lo que también cubre clientes construidos antes de que comience la grabación/reproducción (p. ej. una instancia de openai.AsyncOpenAI() a nivel de módulo).

---

Servidor MCP

agent-observability incluye un servidor de Model Context Protocol para que un agente de IA (Claude, Cursor o cualquier cliente compatible con MCP) pueda listar, inspeccionar y reproducir ejecuciones grabadas directamente, sin que un humano invoque la CLI manualmente.

Instala el extra:

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

Añádelo a la configuración de tu cliente MCP (para Claude Desktop, claude_desktop_config.json):

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

El servidor expone una herramienta, run, que ejecuta la CLI de agent-trace con el subcomando y los argumentos dados más --json, y devuelve el resultado JSON analizado:

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

El transporte es stdio, por lo que no hay nada que alojar: el cliente MCP lanza el servidor como un subproceso local. Fuente: src/agent_trace/mcp_server.py.

---

Frameworks compatibles

LangGraph · OpenAI Agents SDK · CrewAI · AutoGen · LlamaIndex · Haystack · Agno · PydanticAI · Google GenAI Además: cualquier httpx.Client, httpx.AsyncClient o requests.Session — sin necesidad de framework.

---

Referencia de CLI

agent-trace tiene 7 subcomandos. Cada subcomando acepta -h/--help para el mismo detalle mostrado aquí.

agent-trace version

Imprime la versión instalada y sale. Sin argumentos.

agent-trace list

Lista todas las ejecuciones grabadas en el directorio de trazas (~/.agent-trace/runs por defecto, o $AGENT_TRACE_TRACE_DIR).

Bandera	Por defecto	Descripción
--json	off	Imprime JSON legible por máquina en lugar de una tabla legible por humanos.

agent-trace show <run_id>

Imprime de forma legible el trace.json almacenado para una ejecución.

Argumento	Obligatorio	Descripción
run_id	sí	ID de ejecución, p. ej. run_abc123def456.

Bandera	Por defecto	Descripción
--errors-only	off	Imprime solo los spans con estado ERROR, cada uno con su texto de excepción capturado.

show no tiene modo --json — imprime la traza (coloreada mediante rich cuando está instalado, json.dumps simple en caso contrario), no un objeto de resumen estructurado.

agent-trace replay <run_id>

Entra en modo de reproducción para una ejecución e imprime el árbol de spans resultante, además del tiempo de streaming, los intercambios de errores HTTP y los mismos diagnósticos entre spans que imprime show (clasificación de errores, spans de nodos duplicados, tormentas de reintentos, spans mal atribuidos, durabilidad de checkpoints, actualizaciones de tareas cero).

Argumento	Obligatorio	Descripción
run_id	sí	ID de ejecución, p. ej. run_abc123def456.
--json	no	Imprime un resumen JSON estructurado (ruta del fixture, recuentos de spans/intercambios, la traza original) en lugar del árbol de spans legible por humanos.

Sin banderas.

agent-trace inspect <run_id>

Marca automáticamente formas de solicitud/respuesta malformadas conocidas y anomalías entre spans para una ejecución.

Argumento	Obligatorio	Descripción
run_id	sí	ID de ejecución, p. ej. run_abc123def456.

Bandera	Por defecto	Descripción
--registered-tools	ninguno	Lista separada por comas de nombres de herramientas registradas. Activa las comprobaciones de coincidencia difusa de nombres de llamadas a herramientas, compuestos con puntos, nombre de acción ReAct no registrado y nombre de llamada a herramienta no registrado.
--configured-host	ninguno	El host del endpoint LLM configurado del framework. Activa la comprobación de discrepancia de host de endpoint.
--check-kwarg	ninguno	Ruta de kwarg con puntos (p. ej. extra_body.chat_template_kwargs.thinking) que se espera que esté presente en el cable. Marca las solicitudes donde está ausente.
--diff-field	ninguno	Campo de respuesta para comprobar presencia-en-cable-pero-ausente-aguas-abajo — una clave de nivel superior (p. ej. usage) o una ruta con puntos/anidada con segmentos de índice de lista numéricos (p. ej. choices.0.message.reasoning_content, para campos de proveedor como reasoning_content de DeepSeek).
--diff-get-post-field	ninguno	Ruta de campo con puntos (p. ej. instructions) para comparar entre una respuesta GET anterior y un cuerpo de solicitud POST posterior relacionado causalmente que hace referencia al mismo id de recurso (ver issue #2620). Marca discrepancias de valores obsoletos, como un POST /runs de GPTAssistantAgent que aún envía instructions que ya no coinciden con lo que devuelve GET /assistants/{id}.
--diff-get-post-id-field	id	Nombre del campo que la respuesta GET usa para el id del recurso.
--diff-get-post-post-id-field	igual que --diff-get-post-id-field	Nombre del campo que el cuerpo de la solicitud POST usa para hacer referencia al mismo id de recurso, si es diferente (p. ej. assistant_id).
--json	off	Imprime JSON legible por máquina en lugar de listas de banderas legibles por humanos.

agent-trace diff <run_id_a> <run_id_b>

Compara los intercambios de dos ejecuciones grabadas, emparejados por URL, resaltando las diferencias a nivel de campo entre los cuerpos de solicitud/respuesta, además de una comprobación de reinicio-vs-reanudación para un thread_id de LangGraph compartido (ver issue #161).

Argumento	Obligatorio	Descripción
run_id_a	sí	ID de la primera ejecución.
run_id_b	sí	ID de la segunda ejecución.

Bandera	Por defecto	Descripción
--json	off	Imprime JSON legible por máquina en lugar de un diff legible por humanos.

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

Ejecuta un proceso hijo con la grabación preactivada en todo el proceso (AGENT_TRACE_AUTO_RECORD=1), de modo que el primer import agent_trace dentro de ese proceso — incluso uno propiedad de una CLI de terceros como langgraph dev — comienza a grabar sin necesidad de cambios de código en tu propio código de agente. Sale con el código de salida del propio proceso hijo.

Bandera	Por defecto	Descripción
--run-id	aleatorio (run_<12-hex-chars>), impreso al inicio	ID de ejecución explícito.
--name	auto-record	Nombre de traza registrado en los metadatos de trace.json.
--json	off	Imprime el estado propio de agent-trace como una línea JSON final en stdout (las líneas de estado van a stderr en su lugar). Debe ir antes del comando hijo, p. ej. agent-trace run --json -- langgraph dev.
child_command (posicional)	—	Todo lo que va después de -- se ejecuta como proceso hijo, p. ej. -- langgraph dev. Esto captura el resto de la línea de comandos, por lo que --run-id/--name/--json deben indicarse antes, no después.

---

El problema

Una ejecución de LangGraph falla después del paso 8. Tu traza en LangSmith o Langfuse muestra qué se rompió. Pero para reproducirlo tienes que volver a ejecutar el agente completo: 8 llamadas LLM más, 30 segundos más, otros 0,15 $ en coste de API. Si el fallo fue causado por una respuesta específica de una herramienta o una salida transitoria del modelo, no puedes reproducirlo en absoluto. Estás depurando contra un objetivo en movimiento.

Agent Observability resuelve esto en la capa de transporte HTTP. Graba cada solicitud y respuesta textualmente en un archivo SQLite local. La reproducción devuelve esos bytes exactos en secuencia, en menos de 1 ms por intercambio: misma ruta de código, mismo árbol de spans, mismo fallo. Sin llamadas API.

---

Uso en CI: reproducción a coste cero

Graba una vez. Haz commit del fixture. Reproduce en cada ejecución de CI a coste cero 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

Establece AGENT_TRACE_NETWORK_GUARD=1 en CI. Cualquier llamada HTTP que no esté en el fixture lanza NetworkGuardError inmediatamente — detectando regresiones antes de que lleguen a producción.

AGENT_TRACE_NETWORK_GUARD=1 uv run pytest tests/

¿Qué te ahorra esto?

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 qué no usar simplemente LangSmith, Langfuse o Helicone?

Respuesta corta: te muestran lo que pasó. No pueden reproducirlo sin conexión. Los cassettes VCR de LangSmith son solo para Python + LangChain, no capturan los bytes completos del cable y requieren una cuenta de LangSmith. Agent Observability funciona con cualquier cliente HTTP de Python, no necesita cuenta y reproduce en 0,93 ms con fidelidad del 100%.

La mayoría de las herramientas de observabilidad para agentes LLM son solo observación — te muestran una traza de lo que pasó, pero reproducir un fallo aún requiere volver a ejecutar el agente completo contra APIs en vivo.

Capacidad	Agent Observability	LangSmith	Langfuse	Helicone	OpenLLMetry
Reproducción sin conexión desde fixture local	Sí	Parcial ¹	No	No	No
Funciona con cualquier cliente HTTP	Sí	No	No	No	No
Reproducción en CI sin claves API	Sí	Parcial ¹	No	No	No
Tiempo de span determinista en la reproducción	Sí	No	No	No	No
Captura bytes brutos de solicitud/respuesta HTTP	Sí	No	No	Sí	No
Trazado a nivel de span	Sí	Sí	Sí	Sí	Sí
Exportación OTLP (Jaeger, Grafana Tempo)	Sí	No	Sí	No	Sí
Núcleo open-source	Sí	No	Sí	No	Sí
Solo local, sin servidor requerido	Sí	No	Autoalojado	No	Autoalojado

¹ LangSmith tiene LANGSMITH_TEST_CACHE / cassettes VCR (langsmith[vcr]) solo para Python + LangChain. Captura HTTP hacia api.openai.com pero no clientes HTTP arbitrarios, no registra bytes completos a nivel de cable y requiere una cuenta de LangSmith.

Elige LangSmith si tu equipo está en LangChain y necesita gestión de datasets, versionado de prompts y bucles de retroalimentación humana.

Elige Langfuse si quieres una pila de observabilidad totalmente open-source y autoalojable con almacenamiento robusto respaldado por Postgres.

Elige OpenLLMetry si tu equipo ya trabaja con OpenTelemetry y quiere spans estándar de gen_ai.* sin añadir un nuevo sistema de observabilidad.

Agent Observability no es un reemplazo para paneles y pipelines de evaluación. Resuelve el problema específico aguas arriba: reproducir una ejecución fallida concreta sin ningún coste de API LLM, para cualquier agente construido sobre cualquier cliente HTTP de Python.

---

Pruébalo con Docker

Agent Observability emite spans OTLP. Ejecuta una pila de observabilidad local para explorar árboles de trazas:

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

Inicia tres servicios (todos opcionales):

• Jaeger (http://localhost:16686) — ingesta de spans OTLP y UI de trazas
• Grafana (http://localhost:3000) — paneles y alertas
• Tempo (puerto 3200) — backend de almacenamiento de trazas a largo plazo

Luego apunta tu exportador al collector:

from agent_trace.exporters.otlp import OTLPExporter

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

---

Fallos reales que detecta record/replay

• La salida transitoria del modelo en el paso 6 provoca que una herramienta posterior falle — irreproducible con una re-ejecución, trivial de reproducir
• La respuesta de límite de tasa en el paso 3 activa una ruta de respaldo silenciosa — solo visible en los bytes de la fixture grabada, no en una re-ejecución en vivo
• Error de serialización del esquema de la herramienta antes del envío HTTP — capturado por LangGraphTracer.on_llm_error aunque nunca llega al interceptor (ver Limitaciones conocidas)
• Orden no determinista de herramientas en una rama paralela — la reproducción fija la secuencia exacta que produjo el fallo, así que estás depurando la ejecución real en lugar de una nueva
• Respuesta gRPC unary-stream de Gemini que solo falla en un límite de chunk específico — grabada una vez, reproducida byte por byte en lugar de re-disparar una llamada de streaming en vivo cada vez

---

Limitaciones conocidas

El modelo de captura de Agent Observability se basa en un interceptor HTTP (más callbacks instrumentados del framework para las integraciones bajo src/agent_trace/integrations/) y es local al proceso. Ese modelo tiene bordes reales — declarados aquí explícitamente para que queden claros antes de toparte con uno, no después:

• Solo local al proceso. La grabación/reproducción ocurre dentro del proceso de Python en el que importas agent_trace (httpx.Client(transport= RecordingTransport(...)), session.mount(..., RecordingAdapter(...)), o los monkeypatches de ReplayEngine.replay() — ver src/agent_trace/interceptor/). No puede observar ni reproducir llamadas realizadas por un servicio alojado de terceros que no ejecutes o despliegues tú mismo (p. ej. el asistente de chat alojado de un proveedor) — solo las llamadas salientes de tu propio proceso.

• La cobertura gRPC es parcial. src/agent_trace/interceptor/grpc_hook.py parchea grpc.secure_channel/grpc.insecure_channel (y los equivalentes de grpc.aio) para capturar el tráfico de Gemini/Vertex AI que evita httpx por completo — las llamadas unary-unary (p. ej. GenerateContent) y las llamadas síncronas unary-stream (p. ej. StreamGenerateContent) se graban y reproducen completamente. Las llamadas gRPC de client-streaming y bidireccional-streaming, y cualquier llamada de streaming de grpc.aio, no se capturan — esas van directamente a la red en vivo sin intercepción, tanto durante la grabación como (si se intenta) durante la reproducción.

• La captura comienza una vez que existe un objeto de solicitud. RecordingTransport. handle_request/AsyncRecordingTransport.handle_async_request (httpx_hook.py) y RecordingAdapter.send (requests_patch.py) solo se ejecutan cuando un httpx.Request/PreparedRequest completamente construido llega a ellos. Cualquier excepción lanzada antes de eso — mientras un SDK serializa un esquema de herramienta, construye cabeceras, o ensambla la llamada de otra forma, o incluso antes, durante la construcción normal de objetos de Python (p. ej. TypeError de abc.ABCMeta al instanciar una clase abstracta incorrectamente) — ocurre completamente aguas arriba de la superficie de captura del interceptor y produce cero filas de fixture. El callback de error propio de una integración de framework conectada (p. ej. LangGraphTracer.on_llm_error) sí captura dichas excepciones pre-HTTP cuando se propagan a través del propio try/except del framework — así que "invisible para el interceptor" no es lo mismo que "invisible en todas partes": depende de si una integración de framework está conectada para que la excepción pase por ella.

• Sin visibilidad en el código de print/display propio del framework. Las excepciones lanzadas dentro de la maquinaria local de logging/impresión/display — p. ej. la salida de Consola de rich, los hooks de display de IPython/Jupyter, disparados por el logging de verbose=True del propio framework — tienen cero tráfico HTTP y cero superficie de callback del framework. Ningún mecanismo de captura existente o planificado (interceptor HTTP, hook de transporte stdio de MCP, o cualquier integración de framework) observa esta categoría de fallo.

---

Seguridad

• Cadena de suministro: Los lanzamientos se construyen y publican mediante GitHub Actions (release.yml). La procedencia SLSA Nivel 2 mediante firma OIDC de Sigstore está verificada y funcionando (los paquetes .sigstore.json se producen genuinamente para cada artefacto de distribución); el SBOM (CycloneDX JSON + XML) se genera y se adjunta al lanzamiento de GitHub junto con los artefactos firmados.
• Escaneo de vulnerabilidades: dependabot.yml abre semanalmente PRs de actualización de pip y mensualmente de versiones de GitHub Actions. Las alertas de asesoramiento de seguridad de Dependabot, el escaneo de secretos y la protección de push con escaneo de secretos están habilitados en este repositorio.
• Seguridad de fixtures: Los archivos de fixture en ~/.agent-trace/runs/ contienen cuerpos completos de solicitudes y respuestas HTTP, incluyendo claves de API y contenidos de prompts. Añade .agent-trace/ y *.db a tu .gitignore.
• Divulgación: SECURITY.md — reporta vulnerabilidades a agent.obs.oss.security@gmail.com con un SLA de respuesta de 48 horas.

[!WARNING] Nunca hagas commit de una fixture generada contra una clave de API de producción. Los archivos de fixture capturan cuerpos completos de solicitudes/respuestas textualmente, así que una fixture con commit puede filtrar claves de API reales y contenidos de prompts en tu historial de git.

Avisos de seguridad upstream conocidos

• chromadb (solo extra opcional [crewai]): GHSA por una vulnerabilidad de inyección de código pre-autenticación que afecta a chromadb 1.0.0 hasta la última versión actual (1.5.9). El fix upstream (chroma-core/chroma PR #7237) se fusionó el 2026-07-07 pero no se ha publicado en ninguna versión de PyPI desde entonces — actualmente no hay una versión parcheada a la que fijarse. chromadb se incluye solo mediante el extra opcional de integración crewai (pip install agent-observability-trace-cli[crewai]), no se instala por defecto, y este proyecto nunca ejecuta un servidor Chroma con una API HTTP expuesta, así que la ruta de explotación real (un endpoint /api/v2/.../collections alcanzable por un atacante) no aplica al uso normal de este paquete. Si instalas el extra [crewai] y ejecutas tu propio servidor Chroma en otro lugar, sigue el aviso upstream y actualiza chromadb en cuanto se publique una versión corregida.

  Hoja de ruta futura: cuando chromadb publique una versión que contenga el fix, fija chromadb a esa versión inmediatamente. Si no se publica ningún fix antes de la próxima revisión de seguridad programada y el extra [crewai] muestra un uso real insignificante, eliminar el extra por completo es el plan de respaldo bajo consideración para cerrar este tema definitivamente.

---

FAQ

¿Qué es Agent Observability y en qué se diferencia de una herramienta típica de trazado de LLM?

Es una biblioteca de Python y CLI (agent-trace) que graba cada solicitud y respuesta HTTP que hace tu agente, textualmente, en una fixture SQLite local, y luego reproduce esos bytes exactos más tarde sin llamada de red. La mayoría de las herramientas de trazado, incluyendo LangSmith, Langfuse, Helicone y OpenLLMetry, te muestran lo que ocurrió durante una ejecución. Agent Observability además te permite reproducir esa ejecución exacta fuera de línea, de forma determinista, sin tocar la API en vivo. Ver "¿Por qué no usar simplemente LangSmith, Langfuse o Helicone?" arriba para el desglose completo de capacidades frente a esas cuatro herramientas.

¿Cómo funciona realmente la grabación/reproducción determinista?

La grabación parchea httpx.Client, httpx.AsyncClient y requests.Session en la capa de transporte (src/agent_trace/interceptor/) para capturar cada solicitud y respuesta saliente como bytes crudos en fixture.db. La reproducción instala un FixtureClock (src/agent_trace/core/clock.py) y sirve esos mismos bytes de vuelta en la secuencia original, así que la ruta de código, el árbol de spans y las marcas de tiempo coinciden con la grabación original. Las cifras de referencia citadas arriba (0.011% de sobrecarga de grabación, 0.93ms de latencia media de reproducción, 100% de fidelidad) provienen de benchmarks/test_overhead.py, benchmarks/test_replay_vs_live.py y benchmarks/test_fidelity.py en este repositorio, ejecutables tú mismo con uv run pytest benchmarks/.

¿Cómo lo instalo y qué plataformas soporta?

pip install agent-observability-trace-cli, o uv add agent-observability-trace-cli. Requiere Python 3.10 o superior y depende solo de httpx y rich, sin extensiones compiladas, así que se instala en cualquier lugar donde esas ruedas funcionen. CI (.github/workflows/ci.yml) pasa en Ubuntu, macOS y Windows, en Python 3.10 hasta 3.13. También se publica un wrapper npm, agent-observability-trace-cli (código fuente bajo npm/ en este repositorio), para equipos que prefieren npx/npm, pero igualmente invoca la CLI de Python internamente, así que el paquete de Python también debe estar instalado.

¿Cómo se compara esto con LangSmith específicamente?

El LANGSMITH_TEST_CACHE de LangSmith (cassettes estilo VCR, mediante langsmith[vcr]) es el equivalente integrado más cercano. Es solo Python y LangChain, captura llamadas HTTP a api.openai.com en lugar de a cualquier cliente HTTP, no graba bytes completos a nivel de cable, y requiere una cuenta de LangSmith. Agent Observability funciona con cualquier cliente HTTP de Python, más interceptores dedicados para tráfico gRPC, aiohttp, botocore y WebSocket, graba bytes completos de solicitudes y respuestas localmente, y no necesita cuenta ni servicio alojado. Elige LangSmith si ya estás en LangChain y quieres gestión de datasets, versionado de prompts y bucles de retroalimentación humana junto con el trazado. Elige Agent Observability si el objetivo es reproducir una ejecución fallida específica a costo cero de API, independientemente de qué SDK hizo la llamada.

¿Qué ocurre si la reproducción no encuentra una entrada de fixture coincidente?

Con AGENT_TRACE_NETWORK_GUARD=1 configurado, cualquier solicitud que falte en la fixture lanza NetworkGuardError inmediatamente en lugar de caer silenciosamente a una llamada en vivo. La causa más común es un cliente HTTP construido antes de entrar en el contexto de grabación o reproducción, ya que el parche solo aplica a clientes creados dentro del bloque start_trace/replay. Ver "Limitaciones conocidas" arriba para la lista completa de bordes, incluyendo cobertura parcial de streaming gRPC y excepciones pre-HTTP que nunca llegan al interceptor.

¿Captura agentes construidos sobre frameworks que no son de Python?

No. La captura es un interceptor de transporte HTTP de Python más callbacks instrumentados para las integraciones bajo src/agent_trace/integrations/ (LangGraph, CrewAI, AutoGen, LlamaIndex, Haystack, Agno, PydanticAI, Google GenAI y otros). Solo ve tráfico de tu propio proceso de Python. Los agentes construidos en otros lenguajes, o las llamadas realizadas por un servicio alojado de terceros que no ejecutes tú mismo, están fuera de su superficie de captura.

¿Son seguros los archivos de fixture para hacer commit en el control de versiones?

No por defecto. fixture.db contiene cuerpos completos de solicitudes y respuestas HTTP, lo que significa claves de API y contenidos de prompts siempre que aparezcan en cabeceras o payloads. Añade .agent-trace/ y *.db a .gitignore, y nunca hagas commit de una fixture grabada contra una clave de API de producción. Elimina o redacta los secretos primero si quieres conservar una fixture como activo de prueba de CI con commit.

¿Es gratuito para uso comercial?

Sí. El proyecto tiene licencia Apache 2.0 (ver LICENSE), que permite uso comercial, modificación y redistribución, incluso dentro de productos de código cerrado, sujeto a los términos de atribución y aviso de la propia licencia. No hay un nivel de pago separado ni una licencia comercial.

---

Contribuciones

• Lee CONTRIBUTING.md antes de abrir un PR
• Los primeros issues buenos están etiquetados en GitHub Issues
• El motor de reproducción (src/agent_trace/_replay/) requiere 80% de cobertura de pruebas — crítico para la corrección
• El interceptor (src/agent_trace/interceptor/) requiere 80% de cobertura de pruebas
• GitHub Discussions para preguntas de diseño e ideas

Apache 2.0. Las contribuciones son bienvenidas.

---

Construido por Rudrendu Paul y Sourav Nandy