AgentLens: 멀티스텝 AI 에이전트를 위한 로컬 우선 디버거 및 추적 포킹 도구

커뮤니티 반응

작성자가 초기 단계의 프로젝트에 대한 피드백을 요청 중이며, 로컬 우선(Local-first) 방식과 MIT 라이선스의 오픈소스 구조에 대해 긍정적인 관심이 예상된다.

합의점 vs 논쟁점

합의점

멀티스텝 에이전트 디버깅 시 전체 체인을 재실행하는 것은 비효율적이다.
로컬 환경에서 데이터를 관리하는 디버깅 도구가 개발 워크플로우에 유용하다.

실용적 조언

에이전트가 예상치 못한 도구 호출 결과를 냈을 때, Hybrid 모드를 사용하여 API 비용을 아끼면서 LLM의 수정된 반응만 테스트해 볼 것
LangChain 프로젝트에 AgentLensCallbackHandler를 추가하여 로컬 환경에서 즉시 디버깅 환경을 구축할 것

섹션별 상세

AgentLens는 멀티스텝 에이전트의 실행 과정을 상세히 기록하고 사용자가 임의의 지점에서 실행 흐름을 분기(Fork)할 수 있게 한다. 사용자는 특정 LLM 호출이나 도구 실행 결과(Span)를 클릭하여 내용을 직접 수정한 뒤, 해당 시점부터 이후 단계들을 다시 실행하며 결과를 비교할 수 있다. 이는 전체 체인을 처음부터 다시 실행하지 않고도 특정 입력 변화가 결과에 미치는 영향을 파악하는 데 유용하다.

세 가지 재실행 모드를 통해 비용과 정확도 사이의 균형을 조절할 수 있다. Deterministic 모드는 실제 API 호출 없이 하위 단계들을 stale 상태로 표시하며, Live 모드는 모든 하위 단계를 실제 API로 재실행한다. Hybrid 모드는 LLM 호출은 실제 API를 사용하되 도구 호출은 기존에 기록된 데이터를 반환하여 부수 효과(Side effects) 없이 모델의 반응 변화만 확인할 수 있다.

LangChain 및 LangGraph와의 통합을 위해 전용 콜백 핸들러(Callback Handler)를 제공한다. AgentLensCallbackHandler를 초기화하고 graph.invoke의 설정값에 전달하는 간단한 코드로 기존 프로젝트에 추적 기능을 추가할 수 있다. 이 외에도 OpenAI Agents SDK, CrewAI 등 다양한 프레임워크와 원시 API 클라이언트를 지원한다.

python

from agentlens.integrations.langchain import AgentLensCallbackHandler

with AgentLensCallbackHandler(trace_name="my_agent") as handler:
    graph.invoke(input, config={"callbacks": [handler]})

LangChain/LangGraph 프로젝트에 AgentLens 콜백 핸들러를 통합하여 실행 과정을 추적하는 예시

용어 해설

에이전트 렌즈(AgentLens): — 멀티스텝 AI 에이전트의 실행 과정을 추적하고 특정 지점에서 실행 흐름을 수정하여 재시뮬레이션할 수 있게 돕는 로컬 우선 디버깅 도구이다. SQLite를 기반으로 로컬 환경에서 작동하며, LangChain 및 LangGraph와 쉽게 통합된다.
추적 포킹(Trace Forking): — 이미 실행된 에이전트의 추적 로그 중 특정 단계(Span)를 선택하여 그 출력을 수정하고, 해당 시점부터 이후의 과정을 다시 실행해 보는 기법이다. 전체 체인을 재실행하지 않고도 특정 변경 사항의 영향을 즉각 확인할 수 있다.
콜백 핸들러(Callback Handler): — 프레임워크의 실행 주기 중 특정 이벤트가 발생할 때 호출되는 인터페이스이다. LangChain에서 에이전트의 입력, 출력, 도구 호출 데이터를 AgentLens와 같은 외부 모니터링 도구로 전달하는 역할을 수행한다.

코드 예제

bash

pip install agentlens-xray agentlens
agentlens serve

AgentLens 설치 및 로컬 서버 실행 명령

언급된 도구

AgentLens추천링크

로컬 우선 에이전트 디버거 및 추적 도구

LangChain중립

LLM 애플리케이션 프레임워크

LangGraph중립

상태 유지 멀티 에이전트 오케스트레이션

언급된 리소스

GitHubAgentLens GitHub Repository