fork & replay 기능을 갖춘 로컬 에이전트 디버거를 만들었습니다 - 단계별 수정 및 실시간 API 호출 재실행 가능
I built a local agent debugger with "fork & replay" - edit any step and re-run the rest with live API calls
핵심 요약
에이전트의 특정 단계를 수정하고 실시간 API 호출로 재실행하여 디버깅할 수 있는 로컬 오픈소스 도구 'AgentLens' 소개.
- Fork & Replay — 에이전트의 특정 단계 출력을 수정하고 이후 과정을 실시간으로 재실행함.
- 다양한 재실행 모드 — 결정론적, 실시간, 하이브리드 모드를 지원하여 효율적인 디버깅 환경 제공.
- 간편한 통합 — LangChain, LangGraph, CrewAI 등 주요 프레임워크와 콜백 핸들러로 쉽게 연동됨.
- 로컬 우선 설계 — SQLite 기반으로 클라우드 계정 없이 로컬에서 안전하게 트레이스 분석 가능.
안녕하세요,
개인 금융 관련 다단계 에이전트(거래 분류, 이상 징후 표시, 보고서 생성)를 만들고 있었는데, 항상 같은 벽에 부딪혔습니다. 에이전트가 체인 중간에 멈추면 전체를 다시 실행하지 않고는 이유를 알아낼 방법이 없었거든요.
LangSmith 트레이스는 무슨 일이 일어났는지 확인하는 데 도움이 되었지만, 전체 상위 단계를 다시 실행하거나 도구를 다시 호출하지 않고도 한 단계의 출력만 수정해서 LLM이 다르게 행동했을지 확인하고 싶었습니다.
그래서 AgentLens를 만들었습니다. 트레이스를 캡처하고 어느 단계에서든 포크(fork)할 수 있게 해주는 로컬 우선 디버거입니다:
-
모든 LLM 호출, 도구 호출, 체인 단계를 포함한 전체 트레이스 확인
-
아무 스팬(span)이나 클릭하여 출력 수정
-
재실행(replay) - 하위 단계들이 실제 API 호출과 함께 다시 실행됨
-
원본과 재실행 트레이스의 나란히 비교(side-by-side diff)
세 가지 재실행 모드:
-
Deterministic - API 호출 없음, 하위 단계를 단순히 stale(오래됨)로 표시 (무료, 즉시)
-
Live - 하위 단계 전체를 실제 API 호출로 재실행
-
Hybrid - LLM 호출은 실시간으로 수행, 도구 호출은 기록된 데이터를 반환 (부작용 없음)
LangChain/LangGraph 통합을 지원합니다 — 콜백 핸들러를 전달하기만 하면 됩니다:
from agentlens.integrations.langchain import AgentLensCallbackHandler
with AgentLensCallbackHandler(trace_name="my_agent") as handler:
graph.invoke(input, config={"callbacks": [handler]})
OpenAI Agents SDK, CrewAI, 그리고 원시 OpenAI/Anthropic 클라이언트와도 작동합니다.
모든 것이 로컬(SQLite, 클라우드 계정 없음)이며, MIT 라이선스 오픈 소스입니다.
pip install agentlens-xray
agentlens serve
GitHub: https://github.com/BugsBunnyWanders/agentlens
아직 초기 단계라 피드백을 진심으로 환영합니다. 무엇이 부족한가요? 여러분의 워크플로우에 유용하게 만들려면 무엇이 필요할까요?
