agent-observability

Agent Observability

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

---

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 costo de API. Si la falla fue causada por una salida transitoria del modelo, no puedes reproducirla en absoluto.

Agent Observability lo soluciona. Registra una vez. Reproduce sin conexión en 0.93 ms. Cero llamadas API. Cero costo.

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 para LangGraph:

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

Soporte para OpenAI Agents SDK:

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

Inicio rápido en 30 segundos con la CLI

# 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 --json para salida analizable por máquina, de modo que 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 hijo no puede hacerse estructurada). show no tiene modo --json propio. Acepta --errors-only para filtrar su salida a los spans fallidos. Consulta la referencia completa de la CLI a continuación para ver las banderas de cada subcomando.

¿Prefieres 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 recuperación posterior 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 utilizado por defecto en el SDK de Python de OpenAI v1.x y el SDK de Anthropic. El parche se instala en el momento del despacho de la solicitud, por lo que también cubre clientes construidos antes de que comience la grabación/reproducción (por ejemplo, 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]"

Agrégalo 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 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 inicia 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 la CLI

agent-trace tiene 7 subcomandos. Cada subcomando acepta -h/--help para el mismo detalle que se muestra 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	Predeterminado	Descripción
--json	off	Imprime JSON analizable 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	Requerido	Descripción
run_id	sí	ID de ejecución, p. ej. run_abc123def456.

Bandera	Predeterminado	Descripción
--errors-only	off	Solo imprime 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 transmisión, los intercambios de errores HTTP y los mismos diagnósticos entre spans que show imprime (clasificación de errores, spans de nodos duplicados, tormentas de reintentos, spans mal atribuidos, durabilidad de puntos de control, actualizaciones de tareas cero).

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

agent-trace inspect <run_id>

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

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

Bandera	Predeterminado	Descripción
--registered-tools	none	Lista separada por comas de nombres de herramientas registradas. Habilita la coincidencia difusa de nombres de llamadas a herramientas, compuestos con puntos, nombres de acciones ReAct no registrados y verificaciones de nombres de llamadas a herramientas no registrados.
--configured-host	none	El host del endpoint LLM configurado del framework. Habilita la verificación de discrepancia de host de endpoint.
--check-kwarg	none	Ruta de kwarg con puntos (p. ej. extra_body.chat_template_kwargs.thinking) que se espera que esté presente en el cable. Marca solicitudes donde está ausente.
--diff-field	none	Campo de respuesta para verificar presencia-en-cable-pero-ausente-corriente-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	none	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 GPTAssistantAgent /runs que aún envía instructions que ya no coinciden con lo que GET /assistants/{id} devuelve.
--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 analizable 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 diferencias a nivel de campo entre los cuerpos de solicitud/respuesta, además de una verificación de reinicio-vs-reanudación para un thread_id compartido de LangGraph (ver issue #161).

Argumento	Requerido	Descripción
run_id_a	sí	Primer ID de ejecución.
run_id_b	sí	Segundo ID de ejecución.

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

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

Ejecuta un proceso hijo con la grabación pre-habilitada 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, comience 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	Predeterminado	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)	none	Todo después de -- se ejecuta como el proceso hijo, p. ej. -- langgraph dev. Esto captura el resto de la línea de comandos, por lo que --run-id/--name/--json deben darse 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 todo el agente: 8 llamadas LLM más, 30 segundos más, otros $0.15 en costo de API. Si la falla fue causada por una respuesta específica de una herramienta o una salida transitoria del modelo, no puedes reproducirla en absoluto. Estás depurando contra un objetivo en movimiento.

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

---

Uso en CI: reproducción a costo cero

Registra una vez. Haz commit del fixture. Reproduce en cada ejecución de CI a costo 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 genera 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 sucedió. 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 100% de fidelidad.

La mayoría de las herramientas de observabilidad para agentes LLM son solo observación: te muestran una traza de lo que sucedió, pero reproducir una falla 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 spans determinista en reproducción	Sí	No	No	No	No
Captura bytes crudos de solicitud/respuesta HTTP	Sí	No	No	Sí	No
Trazado a nivel de spans	Sí	Sí	Sí	Sí	Sí
Exportación OTLP (Jaeger, Grafana Tempo)	Sí	No	Sí	No	Sí
Núcleo de código abierto	Sí	No	Sí	No	Sí
Solo local, sin servidor requerido	Sí	No	Auto-alojado	No	Auto-alojado

¹ 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 completamente de código abierto y auto-alojable con almacenamiento robusto respaldado por Postgres.

Elige OpenLLMetry si tu equipo ya usa OpenTelemetry y quiere spans estándar de gen_ai.* sin agregar un nuevo sistema de observabilidad.

Agent Observability no es un reemplazo para paneles y pipelines de evaluación. Resuelve el problema upstream específico: reproducir una ejecución fallida específica sin ningún costo 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 colector:

from agent_trace.exporters.otlp import OTLPExporter

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

---

Fallas reales que la grabación/reproducción detecta

• La salida transitoria del modelo en el paso 6 provoca que una herramienta posterior falle. No reproducible 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, visible solo en los bytes de la grabación, 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, por lo 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 fragmento específico, grabada una vez y 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 interceptor HTTP (además de callbacks instrumentados del framework para las integraciones bajo src/agent_trace/integrations/) y es local al proceso. Ese modelo tiene bordes reales, declarados explícitamente aquí para que queden claros antes de que te encuentres con uno, no después:

• Solo local al proceso. La grabación/reproducción ocurre dentro del proceso 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 hechas por un servicio alojado de terceros que no ejecutes o despliegues tú mismo (por ejemplo, el asistente de chat alojado de un proveedor). Solo ve las llamadas salientes de tu propio proceso.

• La cobertura de 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 tráfico de Gemini/Vertex AI que evita httpx por completo. Las llamadas unary-unary (por ejemplo, GenerateContent) y las llamadas síncronas unary-stream (por ejemplo, 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) 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 encabezados, o ensambla la llamada, o incluso antes durante la construcción de objetos Python simples (por ejemplo, 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 grabación. Un callback de error propio de una integración de framework conectada (por ejemplo, LangGraphTracer.on_llm_error) sí captura tales excepciones pre-HTTP cuando se propagan a través del propio try/except del framework, por lo 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 a través.

• Sin visibilidad en el código de impresión/visualización propio del framework. Excepciones lanzadas dentro de la maquinaria local de logging/impresión/visualización, por ejemplo, la salida de Consola de rich o los hooks de visualización de IPython/Jupyter, disparadas por el propio logging de verbose=True del 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). Se verifica que la procedencia SLSA Nivel 2 mediante firma OIDC de Sigstore funciona (.sigstore.json bundles genuinamente producidos 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 PRs semanales de actualización de versiones de pip y mensuales 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 las grabaciones: Los archivos de grabación 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 confirmes una grabación generada contra una clave de API de producción. Los archivos de grabación capturan cuerpos completos de solicitudes/respuestas textualmente, por lo que una grabación confirmada puede filtrar claves de API reales y contenidos de prompts en tu historial de git.

Avisos de seguridad conocidos de aguas arriba

• chromadb (solo extra opcional [crewai]): GHSA para 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 parche de aguas arriba (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 de integración opcional 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, por lo que la ruta de explotación real (un endpoint /api/v2/.../collections alcanzable por un atacante) no se aplica al uso normal de este paquete. Si instalas el extra [crewai] y ejecutas tu propio servidor Chroma en otro lugar, sigue el aviso de aguas arriba y actualiza chromadb tan pronto como se publique una versión corregida.

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

---

Preguntas frecuentes

¿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 grabación 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 sucedió durante una ejecución. Agent Observability además te permite reproducir esa ejecución exacta fuera de línea, de manera determinista, sin tocar la API en vivo. Consulta "¿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, por lo que la ruta de código, el árbol de spans y las marcas de tiempo coinciden con la grabación original. Los números de referencia citados 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, por lo que se instala en cualquier lugar donde esas ruedas estén disponibles. CI (.github/workflows/ci.yml) pasa en Ubuntu, macOS y Windows, en Python 3.10 a 3.13. Un envoltorio npm, agent-observability-trace-cli (código fuente bajo npm/ en este repositorio), también se publica para equipos que usan npx/npm, pero aún así invoca la CLI de Python internamente, por lo que el paquete de Python también debe instalarse.

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

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 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, además de 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 conjuntos de datos, 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é sucede si la reproducción no puede encontrar una entrada de grabación coincidente?

Con AGENT_TRACE_NETWORK_GUARD=1 configurado, cualquier solicitud que falte en la grabación 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 se aplica a clientes creados dentro del bloque start_trace/replay. Consulta "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 en 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 hechas por un servicio alojado de terceros que no ejecutas tú mismo, están fuera de su superficie de captura.

¿Son seguros los archivos de grabación para confirmarlos en 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 encabezados o cargas útiles. Añade .agent-trace/ y *.db a .gitignore, y nunca confirmes una grabación registrada contra una clave de API de producción. Elimina o redacta los secretos primero si quieres mantener una grabación como activo de prueba de CI confirmado.

¿Es gratuito para uso comercial?

Sí. El proyecto está licenciado bajo 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 problemas 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. Contribuciones bienvenidas.

---

Construido por Rudrendu Paul y Sourav Nandy