AI 에이전트를 위한 시간 이동 디버거를 구축했습니다.

Time-travel debugging for AI agents. Building multi-step AI agents (LangGraph, CrewAI, OpenHands) is painfully slow to debug. When your agent fails on step 8 out of 10, observability tools like LangSmith or LangFuse only show you what went wrong. To fix it, you patch the code and re-run all 10 steps from scratch. Every typo costs minutes of wall time and dollars in wasted tokens. Agent VCR records your agent's complete state at every step. When something breaks, you rewind to the failing step, edit the state, and resume execution from that exact point. No re-running the whole chain. LangSmith shows you what happened. Agent VCR lets you change it. pip install ai-agent-vcr from agent_vcr import VCRRecorder, VCRPlayer # Record your agent recorder = VCRRecorder() recorder.start_session("bug_hunt") # ... your agent code ... recorder.save() # Time-travel and fix player = VCRPlayer.load(".vcr/bug_hunt.vcr") state = player.goto_frame(2) # jump to step 2 state["prompt"] = "Fixed prompt" # fix the state player.resume(from_frame=2) # continue from there - Time Travel — Jump back to any step. Full state snapshot at every node. - State Injection & Resume — Edit the state at any frame — fix a prompt, patch tool output, inject context — then resume mid-chain. - ACID Transactions — Wrap agent execution in real database-style transactions backed by git. Rollback physically reverts files on disk, not just in-memory state. - Golden Run Cache — Save successful runs as replayable paths. Next time you hit the same task, skip all LLM calls. Same task, zero tokens, instant. - React Dashboard — Run vcr-server , openlocalhost:8000 . Glassmorphism UI for inspecting state, viewing JSON diffs, live WebSocket streaming. - TUI Debugger — Run vcr-tui in your terminal. Navigate frames, presse to edit state, pressr to resume. - Visual Diffs — Color-coded state mutation tracking in Dashboard and TUI. - DAG Visualization — See parallel execution branches, search/filter sessions by tags. - Framework Agnostic — 1-line integration with LangGraph, CrewAI, or raw Python. - Git-Friendly Storage — JSONL files, version controllable, append-only. - Production Safe — str: return "findings..." Install with: pip install "ai-agent-vcr[crewai]" See examples/crewai_integration.py for a full runnable demo. Agent VCR uses JSONL (JSON Lines): {"type": "session", "data": {"session_id": "abc123", "created_at": "2024-01-01T00:00:00Z", ...}} {"type": "frame", "data": {"frame_id": "...", "node_name": "planner", "input_state": {...}, "output_state": {...}, ...}} {"type": "frame", "data": {...}} - Human-readable - Git-diffable - Append-only (efficient for streaming) - Line-by-line parsing (no need to load the entire file) Recording overhead is continuously benchmarked in CI to stay under 5ms per frame. pytest tests/benchmarks/ -v class VCRRecorder: def start_session( self, session_id: str = None, parent_session_id: str = None, forked_from_frame: int = None, metadata: dict = None, tags: list[str] = None, ) -> Session def record_step( self, node_name: str, input_state: dict, output_state: dict, metadata: FrameMetadata = None, frame_type: FrameType = FrameType.NODE_EXECUTION, ) -> Frame def record_llm_call(...) def record_tool_call(...) def record_error(...) def save(self) -> Path def fork(self, from_frame: int, ...) -> VCRRecorder class VCRPlayer: @classmethod def load(cls, filepath: str) -> VCRPlayer def goto_frame(self, index: int) -> dict def get_frame(self, index: int) -> Frame def list_nodes(self) -> list[str] def get_errors(self) -> list[Frame] def compare_frames(self, a: int, b: int) -> dict def resume(self, agent_callable: Callable, config: ResumeConfig) -> str def export_state(self, frame_index: int) -> dict class ACIDWorkspace: def __init__(self, workspace_path: str, recorder: VCRRecorder = None) def begin(self, session_id: str) -> None def savepoint(self, state: dict, node_name: str) -> None def rollback(self, to_frame_index: int) -> None def commit(self) -> None class GoldenRunCache: def __init__(self, cache_dir: str = ".vcr/golden") def save_golden_run(self, task: str, recorder: VCRRecorder) -> str def replay(self, task: str) -> tuple[list[dict], CostLedger] def invalidate(self, task: str) -> bool class ResumeConfig: from_frame: int # Frame to resume from new_session_id: str = None # Optional ID for forked session state_overrides: dict = {} # State changes to apply mode: ResumeMode = FORK # FORK, REPLAY, or MOCK skip_nodes: list[str] = [] # Nodes to skip during replay inject_mocks: dict = {} # Mock values for dependencies See the examples/ directory: basic_usage.py — Recording and playbacktime_travel_demo.py — Full time-travel workflowlanggraph_integration.py — LangGraph auto-instrumentationacid_golden_run.py — ACID transactions and Golden Run Cache python examples/acid_golden_run.py Contributions welcome. See CONTRIBUTING.md for guidelines. git clone https://github.com/agent-vcr/agent-vcr.git cd agent-vcr pip install -e ".[dev]" pytest tests/unit/ -v pyte