LLM 도구 호출 오류 해결을 위한 optulus-anchor 라이브러리 공개

실용적 조언

pip install optulus-anchor 명령어로 라이브러리를 설치하여 즉시 테스트 가능하다.
LangGraph 사용자라면 AnchorToolNode를 사용하여 기존 노드를 쉽게 대체하고 검증 기능을 추가할 수 있다.
anchor report --hours 24 명령어를 사용하여 로컬 SQLite에 저장된 트레이스 로그를 간편하게 확인할 수 있다.

섹션별 상세

LLM이 도구 호출 시 잘못된 데이터 타입을 전달하여 발생하는 런타임 오류 문제를 제기했다. 모델이 정수형(int)을 기대하는 도구에 문자열("five")을 전달할 경우 즉각적인 에러 없이 후속 단계에서 실패하여 원인 파악이 어렵다는 점을 지적했다. 이를 해결하기 위해 Pydantic 스키마를 활용하여 런타임에 입출력을 검증하는 방식을 도입했다.

python

search_docs(limit="five") # fails ambiguously downstream

모델이 정수형 인자에 문자열을 전달하여 발생하는 전형적인 오류 예시

optulus-anchor는 Python 데코레이터 형태로 구현되어 도구 호출 과정을 구조화된 이벤트로 기록한다. 모든 트레이스 이벤트는 SQLite에 저장되며 전용 CLI 명령어를 통해 지난 24시간 동안의 기록을 조회할 수 있다. 이는 에이전트의 다단계 추론 과정에서 발생한 데이터 흐름을 투명하게 시각화하여 디버깅 효율을 높인다.

오류 발생 시 모델이 스스로 수정하도록 유도하는 self_correct 모드를 지원한다. 잘못된 파라미터가 감지되면 PARAM_FAIL 이벤트를 발생시키고 수정 프롬프트를 LLM에 다시 전달하여 올바른 인자로 재시도하게 만든다. 이러한 루프 메커니즘은 개발자의 수동 개입 없이도 에이전트의 실행 성공률을 높이는 데 기여한다.

LangGraph와의 호환성을 위해 AnchorToolNode라는 드롭인 교체 기능을 제공한다. 기존 LangGraph 워크플로에 최소한의 코드 수정으로 통합이 가능하며 Apache 2.0 라이선스로 배포되어 상용 프로젝트에서도 자유롭게 활용할 수 있다. 현재 제작자는 실제 운영 환경에서의 수정 루프 동작에 대한 커뮤니티의 피드백을 요청하고 있다.

용어 해설

도구 호출(Tool Calling): — LLM이 외부 API나 함수를 실행하기 위해 필요한 인자를 생성하는 과정이다. 모델이 문자열을 정수형으로 잘못 전달하는 등의 타입 오류가 발생하면 전체 워크플로가 중단될 수 있어 정밀한 제어가 중요하다.
자기 수정(Self-Correction): — LLM이 생성한 결과물에 오류가 있을 때, 오류 메시지를 다시 모델에게 입력으로 제공하여 스스로 수정된 결과를 생성하도록 유도하는 기법이다. 에이전트의 자율성과 신뢰성을 높이는 핵심 메커니즘이다.
Pydantic 스키마(Pydantic Schema): — Python에서 데이터 타입 검증과 설정을 위해 널리 사용되는 라이브러리이다. LLM이 도구에 전달하는 인자가 정의된 데이터 타입과 일치하는지 런타임에 검증하여 데이터 무결성을 보장한다.

언급된 도구

optulus-anchor추천링크

LLM 도구 호출 입력/출력 검증 및 자동 수정 루프 지원 라이브러리

LangGraph중립

에이전트 워크플로 구축 프레임워크

언급된 리소스

GitHubOptulus Anchor GitHub Repository