아프니까 개발자다 아프니까 개발자다

RAG 파이프라인을 구성하는 세 가지 재료가 있다. 문서를 저장한 벡터 DB에서 검색해 오는 리트리버, 그 리트리버를 LLM이 호출할 수 있는 형태로 포장한 도구(@tool), 그리고 질문의 의도에 따라 어떤 도구를 몇 번 쓸지 스스로 결정하는 에이전트. 이 세 가지를 하나로 묶는 접착제가 create_agent다.이 글에서는 create_agent로 에이전트를 조립하는 방법부터 시작해, 단일 카테고리 질문과 복합 카테고리 질문이 내부에서 어떻게 다르게 처리되는지, 그리고 messages 배열을 읽어 에이전트 동작을 추적하는 방법까지 순서대로 살펴본다.1. create_agent로 RAG 에이전트 조립에이전트를 만드는 데 필요한 최소 재료는 세 가지다. LLM(model), 도구 리스트(tools), 그..

들어가며 — 도구 하나 더 추가했더니 RAG 호출이 줄었다로컬 챗봇에 도구를 하나씩 추가해 11개가 됐다. 지식금고 RAG, 공유 메모리, 첨부 검색, 이미지 분석, 웹 검색, 메모리 저장/회상, 캘린더, Claude CLI 자문, 외부 LLM 자문, 이미지 생성으로 구성된다. 모두 LangChain Tool 객체로 통일됐고 LangGraph ReAct에 묶여있다. 깔끔한 설계다.그런데 운영하다가 묘한 패턴을 봤다. 도구가 늘어날수록 작은 모델의 RAG 호출 빈도가 떨어진다. "어떤 도구를 써야 할지" 망설이다 그냥 답해버리는 경우가 늘어난 것이다. 도구가 풍부할수록 좋다는 직관과 반대다. 이번 글은 이 현상의 원인과, 두 가지 안전판 — _safe_tool wrapper와 allowed_tools 화이..

코드 속에 갇힌 AI 에이전트로컬 서버에서 Gemma 4 모델을 vLLM으로 서빙하고, LangGraph로 ReAct 에이전트를 만들어 RAG 검색, 웹 검색, 캘린더, 메모리 저장 등 7개 도구를 연결해 쓰고 있었습니다. 코드로는 잘 돌아가지만 몇 가지 불만이 있었습니다.에이전트가 어떤 도구를 호출했는지 확인하려면 로그 파일을 grep해야 합니다시스템 프롬프트 한 줄 바꾸려면 Python 코드를 수정하고 서버를 재시작해야 합니다새 도구를 추가하려면 코드 작성 → 테스트 → 배포 사이클을 돌아야 합니다실행 흐름을 파악하려면 코드를 머릿속으로 따라가야 합니다이걸 해결할 방법을 찾다가 n8n을 떠올렸습니다. 이미 셋업은 해놨지만 실제로 AI 에이전트 워크플로우에 써본 적은 없었거든요.n8n이 뭔가요?n8n은..

LLM 에이전트를 만들었다. 질문하면 답이 온다. 그런데 왜 그런 답을 했는지, 어디서 시간이 걸렸는지, 어떤 도구를 호출했는지 전혀 보이지 않는다. 에이전트는 블랙박스다. 이 블랙박스에 유리창을 달아주는 도구가 Langfuse다.Langfuse란 무엇인가Langfuse(Lang + Fuse)는 LLM 애플리케이션을 위한 오픈소스 관측성(observability) 플랫폼이다. 전기 퓨즈가 회로를 보호하고 모니터링하듯, LLM 앱 내부의 흐름을 추적하고 시각화한다.어떤 문제를 해결하는가LLM 앱은 전통적인 소프트웨어와 디버깅 방식이 다르다. 입력이 같아도 출력이 달라지고, 에이전트가 도구를 여러 번 호출하면서 내부 상태가 계속 바뀐다. 기존 로그만으로는 "에이전트가 왜 이런 판단을 내렸는지" 추적하기 어렵..

LangChain이 있는데 왜 LangGraph가 따로 필요할까? LLM 에이전트의 핵심 흐름이 일직선(Chain)이 아니라 순환하는 그래프(Graph)이기 때문입니다. 실제 코드를 따라가며, 이 그래프가 어떤 모양이고 왜 이런 구조가 되는지 풀어봅니다.Chain의 한계 — 직선은 판단을 못 한다LangChain의 기본 모델은 이름 그대로 Chain입니다. A → B → C 순서로 단계를 밟는 파이프라인이죠.# Chain 방식: 검색 → LLM → 출력 (순서 고정)chain = retriever | prompt | llm | output_parser이 구조는 "검색해서 답변해" 같은 단순 RAG에는 충분합니다. 하지만 이런 상황에서 막힙니다:검색 결과가 불충분하면? → 다시 검색해야 하는데, 체인은 뒤..