500라인 이하 코드로 구현한 Provider 독립적 AI Agent Loop 프레임워크

What I learned building an AI agent loop in Go

Lucas Neves Pereira2026년 5월 17일7분intermediate

AI 요약

Context

특정 유스케이스에 종속된 하드코딩 구조로 인해 새로운 도구 및 환경 확장 시 코드 전면 수정이 필요한 한계 발생. LLM Provider별 상이한 Tool Calling 규격으로 인한 강한 결합도 해결을 위해 재사용 가능한 프레임워크 설계 필요.

Generic Block 타입(text, tool_use, tool_result) 도입을 통한 LLM Provider 간 인터페이스 추상화
stop_reason 대신 tool_use 블록의 존재 여부를 기반으로 한 루프 종료 조건 설정으로 토큰 제한 상황에서의 동작 정확성 확보
모델의 Text 응답과 Tool Call을 단일 메시지로 묶어 전달하는 구조를 통해 API 요청 시 Tool ID 참조 무결성 유지
다중 Tool 호출 결과를 단일 User 메시지에 통합 배치하여 모델의 컨텍스트 윈도우 내 매핑 구조 최적화
Tool 실행 오류를 Exception이 아닌 is_error: true 형태의 데이터로 모델에 환류하여 자가 수정(Self-correction) 유도
Tool 인터페이스를 통해 Schema 정의와 Run 로직을 분리하여 Bash, Web Fetch 등 다양한 기능을 플러그인 형태로 확장

실천 포인트

1. LLM API 설계 시 Provider별 응답 포맷 차이를 제거하기 위해 내부 추상화 계층(Internal Representation)을 구축했는가?

2. Tool Call 결과 반환 시 개별 메시지가 아닌 단일 메시지로 그룹화하여 세션 무결성을 보장하고 있는가?

3. 도구 실행 실패 시 프로세스를 중단하지 않고 에러 내용을 모델에 전달하여 추론 루프 내에서 해결하도록 설계했는가?

4. 루프 종료 조건을 API의 Stop Reason에 의존하지 않고 실제 콘텐츠의 도구 사용 여부로 판별하고 있는가?

태그